@camera.ui/ffmpeg

Intelligent FFmpeg binary downloader with automatic platform detection and hardware optimization for camera.ui.

Installation

npm install @camera.ui/ffmpeg

The FFmpeg binary will be automatically downloaded during installation based on your system.

Usage

import { ffmpegPath, isFFmpegAvailable } from '@camera.ui/ffmpeg';

// Get FFmpeg binary path
const ffmpeg = ffmpegPath();
console.log('FFmpeg path:', ffmpeg);

// Check if FFmpeg is available
if (isFFmpegAvailable()) {
  console.log('FFmpeg is ready to use');
}

Smart Binary Selection

The package automatically selects the optimal FFmpeg binary based on:

Platform Detection

• Linux - Detects distribution (Debian, Ubuntu) and codename
• Windows - x64, x86, ARM64 support
• macOS - Intel and Apple Silicon support
• FreeBSD - x64 support

Hardware Optimization

• VAAPI/QSV - Intel hardware acceleration compatibility
• V4L2M2M - Raspberry Pi hardware acceleration
• Rockchip - ARM SoC optimization
• Jellyfin - Optimized builds for media servers

Architecture Support

• x64 - Standard 64-bit Intel/AMD
• ARM64 - 64-bit ARM (Apple M1, ARM servers)
• ARM - 32-bit ARM with automatic ARMv6/v7/hardfp detection
• x86 - 32-bit Intel/AMD

Available Binaries

Standard FFmpeg

• FFmpeg 6.1 - VAAPI compatible for older systems
• FFmpeg 7.1 - Latest standard builds
• FFmpeg 7.1.1 - Latest stable release

Jellyfin Optimized

• FFmpeg 7.0.2-jellyfin - Media server optimizations
• FFmpeg 7.1.1-jellyfin - Latest Jellyfin builds

Hardware Specific

• Rockchip builds - ARM SoC acceleration
• V4L2M2M builds - Raspberry Pi optimization
• VAAPI compatible - Intel/AMD hardware acceleration

Distribution-Specific Builds

For Linux, the package detects your distribution and downloads optimized binaries:

• Debian 11 (Bullseye)
• Debian 12 (Bookworm)
• Ubuntu 20.04 (Focal)
• Ubuntu 22.04 (Jammy)
• Ubuntu 24.04 (Noble)
• Generic - Fallback for other distributions

Hardware Detection

Intel/AMD Hardware

// Automatically detects:
// - Intel/AMD GPUs via lspci
// - VAAPI render nodes (/dev/dri/render*)
// - Intel CPU for QuickSync support
// - libva version compatibility

ARM Hardware

// Automatically detects:
// - Raspberry Pi (bcm2835 driver, /dev/video* devices)
// - Rockchip SoCs (device tree, dmesg)
// - ARMv6/v7/hardfp architecture variants

Environment Variables

Control binary selection with environment variables:

# Force generic builds (disable distribution detection)
FORCE_GENERIC=true npm install

# Use Jellyfin optimized builds
USE_JELLYFIN=true npm install

# Prefer VAAPI compatible versions
PREFER_VAAPI_COMPATIBLE=true npm install

# Cross-compilation support
npm_config_os=linux npm_config_cpu=arm64 npm install

Binary Selection Logic

The package uses intelligent selection logic:

1. Active Binary - If marked as active: true
2. Rockchip Priority - For Rockchip devices
3. Hardware Compatibility - VAAPI/V4L2M2M support
4. Distribution Match - OS-specific builds
5. Version Priority - Highest compatible version
6. Standard/Jellyfin - Based on USE_JELLYFIN flag

Examples

Basic Usage

import { ffmpegPath } from '@camera.ui/ffmpeg';
import { spawn } from 'child_process';

const ffmpeg = spawn(ffmpegPath(), [
  '-i', 'input.mp4',
  '-c:v', 'libx264',
  'output.mp4'
]);

Hardware Acceleration

import { ffmpegPath } from '@camera.ui/ffmpeg';

// The downloaded binary automatically includes
// hardware acceleration support for your platform:
// - NVENC (NVIDIA)
// - VAAPI (Intel/AMD Linux)
// - QuickSync (Intel)
// - VideoToolbox (macOS)
// - V4L2M2M (Raspberry Pi)

Check Availability

import { isFFmpegAvailable, ffmpegPath } from '@camera.ui/ffmpeg';

if (!isFFmpegAvailable()) {
  console.error('FFmpeg not found. Run: npm install @camera.ui/ffmpeg');
  process.exit(1);
}

console.log('Using FFmpeg at:', ffmpegPath());

Platform Examples

Raspberry Pi

# Automatically detects Pi and downloads V4L2M2M optimized build
npm install @camera.ui/ffmpeg

Intel NUC with VAAPI

# Detects Intel GPU and downloads VAAPI compatible version
npm install @camera.ui/ffmpeg

Apple Silicon Mac

# Downloads ARM64 build with VideoToolbox support
npm install @camera.ui/ffmpeg

Ubuntu Server

# Detects Ubuntu 22.04 and downloads Jammy-specific build
npm install @camera.ui/ffmpeg

Troubleshooting

Force Generic Build

If automatic detection fails:

FORCE_GENERIC=true npm install @camera.ui/ffmpeg

Manual Binary Selection

# Force specific platform/architecture
npm_config_os=linux npm_config_cpu=x64 npm install

Check Detection Results

The installer logs detected platform information:

Detected platform: linux / x64 / jammy / VAAPI/QSV
Using Jellyfin FFmpeg v7.1.1-jellyfin (VAAPI/QSV compatible)

Common Issues

• Permission errors - Binary is automatically made executable on Unix
• Missing libva - Falls back to software-only builds
• Unknown distribution - Uses generic Linux builds
• Cross-compilation - Set npm_config_os and npm_config_cpu

Binary Sources

Binaries are downloaded from the official camera.ui FFmpeg repository:

• Repository: seydx/ffmpeg-static
• Version: 0.0.9
• Format: Compressed ZIP archives
• Verification: GitHub release checksums

Development

# Clone repository
git clone https://github.com/camera-ui/ffmpeg

# Install dependencies
npm install

# Run installer
npm run install

# Check binary
npm run test

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

MIT

Part of the camera.ui ecosystem - A comprehensive camera management solution.