DOCS.md

# Video Encoder Pipeline Documentation

## Introduction
The Video Encoder Pipeline is a robust solution for encoding videos into multiple resolutions and bitrates, suitable for Video on Demand (VOD) services. This pipeline leverages FastAPI for the API, Valkey (Redis) for job queuing, and FFmpeg for video encoding.

## Quickstart Guide

### Prerequisites
- Python 3.8+
- FFmpeg installed system-wide
- Valkey (Redis) server running

### Installation
1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/video-encoder-pipeline.git
   cd video-encoder-pipeline
   ```

2. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

### Running the Server
1. Start the FastAPI server:
   ```bash
   python run.py
   ```

2. The server will be available at `http://localhost:8000`.

### Basic Usage
1. Upload a video:
   ```bash
   curl -X POST -F "file=@input.mp4" http://localhost:8000/upload
   ```

2. Check encoding status:
   ```bash
   curl http://localhost:8000/status/{job_id}
   ```

3. Generate a token for playback:
   ```bash
   curl http://localhost:8000/token/{job_id}
   ```

4. Play encoded video:
   ```bash
   curl http://localhost:8000/play/{job_id}?token={valid_token}
   ```

## API Reference

### Endpoints

#### Upload Video
- **Endpoint**: `/upload`
- **Method**: `POST`
- **Description**: Uploads a video file for encoding.
- **Parameters**:
  - `file`: The video file to upload.
- **Response**:
  - `job_id`: The ID of the encoding job.

#### Get Encoding Status
- **Endpoint**: `/status/{job_id}`
- **Method**: `GET`
- **Description**: Retrieves the encoding status of a job.
- **Parameters**:
  - `job_id`: The ID of the encoding job.
- **Response**:
  - `job_id`: The ID of the encoding job.
  - `progress`: The encoding progress (0.0 to 1.0).

#### Generate Token
- **Endpoint**: `/token/{job_id}`
- **Method**: `GET`
- **Description**: Generates a token for secure playback.
- **Parameters**:
  - `job_id`: The ID of the encoding job.
- **Response**:
  - `token`: The generated token.

#### Play Encoded Video
- **Endpoint**: `/play/{job_id}`
- **Method**: `GET`
- **Description**: Streams the encoded video.
- **Parameters**:
  - `job_id`: The ID of the encoding job.
  - `token`: The generated token.
- **Response**:
  - The HLS playlist for the encoded video.

## Architecture Overview

The video encoder pipeline consists of the following components:

1. **FastAPI**: Handles API requests and responses.
2. **Valkey (Redis)**: Manages job queuing and progress tracking.
3. **FFmpeg**: Performs video encoding into multiple resolutions and bitrates.
4. **HMAC**: Ensures secure access to encoded videos.

## Encoding Profiles

The pipeline supports the following encoding profiles:

- **1080p**: 1920x1080, 5000 kbps video, 128 kbps audio
- **720p**: 1280x720, 2500 kbps video, 128 kbps audio
- **480p**: 854x480, 1000 kbps video, 96 kbps audio
- **240p**: 426x240, 400 kbps video, 64 kbps audio

## Security Considerations

The pipeline uses HMAC for secure access to encoded videos. Each video playback request requires a valid token generated using the `/token/{job_id}` endpoint.

## Troubleshooting

### Common Issues

1. **FFmpeg Not Found**: Ensure FFmpeg is installed and accessible in the system PATH.
2. **Job Not Found**: Ensure the `job_id` is correct and the job has been enqueued.
3. **Invalid Token**: Ensure the token is generated using the `/token/{job_id}` endpoint and is valid.

### Solutions

1. **FFmpeg Not Found**: Install FFmpeg and add it to the system PATH.
2. **Job Not Found**: Verify the `job_id` and ensure the job has been enqueued.
3. **Invalid Token**: Generate a new token using the `/token/{job_id}` endpoint.