transcode_bench/README.md

# Video Transcoding Benchmark

A simple CLI tool to benchmark video transcoding performance on your system. Measures how many simultaneous 1080p H.264 → 720p H.265 transcodes can be performed in real-time or better.

## Features

- **Hardware Acceleration Support**: Automatically detects and uses available hardware acceleration:
  - NVIDIA NVENC (CUDA)
  - Intel Quick Sync Video (QSV)
  - AMD AMF/VCE
  - Apple VideoToolbox (macOS/iOS ARM)
  - VA-API (Linux Intel/AMD)
  - Falls back to software encoding (libx264) if no hardware acceleration available

- **Cross-Platform**: Works on Linux, macOS, and Windows
- **Cross-Architecture**: Supports both Intel/AMD x86_64 and ARM architectures
- **Simple Output**: Produces a single number representing transcoding capacity

## Requirements

- Python 3.6+
- FFmpeg (with hardware acceleration support compiled in if desired)

## Installation

### 1. Install FFmpeg

#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install ffmpeg
```

For hardware acceleration support:
```bash
# Intel QSV
sudo apt install intel-media-va-driver-non-free

# NVIDIA NVENC (requires NVIDIA drivers)
# Already supported if NVIDIA drivers are installed

# AMD VA-API
sudo apt install mesa-va-drivers
```

#### macOS
```bash
brew install ffmpeg
```

#### Windows
Download from [ffmpeg.org](https://ffmpeg.org/download.html) or use:
```bash
choco install ffmpeg
```

### 2. Make the script executable (Linux/macOS)
```bash
chmod +x transcode_bench.py
```

## Usage

### Basic Usage
```bash
python3 transcode_bench.py
```

This will:
1. Detect available hardware acceleration
2. Generate a 10-second 1080p H.264 test video
3. Run benchmarks to find the maximum number of simultaneous 1080p H.264 → 720p H.265 transcodes
4. Output the result

### Command-Line Options

```bash
python3 transcode_bench.py [OPTIONS]

Options:
  --duration SECONDS    Test video duration (default: 30)
  --input FILE          Use existing video file instead of generating one
  --min-fps FPS         Minimum FPS to consider real-time (default: 30.0)
  --help                Show help message
```

### Examples

**Use a shorter test video (faster benchmark):**
```bash
python3 transcode_bench.py --duration 10
```

**Use your own video file:**
```bash
python3 transcode_bench.py --input /path/to/your/video.mp4
```

**Set a different real-time threshold (e.g., 60fps):**
```bash
python3 transcode_bench.py --min-fps 60
```

## Output

The benchmark will display progress as it searches for the maximum number of streams, then output a final score:

```
==============================================================
Video Transcoding Benchmark
==============================================================
Detected acceleration: NVIDIA NVENC
Encoder: h264_nvenc
Generating 30s 1080p test video...

Benchmarking with NVIDIA NVENC...
Finding maximum simultaneous 1080p streams at real-time or better...

Testing 32 simultaneous streams...  (avg 87.3 fps)
Testing 48 simultaneous streams...  (avg 58.2 fps)
Testing 56 simultaneous streams...  (avg 24.1 fps - below real-time)
Testing 52 simultaneous streams...  (avg 45.7 fps)
Testing 54 simultaneous streams...  (avg 32.8 fps)
Testing 55 simultaneous streams...  (avg 28.9 fps - below real-time)

==============================================================
BENCHMARK RESULTS
==============================================================
Hardware Acceleration: NVIDIA NVENC
Maximum Simultaneous 1080p Streams: 54
(at 30.0 FPS or better)
==============================================================

Benchmark Score: 54
```

## How It Works

1. **Detection**: Scans for available hardware encoders in your FFmpeg build and tests both H.264 decode and H.265 encode capabilities
2. **Test Video**: Generates a synthetic 1080p H.264 video with test patterns
3. **Realistic Transcoding**: Each stream transcodes 1080p H.264 → 720p H.265 with:
   - Hardware-accelerated H.264 decode
   - CPU-based scaling (1080p → 720p)
   - Hardware-accelerated H.265 encode
4. **Adaptive Binary Search**: Uses adaptive binary search to efficiently find the maximum number of streams, based on single-stream performance
5. **Parallel Execution**: Runs multiple FFmpeg processes in parallel to simulate concurrent transcoding workloads

## Interpreting Results

The "Benchmark Score" represents how many 1080p H.264 → 720p H.265 transcodes your system can perform simultaneously while maintaining real-time or better performance (≥30 FPS). This is useful for:

- Comparing hardware performance
- Capacity planning for video processing workloads
- Evaluating hardware acceleration effectiveness

**Typical scores:**
- Software (CPU only): 1-4 streams
- Entry-level GPU: 5-15 streams
- Mid-range GPU: 15-40 streams
- High-end GPU: 40-100+ streams

## Troubleshooting

**FFmpeg not found:**
- Ensure FFmpeg is installed and in your system PATH
- Try running `ffmpeg -version` to verify

**Hardware acceleration not detected:**
- Verify your FFmpeg build includes hardware encoder support: `ffmpeg -encoders | grep <encoder>`
- Ensure proper drivers are installed (NVIDIA, Intel, AMD)
- On Linux, check that you have access to `/dev/dri/renderD128` for VA-API

**Benchmark fails or hangs:**
- Try a shorter duration: `--duration 10`
- Check system resources (CPU, memory, GPU)
- Verify FFmpeg works manually: `ffmpeg -i input.mp4 -c:v h264_nvenc output.mp4`

## License

MIT License