One-KVM/docs/report/hwcodec/01-api-reference.md

hwcodec 编解码器 API 详解

1. 编码器 API

1.1 编码器初始化

EncodeContext 参数

pub struct EncodeContext {
    pub name: String,          // 编码器名称
    pub mc_name: Option<String>, // MediaCodec 名称 (Android)
    pub width: i32,            // 视频宽度 (必须为偶数)
    pub height: i32,           // 视频高度 (必须为偶数)
    pub pixfmt: AVPixelFormat, // 像素格式
    pub align: i32,            // 内存对齐 (通常为 0 或 32)
    pub fps: i32,              // 帧率
    pub gop: i32,              // GOP 大小 (关键帧间隔)
    pub rc: RateControl,       // 码率控制模式
    pub quality: Quality,      // 编码质量
    pub kbs: i32,              // 目标码率 (kbps)
    pub q: i32,                // 量化参数 (CQ 模式)
    pub thread_count: i32,     // 编码线程数
}

参数说明

参数	类型	说明	推荐值
name	String	FFmpeg 编码器名称	见下表
width	i32	视频宽度	1920
height	i32	视频高度	1080
pixfmt	AVPixelFormat	像素格式	NV12 / YUV420P
align	i32	内存对齐	0 (自动)
fps	i32	帧率	30
gop	i32	GOP 大小	30 (1秒)
rc	RateControl	码率控制	CBR / VBR
quality	Quality	质量级别	Medium
kbs	i32	码率 (kbps)	2000-8000
thread_count	i32	线程数	4

编码器名称对照表

名称	格式	加速	平台
h264_nvenc	H.264	NVIDIA GPU	Windows/Linux
hevc_nvenc	H.265	NVIDIA GPU	Windows/Linux
h264_amf	H.264	AMD GPU	Windows/Linux
hevc_amf	H.265	AMD GPU	Windows/Linux
h264_qsv	H.264	Intel QSV	Windows
hevc_qsv	H.265	Intel QSV	Windows
h264_vaapi	H.264	VAAPI	Linux
hevc_vaapi	H.265	VAAPI	Linux
vp8_vaapi	VP8	VAAPI	Linux
vp9_vaapi	VP9	VAAPI	Linux
h264_rkmpp	H.264	Rockchip MPP	Linux
hevc_rkmpp	H.265	Rockchip MPP	Linux
h264_v4l2m2m	H.264	V4L2 M2M	Linux
hevc_v4l2m2m	H.265	V4L2 M2M	Linux
hevc_videotoolbox	H.265	VideoToolbox	macOS
h264	H.264	软件 (x264)	全平台
hevc	H.265	软件 (x265)	全平台
libvpx	VP8	软件	全平台
libvpx-vp9	VP9	软件	全平台
mjpeg	MJPEG	软件	全平台

1.2 创建编码器

use hwcodec::ffmpeg_ram::encode::{Encoder, EncodeContext};
use hwcodec::ffmpeg::{AVPixelFormat};
use hwcodec::common::{RateControl, Quality};

let ctx = EncodeContext {
    name: "h264_vaapi".to_string(),
    mc_name: None,
    width: 1920,
    height: 1080,
    pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
    align: 0,
    fps: 30,
    gop: 30,
    rc: RateControl::RC_CBR,
    quality: Quality::Quality_Medium,
    kbs: 4000,
    q: 0,
    thread_count: 4,
};

let encoder = Encoder::new(ctx)?;
println!("Linesize: {:?}", encoder.linesize);
println!("Offset: {:?}", encoder.offset);
println!("Buffer length: {}", encoder.length);

1.3 编码帧

// 准备 YUV 数据
let yuv_data: Vec<u8> = prepare_yuv_frame();

// 编码
let pts_ms: i64 = 0; // 时间戳 (毫秒)
match encoder.encode(&yuv_data, pts_ms) {
    Ok(frames) => {
        for frame in frames.iter() {
            println!("Encoded: {} bytes, pts={}, key={}",
                     frame.data.len(), frame.pts, frame.key);
            // 发送 frame.data
        }
    }
    Err(code) => {
        eprintln!("Encode error: {}", code);
    }
}

1.4 动态调整码率

// 动态调整到 6000 kbps
encoder.set_bitrate(6000)?;

1.5 请求关键帧

// 下一帧强制编码为 IDR 帧
encoder.request_keyframe();

1.6 检测可用编码器

use hwcodec::ffmpeg_ram::encode::{Encoder, EncodeContext};
use hwcodec::ffmpeg_ram::CodecInfo;

let ctx = EncodeContext {
    name: String::new(),
    mc_name: None,
    width: 1920,
    height: 1080,
    pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
    align: 0,
    fps: 30,
    gop: 30,
    rc: RateControl::RC_DEFAULT,
    quality: Quality::Quality_Default,
    kbs: 4000,
    q: 0,
    thread_count: 4,
};

let available_encoders = Encoder::available_encoders(ctx, None);
for encoder in available_encoders {
    println!("Available: {} (format: {:?}, priority: {})",
             encoder.name, encoder.format, encoder.priority);
}

2. 解码器 API

2.1 解码器初始化

DecodeContext 参数

pub struct DecodeContext {
    pub name: String,           // 解码器名称
    pub device_type: AVHWDeviceType, // 硬件设备类型
    pub thread_count: i32,      // 解码线程数
}

硬件设备类型

AVHWDeviceType	说明
AV_HWDEVICE_TYPE_NONE	软件解码
AV_HWDEVICE_TYPE_CUDA	NVIDIA CUDA
AV_HWDEVICE_TYPE_VAAPI	Linux VAAPI
AV_HWDEVICE_TYPE_D3D11VA	Windows D3D11
AV_HWDEVICE_TYPE_VIDEOTOOLBOX	macOS VideoToolbox
AV_HWDEVICE_TYPE_MEDIACODEC	Android MediaCodec

2.2 创建解码器

use hwcodec::ffmpeg_ram::decode::{Decoder, DecodeContext};
use hwcodec::ffmpeg::AVHWDeviceType;

let ctx = DecodeContext {
    name: "h264".to_string(),
    device_type: AVHWDeviceType::AV_HWDEVICE_TYPE_VAAPI,
    thread_count: 4,
};

let decoder = Decoder::new(ctx)?;

2.3 解码帧

// 输入编码数据
let encoded_packet: Vec<u8> = receive_encoded_data();

match decoder.decode(&encoded_packet) {
    Ok(frames) => {
        for frame in frames.iter() {
            println!("Decoded: {}x{}, format={:?}, key={}",
                     frame.width, frame.height, frame.pixfmt, frame.key);

            // 访问 YUV 数据
            let y_plane = &frame.data[0];
            let u_plane = &frame.data[1];
            let v_plane = &frame.data[2]; // 仅 YUV420P
        }
    }
    Err(code) => {
        eprintln!("Decode error: {}", code);
    }
}

2.4 DecodeFrame 结构体

pub struct DecodeFrame {
    pub pixfmt: AVPixelFormat,  // 输出像素格式
    pub width: i32,             // 帧宽度
    pub height: i32,            // 帧高度
    pub data: Vec<Vec<u8>>,     // 平面数据 [Y, U, V] 或 [Y, UV]
    pub linesize: Vec<i32>,     // 每个平面的行字节数
    pub key: bool,              // 是否为关键帧
}

像素格式与平面布局

像素格式	平面数	data[0]	data[1]	data[2]
YUV420P	3	Y	U	V
YUVJ420P	3	Y	U	V
YUV422P	3	Y	U	V
NV12	2	Y	UV (交错)	-
NV21	2	Y	VU (交错)	-

2.5 检测可用解码器

use hwcodec::ffmpeg_ram::decode::Decoder;

let available_decoders = Decoder::available_decoders();
for decoder in available_decoders {
    println!("Available: {} (format: {:?}, hwdevice: {:?})",
             decoder.name, decoder.format, decoder.hwdevice);
}

3. 码率控制模式

3.1 RateControl 枚举

pub enum RateControl {
    RC_DEFAULT,  // 使用编码器默认
    RC_CBR,      // 恒定码率
    RC_VBR,      // 可变码率
    RC_CQ,       // 恒定质量 (需设置 q 参数)
}

3.2 模式说明

模式	说明	适用场景
RC_CBR	码率恒定，质量随场景变化	网络带宽受限
RC_VBR	质量优先，码率波动	本地存储
RC_CQ	恒定质量，码率波动大	质量敏感场景

3.3 各编码器支持情况

编码器	CBR	VBR	CQ
nvenc	✓	✓	✓
amf	✓	✓ (低延迟)	✗
qsv	✓	✓	✗
vaapi	✓	✓	✗
mediacodec	✓	✓	✓

4. 质量等级

4.1 Quality 枚举

pub enum Quality {
    Quality_Default, // 使用编码器默认
    Quality_High,    // 高质量 (慢速)
    Quality_Medium,  // 中等质量 (平衡)
    Quality_Low,     // 低质量 (快速)
}

4.2 编码器预设映射

质量	nvenc	amf	qsv
High	-	quality	veryslow
Medium	p4	balanced	medium
Low	p1	speed	veryfast

5. 混流器 API

5.1 创建混流器

use hwcodec::mux::{Muxer, MuxContext};

let ctx = MuxContext {
    filename: "/tmp/output.mp4".to_string(),
    width: 1920,
    height: 1080,
    is265: false,  // H.264
    framerate: 30,
};

let muxer = Muxer::new(ctx)?;

5.2 写入视频帧

// 编码后的帧数据
let encoded_data: Vec<u8> = encoder.encode(...)?;
let is_keyframe = true;

muxer.write_video(&encoded_data, is_keyframe)?;

5.3 完成写入

// 写入文件尾
muxer.write_tail()?;
// muxer 被 drop 时自动释放资源

6. 错误处理

6.1 错误码

错误码	常量	说明
0	HWCODEC_SUCCESS	成功
-1	HWCODEC_ERR_COMMON	通用错误
-2	HWCODEC_ERR_HEVC_COULD_NOT_FIND_POC	HEVC 解码参考帧丢失

6.2 常见错误处理

match encoder.encode(&yuv_data, pts) {
    Ok(frames) => {
        // 处理编码帧
    }
    Err(-1) => {
        eprintln!("编码失败，可能是输入数据格式错误");
    }
    Err(code) => {
        eprintln!("未知错误: {}", code);
    }
}

7. 最佳实践

7.1 编码器选择策略

fn select_best_encoder(
    width: i32,
    height: i32,
    format: DataFormat
) -> Option<String> {
    let ctx = EncodeContext {
        width,
        height,
        pixfmt: AVPixelFormat::AV_PIX_FMT_NV12,
        // ... 其他参数
    };

    let encoders = Encoder::available_encoders(ctx, None);

    // 按优先级排序，选择最佳
    encoders.into_iter()
        .filter(|e| e.format == format)
        .min_by_key(|e| e.priority)
        .map(|e| e.name)
}

7.2 帧内存布局

// 获取 NV12 帧布局信息
let (linesize, offset, length) = ffmpeg_linesize_offset_length(
    AVPixelFormat::AV_PIX_FMT_NV12,
    1920,
    1080,
    0,  // align
)?;

// 分配缓冲区
let mut buffer = vec![0u8; length as usize];

// 填充 Y 平面: buffer[0..offset[0]]
// 填充 UV 平面: buffer[offset[0]..length]

7.3 关键帧控制

let mut frame_count = 0;

loop {
    // 每 30 帧强制一个关键帧
    if frame_count % 30 == 0 {
        encoder.request_keyframe();
    }

    encoder.encode(&yuv_data, pts)?;
    frame_count += 1;
}

7.4 线程安全

// Decoder 实现了 Send + Sync
unsafe impl Send for Decoder {}
unsafe impl Sync for Decoder {}

// 可以安全地在多线程间传递
let decoder = Arc::new(Mutex::new(Decoder::new(ctx)?));