FFmpeg API on Dorkytiger 的小屋

解封装流程（Demuxing）

Mon, 01 Jan 0001 00:00:00 +0000

一、从文件读取 packet 到解码出 frame 的完整流程

extern "C" {
#include <libavformat/avformat.h>
#include <libavcodec/avcodec.h>
#include <libswscale/swscale.h>
#include <libavutil/imgutils.h>
}

// 完整的一个 demux + decode 流程
// 从视频文件中读取每一帧解码为 YUV420P 原始数据

struct VideoDecoder {
    AVFormatContext* fmt_ctx = nullptr;
    AVCodecContext*  dec_ctx = nullptr;
    int video_stream_idx = -1;
};

bool open_file(VideoDecoder& dec, const char* filename) {
    // ① 打开文件并读取头部信息
    if (avformat_open_input(&dec.fmt_ctx, filename, nullptr, nullptr) < 0)
        return false;

    // ② 读取流信息（找到视频流的索引和编码器参数）
    if (avformat_find_stream_info(dec.fmt_ctx, nullptr) < 0)
        return false;

    // ③ 找到第一个视频流
    for (unsigned i = 0; i < dec.fmt_ctx->nb_streams; i++) {
        if (dec.fmt_ctx->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_VIDEO) {
            dec.video_stream_idx = i;
            break;
        }
    }
    if (dec.video_stream_idx < 0) return false;

    // ④ 找到对应的解码器并打开
    const AVCodec* codec = avcodec_find_decoder(
        dec.fmt_ctx->streams[dec.video_stream_idx]->codecpar->codec_id);
    if (!codec) return false;

    dec.dec_ctx = avcodec_alloc_context3(codec);
    avcodec_parameters_to_context(dec.dec_ctx,
        dec.fmt_ctx->streams[dec.video_stream_idx]->codecpar);
    avcodec_open2(dec.dec_ctx, codec, nullptr);

    return true;
}

bool decode_frame(VideoDecoder& dec, AVFrame* frame) {
    AVPacket* packet = av_packet_alloc();

    while (av_read_frame(dec.fmt_ctx, packet) >= 0) {
        if (packet->stream_index == dec.video_stream_idx) {
            // ⑤ 把 packet 送入解码器
            if (avcodec_send_packet(dec.dec_ctx, packet) == 0) {
                // ⑥ 从解码器取出解码后的 frame
                if (avcodec_receive_frame(dec.dec_ctx, frame) == 0) {
                    av_packet_free(&packet);
                    return true;  // 成功解码一帧
                }
            }
        }
        av_packet_unref(packet);
    }

    av_packet_free(&packet);
    return false;  // 文件读完
}

二、关于 AVFrame 的重要理解

// 解码后得到的 AVFrame 包含：
// frame->data[0]  → Y 平面数据指针
// frame->data[1]  → U 平面数据指针
// frame->data[2]  → V 平面数据指针（NV12 时 data[1] 是 UV 交错）
//
// frame->linesize[0] → Y 平面的 stride
// frame->linesize[1] → U 平面的 stride
// frame->linesize[2] → V 平面的 stride
//
// frame->pts → 显示时间戳（毫秒单位 × time_base）
// frame->pict_type → AV_PICTURE_TYPE_I / P / B
//
// frame->width, frame->height → 分辨率
// frame->format → 像素格式 AV_PIX_FMT_YUV420P / AV_PIX_FMT_NV12

// ❌ 常见错误：假设 data 是连续的内存块
for (int y = 0; y < height; y++) {
    for (int x = 0; x < width; x++) {
        uint8_t y_val = frame->data[0][y * frame->linesize[0] + x];
    }
}
// ✅ linesize 可能不等于 width（有 padding），必须用 linesize

封装流程（Muxing）

Mon, 01 Jan 0001 00:00:00 +0000

一、从编码后的 packet 写出文件/推流的完整流程

struct VideoEncoder {
    AVFormatContext* fmt_ctx = nullptr;
    AVCodecContext*  enc_ctx = nullptr;
    AVStream*        stream = nullptr;
};

bool setup_encoder(VideoEncoder& enc, const char* output_url,
                    int width, int height, int fps) {
    // ① 根据输出 URL 确定容器格式（.mp4 → mp4, .flv → flv, rtmp:// → flv）
    avformat_alloc_output_context2(&enc.fmt_ctx, nullptr, nullptr, output_url);
    if (!enc.fmt_ctx) return false;

    // ② 创建视频流
    enc.stream = avformat_new_stream(enc.fmt_ctx, nullptr);
    enc.stream->time_base = {1, fps};

    // ③ 配置编码器（H.264）
    const AVCodec* codec = avcodec_find_encoder(AV_CODEC_ID_H264);
    enc.enc_ctx = avcodec_alloc_context3(codec);
    enc.enc_ctx->width = width;
    enc.enc_ctx->height = height;
    enc.enc_ctx->time_base = enc.stream->time_base;
    enc.enc_ctx->pix_fmt = AV_PIX_FMT_YUV420P;

    // ④ 低延迟配置（直播场景）
    enc.enc_ctx->gop_size = 30;       // 每 30 帧一个关键帧
    enc.enc_ctx->max_b_frames = 0;    // 不要 B 帧（减少延迟）
    enc.enc_ctx->flags |= AV_CODEC_FLAG_LOW_DELAY;

    avcodec_open2(enc.enc_ctx, codec, nullptr);

    // ⑤ 编码器参数传递给流
    avcodec_parameters_from_context(enc.stream->codecpar, enc.enc_ctx);

    // ⑥ 打开输出文件
    avio_open(&enc.fmt_ctx->pb, output_url, AVIO_FLAG_WRITE);

    // ⑦ 写文件头（MP4 的 ftyp + moov 初始部分）
    avformat_write_header(enc.fmt_ctx, nullptr);
    return true;
}

// 编码并写出一帧
void encode_frame(VideoEncoder& enc, AVFrame* frame) {
    AVPacket* packet = av_packet_alloc();

    // ① 把原始帧送入编码器
    if (avcodec_send_frame(enc.enc_ctx, frame) == 0) {
        while (avcodec_receive_packet(enc.enc_ctx, packet) == 0) {
            // ② 设置时间戳
            av_packet_rescale_ts(packet, enc.enc_ctx->time_base,
                                  enc.stream->time_base);
            packet->stream_index = enc.stream->index;

            // ③ 写出 packet（内部做交错、写入容器的 mdat）
            av_interleaved_write_frame(enc.fmt_ctx, packet);
        }
    }
    av_packet_free(&packet);
}

// 编码结束后记得 flush + 写尾部
void flush_encoder(VideoEncoder& enc) {
    encode_frame(enc, nullptr);  // 送 nullptr 让编码器输出缓存的帧

    // 写文件尾（更新 moov 中的元数据）
    av_write_trailer(enc.fmt_ctx);

    avio_closep(&enc.fmt_ctx->pb);
    avformat_free_context(enc.fmt_ctx);
}

RGB ↔ YUV 转换（sws_scale）

Mon, 01 Jan 0001 00:00:00 +0000

一、为什么需要它

从桌面采集（DXGI/PipeWire）拿到的是 BGRA/RGBA 帧，编码器只接受 YUV420P。sws_scale 一次性完成：

色彩空间转换（RGB → YUV）
色度下采样（4:4:4 → 4:2:0）
图像缩放（可选）

struct ColorConverter {
    SwsContext* sws_ctx = nullptr;
    int src_w, src_h, dst_w, dst_h;
    AVPixelFormat src_fmt, dst_fmt;

    bool init(int src_w, int src_h, AVPixelFormat src_fmt,
              int dst_w, int dst_h, AVPixelFormat dst_fmt) {
        this->src_w = src_w; this->src_h = src_h;
        this->dst_w = dst_w; this->dst_h = dst_h;
        this->src_fmt = src_fmt; this->dst_fmt = dst_fmt;

        sws_ctx = sws_getContext(
            src_w, src_h, src_fmt,        // 输入格式
            dst_w, dst_h, dst_fmt,        // 输出格式
            SWS_BILINEAR,                 // 插值算法（性能 vs 质量）
            nullptr, nullptr, nullptr      // 滤波器参数（默认）
        );
        return sws_ctx != nullptr;
    }

    // 把 BGRA 桌面采集帧转为 YUV420P（AVFrame）
    void convert(const uint8_t* bgra_data, int bgra_stride, AVFrame* out_frame) {
        // 封装 sws_scale 需要的数据
        uint8_t* src_data[1] = { (uint8_t*)bgra_data };
        int src_linesize[1] = { bgra_stride };

        sws_scale(sws_ctx,
                  src_data, src_linesize, 0, src_h,
                  out_frame->data, out_frame->linesize);
    }

    ~ColorConverter() {
        sws_freeContext(sws_ctx);
    }
};

// 使用示例：
// ColorConverter conv;
// conv.init(1920, 1080, AV_PIX_FMT_BGRA,   // 桌面采集的格式
//           1920, 1080, AV_PIX_FMT_YUV420P); // 编码器需要的格式
//
// AVFrame* yuv_frame = av_frame_alloc();
// yuv_frame->format = AV_PIX_FMT_YUV420P;
// yuv_frame->width = 1920;
// yuv_frame->height = 1080;
// av_frame_get_buffer(yuv_frame, 32);
//
// conv.convert(bgra_buffer, 1920 * 4, yuv_frame);
// // yuv_frame 现在有 YUV420P 数据，可以送给编码器

二、sws_scale 一步完成的操作对比

如果你手动做：
  BGRA → 逐像素转 YUV444 → UV 下采样到 4:2:0 → 分配 Y/U/V 三个缓冲区
  → 至少 3 次内存操作，3 个循环

sws_scale 一次调用：
  sws_scale(ctx, src, src_linesize, 0, h, dst, dst_linesize);
  内部 SIMD 优化：一次循环完成色彩转换 + 下采样 + 写入三个平面
  → 1 次内存操作，速度是手写的 3-5 倍

第四阶段总结

Mon, 01 Jan 0001 00:00:00 +0000

解封装（Demuxing）：
    avformat_open_input → 打开文件
    av_read_frame → 读 packet
    avcodec_send_packet + avcodec_receive_frame → 解码

封装（Muxing）：
    avformat_alloc_output_context2 → 确定容器格式
    avcodec_send_frame + avcodec_receive_packet → 编码
    av_interleaved_write_frame → 写出/推流

色彩转换：
    BGRA → YUV420P：sws_getContext + sws_scale 一步完成
    比手写 RGB→YUV 再下采样快 3-5 倍

直播配置关键：
    gop_size = 30（每 30 帧一个关键帧）
    max_b_frames = 0（不要 B 帧减少延迟）
    AV_CODEC_FLAG_LOW_DELAY（编码器低延迟模式）