Hans-R-D/encoder-pipeline

1# Video Encoder Pipeline Documentation2 3## Introduction4The 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.5 6## Quickstart Guide7 8### Prerequisites9- Python 3.8+10- FFmpeg installed system-wide11- Valkey (Redis) server running12 13### Installation141. Clone the repository:15   ```bash16   git clone https://github.com/yourusername/video-encoder-pipeline.git17   cd video-encoder-pipeline18   ```19 202. Install the required dependencies:21   ```bash22   pip install -r requirements.txt23   ```24 25### Running the Server261. Start the FastAPI server:27   ```bash28   python run.py29   ```30 312. The server will be available at `http://localhost:8000`.32 33### Basic Usage341. Upload a video:35   ```bash36   curl -X POST -F "file=@input.mp4" http://localhost:8000/upload37   ```38 392. Check encoding status:40   ```bash41   curl http://localhost:8000/status/{job_id}42   ```43 443. Generate a token for playback:45   ```bash46   curl http://localhost:8000/token/{job_id}47   ```48 494. Play encoded video:50   ```bash51   curl http://localhost:8000/play/{job_id}?token={valid_token}52   ```53 54## API Reference55 56### Endpoints57 58#### Upload Video59- **Endpoint**: `/upload`60- **Method**: `POST`61- **Description**: Uploads a video file for encoding.62- **Parameters**:63  - `file`: The video file to upload.64- **Response**:65  - `job_id`: The ID of the encoding job.66 67#### Get Encoding Status68- **Endpoint**: `/status/{job_id}`69- **Method**: `GET`70- **Description**: Retrieves the encoding status of a job.71- **Parameters**:72  - `job_id`: The ID of the encoding job.73- **Response**:74  - `job_id`: The ID of the encoding job.75  - `progress`: The encoding progress (0.0 to 1.0).76 77#### Generate Token78- **Endpoint**: `/token/{job_id}`79- **Method**: `GET`80- **Description**: Generates a token for secure playback.81- **Parameters**:82  - `job_id`: The ID of the encoding job.83- **Response**:84  - `token`: The generated token.85 86#### Play Encoded Video87- **Endpoint**: `/play/{job_id}`88- **Method**: `GET`89- **Description**: Streams the encoded video.90- **Parameters**:91  - `job_id`: The ID of the encoding job.92  - `token`: The generated token.93- **Response**:94  - The HLS playlist for the encoded video.95 96## Architecture Overview97 98The video encoder pipeline consists of the following components:99 1001. **FastAPI**: Handles API requests and responses.1012. **Valkey (Redis)**: Manages job queuing and progress tracking.1023. **FFmpeg**: Performs video encoding into multiple resolutions and bitrates.1034. **HMAC**: Ensures secure access to encoded videos.104 105## Encoding Profiles106 107The pipeline supports the following encoding profiles:108 109- **1080p**: 1920x1080, 5000 kbps video, 128 kbps audio110- **720p**: 1280x720, 2500 kbps video, 128 kbps audio111- **480p**: 854x480, 1000 kbps video, 96 kbps audio112- **240p**: 426x240, 400 kbps video, 64 kbps audio113 114## Security Considerations115 116The pipeline uses HMAC for secure access to encoded videos. Each video playback request requires a valid token generated using the `/token/{job_id}` endpoint.117 118## Troubleshooting119 120### Common Issues121 1221. **FFmpeg Not Found**: Ensure FFmpeg is installed and accessible in the system PATH.1232. **Job Not Found**: Ensure the `job_id` is correct and the job has been enqueued.1243. **Invalid Token**: Ensure the token is generated using the `/token/{job_id}` endpoint and is valid.125 126### Solutions127 1281. **FFmpeg Not Found**: Install FFmpeg and add it to the system PATH.1292. **Job Not Found**: Verify the `job_id` and ensure the job has been enqueued.1303. **Invalid Token**: Generate a new token using the `/token/{job_id}` endpoint.131