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:

   git clone https://github.com/yourusername/video-encoder-pipeline.git
   cd video-encoder-pipeline
   

2. Install the required dependencies:

   pip install -r requirements.txt
   

Running the Server

1. Start the FastAPI server:

   python run.py
   

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

Basic Usage

1. Upload a video:

   curl -X POST -F "file=@input.mp4" http://localhost:8000/upload
   

2. Check encoding status:

   curl http://localhost:8000/status/{job_id}
   

3. Generate a token for playback:

   curl http://localhost:8000/token/{job_id}
   

4. Play encoded video:

   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.