playa-ffmpeg - Modern FFmpeg Wrapper with vcpkg Integration

Modified by: Alex Joss (joss13@gmail.com)

This is a modernized fork with cross-platform build improvements and vcpkg integration.

Key Modifications

• vcpkg Integration: Automatic FFmpeg installation and static linking on all platforms
• NVENC Support: Hardware encoding with NVIDIA NVENC/NVDEC (Windows/Linux, enabled by default)
• Static Linking: Single standalone binary, no external FFmpeg dependencies required
• Optimized CI/CD: GitHub Actions with aggressive vcpkg caching (20min → 3min builds)
• Release-Only Builds: Custom vcpkg triplets skip debug builds (50% faster on Windows)
• Rust 2024 Edition: Updated to latest Rust edition with modern syntax
• FFmpeg 7.1+ Support: Full support for FFmpeg 7.1 APIs via vcpkg
• Unified Bootstrap Script: Single script for building and publishing across all platforms
• Enhanced Examples: New video-info tool, improved frame dumping
• Visual Studio Setup: Automatic MSVC environment configuration on Windows

Prerequisites

vcpkg Installation

This crate uses vcpkg for FFmpeg dependency management with static linking.

Install vcpkg

Windows:

git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
cd C:\vcpkg
.\bootstrap-vcpkg.bat
setx VCPKG_ROOT "C:\vcpkg"

Linux/macOS:

git clone https://github.com/microsoft/vcpkg.git /usr/local/share/vcpkg
cd /usr/local/share/vcpkg
./bootstrap-vcpkg.sh
export VCPKG_ROOT=/usr/local/share/vcpkg
# Add to ~/.bashrc or ~/.zshrc for persistence

Install FFmpeg via vcpkg

Windows (MSVC) - Release only (faster builds):

First create a custom triplet for release-only builds:

# Create triplet file
$tripletContent = @"
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_BUILD_TYPE release)
"@
New-Item -Path "$env:VCPKG_ROOT\triplets\community" -ItemType Directory -Force
Set-Content -Path "$env:VCPKG_ROOT\triplets\community\x64-windows-static-md-release.cmake" -Value $tripletContent

# Install FFmpeg (release only - ~2x faster than default)
vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale,nvcodec]:x64-windows-static-md-release

Windows (MSVC) - Debug + Release (default):

vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale,nvcodec]:x64-windows-static-md

Linux:

vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale,nvcodec]:x64-linux-release

macOS (Intel):

vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale]:x64-osx-release

macOS (Apple Silicon):

vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale]:arm64-osx-release

Platform-Specific Notes:

Important Notes:

• NVENC Runtime Requirements: NVENC headers are statically linked, but you need NVIDIA GPU + drivers at runtime
• Windows Optimization: Use x64-windows-static-md-release triplet to skip debug builds (50% faster)
• Subsequent Builds: After first build, vcpkg cache makes rebuilds ~3 minutes
• CI/CD: GitHub Actions uses release-only triplets and persistent caching for optimal performance

Quick Start

Windows

bootstrap.cmd build

Linux/macOS

./bootstrap.sh build

See examples/README.md for detailed usage examples.

Quick Test: List Available Codecs

# Build and run video-info example
cargo build --example video-info --release

# List all available codecs (hardware + software)
cargo run --example video-info --release -- ls

Output:

• Video decoders: H264, H265, VP9, AV1, MPEG4, etc.
• Video encoders: libx264, libx265, NVENC (if GPU available), etc.
• Audio decoders: AAC, MP3, Opus, Vorbis, etc.
• Audio encoders: AAC, MP3, Opus, etc.

Why use this:

• Verify NVENC is available on your system
• Check which codecs are enabled
• Confirm FFmpeg is properly configured

Build System

Cargo Features

The crate supports multiple hardware encoding/decoding backends through Cargo features:

[features]
default = ["codec", "device", "filter", "format", "software-resampling", "software-scaling", "nvenc"]

# Core FFmpeg components
codec = []
device = []
filter = []
format = []
software-resampling = []
software-scaling = []

# Hardware encoding/decoding (platform-specific)
nvenc = []           # NVIDIA NVENC/NVDEC (Windows/Linux only, enabled by default)
vaapi = []           # Intel/AMD VAAPI (Linux only)
videotoolbox = []    # Apple VideoToolbox (macOS only)
qsv = []             # Intel Quick Sync Video (Windows/Linux)

Usage examples:

# Default build with NVENC
cargo build --release

# Build without NVENC (software encoding only)
cargo build --release --no-default-features --features "codec,device,filter,format,software-resampling,software-scaling"

# Build with VAAPI for Intel/AMD GPUs on Linux
cargo build --release --features "vaapi"

# Build with VideoToolbox on macOS
cargo build --release --features "videotoolbox"

Build Options

bootstrap build           # Build release (default)
bootstrap build --release # Build release (explicit)
bootstrap build --debug   # Build debug
bootstrap test           # Run all tests

Build System Details

The crate uses a custom build.rs that:

• Automatically detects and uses vcpkg-installed FFmpeg
• Respects VCPKG_DEFAULT_TRIPLET environment variable for custom triplets
• Falls back to system FFmpeg if vcpkg not found
• Attempts automatic vcpkg installation if VCPKG_ROOT is set
• Emits proper linking flags for static/dynamic linking

Testing

Run tests to verify FFmpeg integration:

# All tests
bootstrap test

# Or directly with cargo
cargo test --examples

What it does:

• Verifies FFmpeg libraries are properly linked
• Tests basic codec functionality
• Validates video/audio decoding
• Checks frame extraction and color space conversion

Test output location: target/debug/ or target/release/

Publishing (Maintainers)

bootstrap crate          # Dry-run (preview changes)
bootstrap crate publish  # Publish to crates.io

Uses cargo-release - automatically installed on first use.

CI/CD Pipeline

Optimized Build Strategy

The GitHub Actions workflow is optimized for minimal build times:

First Build (cold cache):

• Linux: ~15 minutes (FFmpeg compilation)
• macOS: ~15 minutes (FFmpeg compilation)
• Windows: ~10 minutes (release-only FFmpeg)

Subsequent Builds (warm cache):

• All platforms: ~3 minutes (Rust code only)

Caching Strategy

1. Persistent FFmpeg Cache: vcpkg artifacts cached indefinitely (only rebuilds when cache key manually bumped)
2. Release-Only Triplets: Windows uses custom x64-windows-static-md-release triplet to skip debug builds
3. Conditional Installation: FFmpeg installation skipped if cache hit

Cache locations:

Linux/macOS:
  - /usr/local/share/vcpkg/installed
  - /usr/local/share/vcpkg/buildtrees
  - /usr/local/share/vcpkg/downloads
  - /usr/local/share/vcpkg/packages

Windows:
  - C:\vcpkg\installed
  - C:\vcpkg\buildtrees
  - C:\vcpkg\downloads
  - C:\vcpkg\packages

Platform Matrix

This is a fork of ffmpeg-next (originally based on the ffmpeg crate by meh.).

This fork focuses on modern Rust (2024 edition) with FFmpeg 8.0 support and simplified cross-platform builds via vcpkg.

Hardware Encoding Support

NVENC (NVIDIA GPUs)

NVENC support is enabled by default on Windows and Linux builds.

Requirements:

• NVIDIA GPU with NVENC support (GTX 600+, Quadro Kxxx+, Tesla Kxx+)
• NVIDIA drivers (no CUDA SDK required for compilation)
• nvcodec feature in vcpkg FFmpeg installation

Runtime behavior:

• On systems with NVIDIA GPU: Hardware encoding available
• On systems without GPU: Gracefully falls back to CPU encoders
• Headers-only dependency - no runtime CUDA requirement

Not available on macOS (NVENC is NVIDIA-specific hardware).

Platform-Specific Hardware Encoding

• Windows/Linux: NVENC via nvcodec feature
• macOS: VideoToolbox (built into macOS, no additional setup)
• Intel GPUs: QuickSync (optional, not enabled by default)

CI/CD Setup

For GitHub Actions or other CI environments:

Required Environment Variables

env:
  VCPKG_ROOT: /usr/local/share/vcpkg  # Linux/macOS
  # or C:\vcpkg on Windows
  PKG_CONFIG_PATH: /usr/local/share/vcpkg/installed/{triplet}/lib/pkgconfig

Example GitHub Actions Workflow

- name: Install FFmpeg via vcpkg
  run: |
    vcpkg install ffmpeg[core,avcodec,avdevice,avfilter,avformat,swresample,swscale,nvcodec]:x64-linux-release

- name: Set environment variables
  run: |
    echo "PKG_CONFIG_PATH=/usr/local/share/vcpkg/installed/x64-linux-release/lib/pkgconfig" >> $GITHUB_ENV
    echo "VCPKG_ROOT=/usr/local/share/vcpkg" >> $GITHUB_ENV

- name: Build
  run: cargo build --release

vcpkg Caching

Speed up CI builds with vcpkg caching:

- name: Cache vcpkg
  uses: actions/cache@v4
  with:
    path: |
      /usr/local/share/vcpkg/installed
      ~/.cache/vcpkg
    key: ${{ runner.os }}-vcpkg-x64-linux-release-${{ hashFiles('.github/workflows/build.yml') }}
    restore-keys: |
      ${{ runner.os }}-vcpkg-x64-linux-release-

Result: First build ~30-40 min, cached builds ~3-5 min.

Cargo Features

[features]
default = ["codec", "device", "filter", "format", "software-resampling", "software-scaling", "nvenc"]

# Hardware encoding (nvenc enabled by default)
nvenc = []           # NVIDIA NVENC/NVDEC
vaapi = []           # Linux VA-API (optional)
videotoolbox = []    # macOS VideoToolbox (optional)
qsv = []             # Intel QuickSync (optional)

Build without NVENC:

cargo build --no-default-features --features codec,device,filter,format,software-resampling,software-scaling

Triplet Reference

Documentation

• API docs - Rust API documentation
• FFmpeg user manual - Official FFmpeg manual
• FFmpeg Doxygen - C API reference
• vcpkg FFmpeg port - vcpkg FFmpeg features

See CHANGELOG.md for version history and upgrade notes.