Video Conversion

Frame provides comprehensive video conversion capabilities with support for multiple containers, codecs, and encoding options. All conversions are powered by FFmpeg and run locally on your machine.

Supported Containers

Frame supports the following video container formats:

MP4

Universal compatibility, best for web and streaming

MKV

Flexible container supporting all codecs and features

WebM

Web-optimized format with VP9 codec support

MOV

QuickTime format, ideal for Apple ecosystem

GIF

Animated image format (see GIF-specific options below)

Video Codecs

Frame supports both software and hardware-accelerated video codecs:

Software Codecs

Codec	Containers	Description
`libx264`	mp4, mkv, mov	H.264 software encoder - universal compatibility
`libx265`	mp4, mkv, mov	H.265/HEVC software encoder - better compression
`vp9`	mp4, mkv, webm	VP9 codec - web-optimized, royalty-free
`prores`	mkv, mov	ProRes codec - professional editing workflow
`libsvtav1`	mp4, mkv	AV1 software encoder - next-gen compression
`gif`	gif	GIF encoder for animated images

Hardware Encoders

Hardware encoders require compatible GPU hardware and drivers. Frame automatically detects available hardware encoders on your system.

NVIDIA NVENC:

h264_nvenc - Hardware-accelerated H.264 encoding
hevc_nvenc - Hardware-accelerated H.265/HEVC encoding
av1_nvenc - Hardware-accelerated AV1 encoding (RTX 40 series+)

Apple VideoToolbox:

h264_videotoolbox - Hardware-accelerated H.264 (macOS)
hevc_videotoolbox - Hardware-accelerated H.265/HEVC (macOS)

Hardware Encoder Settings

NVENC Options:

config.nvencSpatialAq = true;  // Enable spatial adaptive quantization
config.nvencTemporalAq = true; // Enable temporal adaptive quantization

VideoToolbox Options:

config.videotoolboxAllowSw = true; // Fallback to software if hardware unavailable

Bitrate Control Modes

Frame offers two bitrate control modes defined in the videoBitrateMode setting:

CRF (Constant Rate Factor)

config.videoBitrateMode = 'crf';
config.crf = 23; // 0-51, lower = better quality

CRF maintains consistent quality throughout the video. The CRF scale works as follows:

0-17: Visually lossless (very large files)
18-23: High quality (recommended range)
24-28: Medium quality (good for streaming)
29-51: Low quality (small files)

Default CRF value: 23

For hardware encoders (NVENC, VideoToolbox), Frame automatically converts CRF values to equivalent quality settings for the encoder.

Target Bitrate

config.videoBitrateMode = 'bitrate';
config.videoBitrate = '5000'; // kilobits per second

Target bitrate mode aims for a specific file size. Higher bitrates produce better quality but larger files. Recommended bitrates:

1080p: 8,000-12,000 kbps
720p: 5,000-8,000 kbps
480p: 2,500-5,000 kbps

Resolution Scaling

Preset Resolutions

config.resolution = '1080p'; // Options: 'original', '1080p', '720p', '480p'
config.scalingAlgorithm = 'lanczos';

Preset resolutions maintain aspect ratio by scaling the height and calculating width automatically using -2 (ensures even dimensions).

Custom Resolution

config.resolution = 'custom';
config.customWidth = '1920';
config.customHeight = '1080';

Custom dimensions support:

Specific width and height
-1 for automatic calculation based on aspect ratio
Automatic letterboxing to fit specified dimensions

Implementation (filters.rs:55-69):

if w != "-1" && h != "-1" {
    format!(
        "scale={w}:{h}:force_original_aspect_ratio=decrease{algo},pad={w}:{h}:(ow-iw)/2:(oh-ih)/2",
        w = w, h = h, algo = algorithm
    )
}

Scaling Algorithms

Algorithm	Quality	Speed	Best For
`bicubic`	Good	Fast	General purpose
`lanczos`	Best	Slow	Upscaling, high quality
`bilinear`	Medium	Very Fast	Downscaling, speed priority
`nearest`	Poor	Fastest	Pixel art, testing

config.scalingAlgorithm = 'lanczos'; // 'bicubic' | 'lanczos' | 'bilinear' | 'nearest'

Framerate Control

Control output framerate with the fps setting:

config.fps = 'original'; // Keep source framerate
config.fps = '30';       // Convert to 30fps
config.fps = '60';       // Convert to 60fps
config.fps = '24';       // Convert to 24fps (film)

Implementation (codec.rs:94-99):

pub fn add_fps_args(args: &mut Vec<String>, config: &ConversionConfig) {
    if config.fps != "original" {
        args.push("-r".to_string());
        args.push(config.fps.clone());
    }
}

Video Transformations

Rotation

config.rotation = '0';   // No rotation (default)
config.rotation = '90';  // Clockwise 90°
config.rotation = '180'; // 180°
config.rotation = '270'; // Clockwise 270° (counter-clockwise 90°)

FFmpeg implementation (filters.rs:13-18):

match config.rotation.as_str() {
    "90" => filters.push("transpose=1".to_string()),
    "180" => filters.push("transpose=1,transpose=1".to_string()),
    "270" => filters.push("transpose=2".to_string()),
    _ => {}
}

Flip

config.flipHorizontal = true; // Mirror horizontally
config.flipVertical = true;   // Flip upside down

Applies hflip and vflip filters respectively.

Crop

config.crop = {
  enabled: true,
  x: 100,      // Left offset in pixels
  y: 50,       // Top offset in pixels
  width: 1280, // Crop width
  height: 720  // Crop height
};

Filter implementation (filters.rs:20-31):

if let Some(crop) = &config.crop && crop.enabled {
    let crop_width = crop.width.max(1.0).round() as i32;
    let crop_height = crop.height.max(1.0).round() as i32;
    let crop_x = crop.x.max(0.0).round() as i32;
    let crop_y = crop.y.max(0.0).round() as i32;
    filters.push(format!(
        "crop={}:{}:{}:{}",
        crop_width, crop_height, crop_x, crop_y
    ));
}

Encoding Presets

Encoding speed presets balance encoding time vs compression efficiency:

config.preset = 'medium'; // Recommended default

Available presets (from fastest to slowest):

ultrafast - Fastest encoding, lowest compression
superfast
veryfast
faster
fast
medium - Balanced (default)
slow - Better compression
slower
veryslow - Best compression, slowest

Hardware encoders use different preset mappings. NVENC presets are automatically mapped to equivalent hardware settings (codec.rs:33-37).

GIF Conversion

When converting to GIF format, additional settings control palette generation and dithering:

config.container = 'gif';
config.gifColors = 256;           // 2-256 palette colors
config.gifDither = 'sierra2_4a';  // Dithering algorithm
config.gifLoop = 0;               // 0 = infinite loop

Dithering Algorithms

Algorithm	Description
`none`	No dithering - banding artifacts
`bayer`	Ordered dithering - patterned
`floyd_steinberg`	Error diffusion - high quality
`sierra2_4a`	Error diffusion - balanced (default)

Implementation (args.rs:326-343):

let colors = config.gif_colors.clamp(2, 256);
let dither = normalize_gif_dither(&config.gif_dither);

format!(
    "[0:v:0]{chain};[gif_palette_src]palettegen=max_colors={colors}:stats_mode=single[gif_palette];[gif_src][gif_palette]paletteuse=dither={dither}:new=1[gif_out]"
)

Hardware Decode Acceleration

Enable hardware-accelerated decoding to improve performance:

config.hwDecode = true;

Frame automatically selects the appropriate hardware decoder based on the selected encoder:

NVENC codecs use CUDA hardware decoding
VideoToolbox codecs use VideoToolbox hardware decoding

Hardware decode is only available in re-encode mode. It is not compatible with stream copy mode.

Processing Modes

Re-encode Mode

config.processingMode = 'reencode'; // Default

Re-encodes the video, allowing all transformations and filters.

Stream Copy Mode

config.processingMode = 'copy';

Copies streams without re-encoding for fast, lossless container changes. Stream copy mode has limitations:

No video/audio filters or transformations
No resolution, framerate, or quality changes
Source codec must be compatible with target container
Not available for GIF output

Validation (args.rs:572-630) ensures incompatible settings are rejected.

Example Configurations

High Quality Archive

{
  container: 'mkv',
  videoCodec: 'libx265',
  videoBitrateMode: 'crf',
  crf: 18,
  preset: 'slow',
  resolution: 'original',
  scalingAlgorithm: 'lanczos',
  audioCodec: 'ac3',
  audioBitrate: '192'
}

Fast Web Preview

{
  container: 'webm',
  videoCodec: 'vp9',
  videoBitrateMode: 'crf',
  crf: 30,
  preset: 'medium',
  resolution: '720p',
  scalingAlgorithm: 'bicubic',
  fps: '30'
}

Hardware Accelerated

{
  container: 'mp4',
  videoCodec: 'h264_nvenc',
  videoBitrateMode: 'crf',
  quality: 50,
  preset: 'medium',
  nvencSpatialAq: true,
  nvencTemporalAq: true,
  hwDecode: true
}

Audio Conversion

Configure audio codecs and processing

AI Upscaling

Enhance video resolution with Real-ESRGAN

Presets

Save and reuse conversion settings

Batch Processing

Convert multiple files efficiently

Get Started

Features

Guides

Development

​Supported Containers

MP4

MKV

WebM

MOV

GIF

​Video Codecs

​Software Codecs

​Hardware Encoders

​Hardware Encoder Settings

​Bitrate Control Modes

​CRF (Constant Rate Factor)

​Target Bitrate

​Resolution Scaling

​Preset Resolutions

​Custom Resolution

​Scaling Algorithms

​Framerate Control

​Video Transformations

​Rotation

​Flip

​Crop

​Encoding Presets

​GIF Conversion

​Dithering Algorithms

​Hardware Decode Acceleration

​Processing Modes

​Re-encode Mode

​Stream Copy Mode

​Example Configurations

​High Quality Archive

​Fast Web Preview

​Hardware Accelerated

​Related Features

Audio Conversion

AI Upscaling

Presets

Batch Processing

Build docs developers (and LLMs) love

Supported Containers

Video Codecs

Software Codecs

Hardware Encoders

Hardware Encoder Settings

Bitrate Control Modes

CRF (Constant Rate Factor)

Target Bitrate

Resolution Scaling

Preset Resolutions

Custom Resolution

Scaling Algorithms

Framerate Control

Video Transformations

Rotation

Flip

Crop

Encoding Presets

GIF Conversion

Dithering Algorithms

Hardware Decode Acceleration

Processing Modes

Re-encode Mode

Stream Copy Mode

Example Configurations

High Quality Archive

Fast Web Preview

Hardware Accelerated

Related Features