vthumbs
vthumbs is a lightweight Node.js microservice that generates a JPEG thumbnail from a video URL using ffmpeg. It is designed to be simple to run, easy to integrate, and suitable for local development or containerized deployments.
Features
- Generate a thumbnail image from a remote video URL
- In-memory thumbnail caching for repeated requests
- Simple HTTP API for easy integration with web and backend services
- Fast startup with minimal configuration
- Container-ready setup with Docker
- Health endpoint for basic service monitoring
Requirements
- Node.js 18+
- npm 9+
- ffmpeg available on your system path (for local, non-Docker runs)
Quick Start
Run locally in a few steps:
npm install
PORT=3100 npm start
The service will be available at:
http://localhost:3100
Environment Variables
| Variable | Default | Description |
|---|---|---|
| PORT | 3100 | HTTP port used by the service |
Docker Setup
Build and run the container:
docker build -t vthumbs:local .
docker run --rm -p 3100:3100 -e PORT=3100 vthumbs:local
Once running, call the API at:
http://localhost:3100
API Documentation
Generate Thumbnail
Endpoint:
GET /thumbnail?url=VIDEO_URL
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| url | Yes | string | Publicly reachable video URL to process |
Optional parameters:
- None currently
Success Response
- Status: 200 OK
- Content-Type: image/jpeg
- Body: binary JPEG image bytes
Error Responses
| Status | Condition | Example Response |
|---|---|---|
| 400 Bad Request | Missing url query parameter | { "error": "Missing 'url' query parameter" } |
| 500 Internal Server Error | Thumbnail generation failed | { "error": "Failed to generate thumbnail" } |
| 500 Internal Server Error | Video processing pipeline failed | { "error": "Failed to process video" } |
Health Check
Endpoint:
GET /health
Response:
{"status":"ok"}
Example curl Commands
Generate and save a thumbnail image:
curl -L "http://localhost:3100/thumbnail?url=https://example.com/video.mp4" --output thumbnail.jpg
Preview response headers for a thumbnail request:
curl -I "http://localhost:3100/thumbnail?url=https://example.com/video.mp4"
Health check request:
curl "http://localhost:3100/health"
Missing required query parameter:
curl "http://localhost:3100/thumbnail"
License
This project is licensed under the MIT License. See LICENSE for full details.