forked from coracle/vthumbs
135 lines
2.6 KiB
Markdown
135 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
npm install
|
|
PORT=3100 npm start
|
|
```
|
|
|
|
The service will be available at:
|
|
|
|
```text
|
|
http://localhost:3100
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
| --- | --- | --- |
|
|
| PORT | 3100 | HTTP port used by the service |
|
|
|
|
## Docker Setup
|
|
|
|
Build and run the container:
|
|
|
|
```bash
|
|
docker build -t vthumbs:local .
|
|
docker run --rm -p 3100:3100 -e PORT=3100 vthumbs:local
|
|
```
|
|
|
|
Once running, call the API at:
|
|
|
|
```text
|
|
http://localhost:3100
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
### Generate Thumbnail
|
|
|
|
Endpoint:
|
|
|
|
```http
|
|
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:
|
|
|
|
```http
|
|
GET /health
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"status":"ok"}
|
|
```
|
|
|
|
## Example curl Commands
|
|
|
|
Generate and save a thumbnail image:
|
|
|
|
```bash
|
|
curl -L "http://localhost:3100/thumbnail?url=https://example.com/video.mp4" --output thumbnail.jpg
|
|
```
|
|
|
|
Preview response headers for a thumbnail request:
|
|
|
|
```bash
|
|
curl -I "http://localhost:3100/thumbnail?url=https://example.com/video.mp4"
|
|
```
|
|
|
|
Health check request:
|
|
|
|
```bash
|
|
curl "http://localhost:3100/health"
|
|
```
|
|
|
|
Missing required query parameter:
|
|
|
|
```bash
|
|
curl "http://localhost:3100/thumbnail"
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See LICENSE for full details.
|