# Encoding Pipeline Design

## Purpose
The encoding pipeline transforms source videos into Roku-compatible HLS assets.

It also supports ingest from church-owned YouTube videos.

## Pipeline Overview
```text
Video Upload / YouTube Download
            |
            v
Azure Blob Storage (/source)
            |
            v
Encoding Queue
            |
            v
FFmpeg Worker
            |
            v
Azure Blob Storage (/hls)
            |
            v
Metadata Extractor
            |
            v
Video Catalog Update
```

## Supported Inputs
- manually uploaded MP4 files
- archived MP4 files
- church-owned YouTube videos downloaded by staff

## Recommended Rule
Use YouTube only for **church-owned** content. Keep Azure as the system of record for source masters.

## Ingest Workflow

### Manual upload
1. Staff uploads MP4
2. File stored in `/source`
3. Job created in encoding queue

### YouTube ingest
1. Staff downloads owned video from YouTube Studio
2. Uploads to `/source`
3. Job created in encoding queue

## Encoding Output
Each source video is encoded once into HLS assets.

Example:
```text
/source/sermon-2026-03-01.mp4
    ->
/hls/sermon-2026-03-01/
    master.m3u8
    1080p/index.m3u8
    1080p/seg0001.ts
    720p/index.m3u8
    720p/seg0001.ts
    480p/index.m3u8
```

## Example FFmpeg Command
```bash
ffmpeg -i sermon.mp4   -c:v libx264   -c:a aac   -hls_time 6   -hls_playlist_type vod   -hls_segment_filename "seg%03d.ts"   index.m3u8
```

## Metadata to Store
For each encoded asset store:
- videoId
- durationSec
- sourcePath
- hls master path
- available renditions
- segment count
- thumbnail path
- encoding status

Example:
```json
{
  "videoId": "sermon-2026-03-01",
  "durationSec": 3120,
  "sourcePath": "/source/sermon-2026-03-01.mp4",
  "hlsMasterPath": "/hls/sermon-2026-03-01/master.m3u8",
  "variants": ["1080p", "720p", "480p"],
  "status": "ready"
}
```

## Failure Handling
If encoding fails:
- mark status as `failed`
- preserve source file
- log FFmpeg output
- allow retry

## Suggested Worker States
- queued
- processing
- ready
- failed

## Deployment Options
| Component | Recommended Deployment |
|---|---|
| Queue | Azure Storage Queue or Service Bus |
| Worker | Azure Container Apps or VM |
| Source storage | Azure Blob |
| Output storage | Azure Blob |

## Operational Guidance
- encode once, reuse many times
- do not transcode on Roku request
- keep source masters
- generate HLS ahead of scheduling