ff-sys 0.3.0

Low-level FFmpeg FFI bindings for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# ff-sys


Low-level FFmpeg FFI bindings for Rust.

## Overview


`ff-sys` provides raw FFI bindings to FFmpeg libraries, generated by [bindgen](https://github.com/rust-lang/rust-bindgen). This crate is intended as a building block for higher-level safe wrappers.

## Features


- **Complete FFmpeg bindings**: Auto-generated bindings via bindgen
- **Wrapper modules**: Thin Rust wrappers for common operations
  - `avcodec` - Codec operations (encode/decode)
  - `avformat` - Container format I/O
  - `swscale` - Video scaling and color conversion
  - `swresample` - Audio resampling
- **Error handling utilities**: `av_error_string()` and `check_av_error!` macro
- **Cross-platform**: Windows (VCPKG), Linux, macOS

## Supported Platforms


| Platform | FFmpeg Source | Build Method |
|----------|--------------|--------------|
| Windows  | VCPKG        | MSVC toolchain |
| Linux    | System package (apt/yum) | pkg-config |
| macOS    | Homebrew     | pkg-config |

## Prerequisites


FFmpeg development libraries must be installed on your system.

### Windows


```powershell
# Install via VCPKG (recommended)

vcpkg install ffmpeg:x64-windows

# Set environment variables

$env:VCPKG_ROOT = "C:\vcpkg"
```

### Linux (Debian/Ubuntu)


```bash
sudo apt install libavcodec-dev libavformat-dev libswscale-dev libswresample-dev
```

### macOS


```bash
brew install ffmpeg
```

## Minimum Supported Rust Version


Rust 1.93.0 or later (edition 2024).

## Usage


> **Note**: This crate provides unsafe FFI bindings. Consider using higher-level wrappers from the ff-* crate family for safe abstractions.

### Basic Example


```rust,ignore
use ff_sys::{ensure_initialized, av_error_string, check_av_error};

fn main() {
    // Initialize FFmpeg (idempotent)
    ensure_initialized();

    // Error handling example
    let error_msg = av_error_string(-12); // ENOMEM
    println!("Error: {}", error_msg);
}
```

### Using Wrapper Modules


```rust,ignore
use ff_sys::swscale::{get_context, scale, free_context, scale_flags};
use ff_sys::{AVPixelFormat_AV_PIX_FMT_YUV420P, AVPixelFormat_AV_PIX_FMT_RGB24};

unsafe {
    // Create a scaling context
    let ctx = get_context(
        1920, 1080, AVPixelFormat_AV_PIX_FMT_YUV420P,
        1280, 720, AVPixelFormat_AV_PIX_FMT_RGB24,
        scale_flags::LANCZOS,
    )?;

    // Scale a frame (see swscale module for full API)
    // scale(ctx, src_ptrs, src_stride, 0, src_height, dst_ptrs, dst_stride)?;

    // Free the context when done
    free_context(ctx);
}
```

## Module Structure


```
ff-sys/src/
├── lib.rs          # Crate root, bindgen include, utilities
├── avcodec.rs      # Codec context, packet handling
├── avformat.rs     # Format context, stream handling
├── swscale.rs      # Video scaling context
└── swresample.rs   # Audio resampling context
```

## Related Crates


This crate is part of the ff-* crate family:

- **ff-format** - Type-safe pixel/sample formats, timestamps, stream info
- **ff-probe** - Media metadata extraction
- **ff-decode** - Video/audio decoding
- **ff-encode** - Video/audio encoding
- **ff-filter** - Filter graph operations (planned)

## License


MIT OR Apache-2.0