# 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.