第9章：编码器 API：从打开输出到创建流

9.1 API 全景：三个库的分工与对象模型

第 2 章里我们一直在敲命令行：ffmpeg -i in.mp4 -c:v libx264 out.mp4。这条命令背后发生了什么？FFmpeg 的官方命令行工具本身就是一个巨大的 C 程序，它调用的是三个核心库的 API——你完全可以用同样的 API 写自己的转码器，嵌入业务逻辑（加水印、传进度、从内存读、传到云端）。

三个库的分工，一句话各一个：

这四个结构体是整条 API 主线的"四世同堂"，从大到小：

// 对象模型：从外到内
AVFormatContext *ofmt;   // ① 封装器：整个输出文件（"档案袋"）
    AVStream *st;          // ② 流：文件里的一条轨（视频/音频各一条）
        AVCodecContext *enc; // ③ 编解码上下文：编码器的"工作台"，参数都摆这
            AVCodec *codec;     // ④ 编解码器：干活的"师傅"（libx264 / aac…）

对象模型的理解顺序：先找师傅（codec），再摆工作台（codec_ctx），然后把工作台挂到一条流（stream）上，最后把流放进档案袋（format_ctx）。但 API 的调用顺序恰好相反——因为你得先有档案袋才能往里面放流，有了流才知道这条流要什么师傅。这就是素材《ffmpeg-编码的步骤》记录的九步流程，本章一步步走完它。

// 命令行 ↔ API 对照：同一件事的两种说法
// 命令行（第 2 章）                 // C API（本章起）
ffmpeg -i in.wav -c:a aac out.aac    = avformat_alloc_output_context2(&ofmt, NULL, NULL, "out.aac")
                                     + avformat_new_stream(ofmt, NULL)
-c:a aac                            = avcodec_find_encoder_by_name("aac")
-b:a 64k                            = enc_ctx->bit_rate = 64000

这张对照表是全章的"地图"：每一行命令行选项，都能在 API 里找到对应的一个或几个调用。往后读到某个 API 函数想不起用途时，回头看看命令行你用过的那条指令——它们说的是同一件事。

9.2 第一步：打开输出文件流

一切从 avformat_alloc_output_context2 开始。它做两件事：分配一个 AVFormatContext，并且根据输出文件名猜出封装器（.aac → ADTS、.mp4 → MP4、.mkv → Matroska）。第三个参数传 NULL 就是"你看着办"。

AVFormatContext *ofmt_ctx = NULL;
int ret = avformat_alloc_output_context2(&ofmt_ctx, NULL, NULL, "out.aac");
if (ret < 0) {
    av_log(NULL, AV_LOG_ERROR, "无法创建输出上下文: %s\n", av_err2str(ret));
    return ret;
}
printf("oformat = %s\n", ofmt_ctx->oformat->name);  // 猜对了哪个封装器

注意包青天式写法：每一步的返回值都要检查。av_err2str 把错误码转成人类可读文本——这是排查问题的第一手证据。本机实测（FFmpeg 8.1.1）：

# 实测输出（2026-08-08，Apple clang 21 / arm64）
$ gcc enc_steps.c $(pkg-config --cflags --libs libavformat libavcodec libavutil) -o enc_steps && ./enc_steps
[ok  ] avformat_alloc_output_context2
       oformat = adts        <- 看到 out.aac 就自动选了 ADTS 封装器

pkg-config 一行搞定三个库的头文件路径和链接参数——这是编译 FFmpeg 程序的标准姿势，本章所有示例都用它编译。

9.3 第二步：创建输出音频流

档案袋有了，往里放一条流。avformat_new_stream 在容器里注册一条流并返回它的 AVStream——这时候它还是一条"空流"，不知道自己要编什么码。

AVStream *audio_stream = avformat_new_stream(ofmt_ctx, NULL);
if (!audio_stream) {
    av_log(NULL, AV_LOG_ERROR, "无法创建音频流\n");
    return -1;
}
printf("stream index = %d\n", audio_stream->index);  // 这条流在容器里的编号（通常 0）

第二个参数传 NULL 表示"流的信息稍后从编解码器上下文拷贝"——对应素材第七步的 avcodec_parameters_from_context。也就是说：先创建空流，配好编码器，最后把参数灌回流。

# 实测
[ok  ] avformat_new_stream

9.4 第三步：找编码器

现在要给流请师傅。素材的写法是 avcodec_find_encoder(AV_CODEC_ID_AAC)——按编码器 ID 找。这个函数在现行版本已经标记 deprecated（弃用），推荐按名字找，更精确：

// 素材旧写法（已弃用，但仍可用）：按 ID 找
AVCodec *enc_old = avcodec_find_encoder(AV_CODEC_ID_AAC);

// 现行推荐写法：按名字找（更精确，还能找到 libx264 这类第三方编码器）
const AVCodec *encoder = avcodec_find_encoder_by_name("aac");
if (!encoder) {
    av_log(NULL, AV_LOG_ERROR, "找不到 aac 编码器——检查 ffmpeg 编译时是否启用了它\n");
    return -1;
}

为什么弃用按 ID 找？因为一个 ID 背后可能挂多个实现（AAC 有原生的 aac、Apple 的 aac_at、FDK 的 libfdk_aac……），find_encoder 返回"第一个"，结果可能不是你想要的。按名字找就是点名要谁。回顾第 2 章 -c:a aac 与 -c:a aac_at——命令行的 -c:a 后面跟的正是编码器名字，API 里就是 avcodec_find_encoder_by_name 的第一个参数。

# 实测
[ok  ] avcodec_find_encoder_by_name("aac")

9.5 第四到六步：分配上下文与参数设置

师傅请来了，给他摆工作台。avcodec_alloc_context3 分配 AVCodecContext，然后逐项设置参数。素材这部分的参数写法在现行版本有一处重要变化：

AVCodecContext *enc_ctx = avcodec_alloc_context3(encoder);
if (!enc_ctx) { av_log(NULL, AV_LOG_ERROR, "分配上下文失败\n"); return -1; }

// —— 参数设置（素材旧写法 → 现行写法）——
enc_ctx->bit_rate   = 64000;      // 目标码率 64kbps（第 10 章：目标不是承诺）
enc_ctx->sample_rate = 44100;     // 采样率 44.1kHz

// 旧：enc_ctx->channel_layout = 2;           // 直接写整数，早已弃用
// 新：通道布局用 AVChannelLayout 结构体
av_channel_layout_default(&enc_ctx->ch_layout, 2);  // 双声道

enc_ctx->sample_fmt = encoder->sample_fmts[0];        // 用编码器支持的第一种采样格式
enc_ctx->time_base = (AVRational){1, enc_ctx->sample_rate};  // 时间基跟采样率走

逐条解读（柯南视角，数据流会怎么变）：

• bit_rate：目标码率。VBR 下编码器只把它当参考，实际输出看内容复杂度——第 2 章命令行实测 500k 目标只出了 194k。
• sample_rate：每秒钟采多少个样本。44100 是 CD 音质标准。
• ch_layout：素材的 channel_layout = 2 是旧 API（2019 年）。现行 FFmpeg 用 AVChannelLayout 结构体，通过 av_channel_layout_default 初始化成双声道立体声。旧写法在 8.1 会编译警告。
• sample_fmt：采样格式（每个样本怎么存）。不能自己拍脑袋——必须从 encoder->sample_fmts 数组里选编码器支持的第一种。AAC 编码器第一位是 fltp（32 位浮点平面格式）。
• time_base：时间基设为 1/44100——因为音频的"帧"是 1024 个样本一组，时间刻度跟采样率对齐最自然（呼应第 4 章：时间基是给时间编号的刻度）。

# 实测
[ok  ] 参数设置(bit_rate/sample_rate/ch_layout/sample_fmt/time_base)
       sample_fmt = fltp, channels = 2

9.6 第七到九步：打开编码器、收尾三项

工作台摆好了，师傅上岗：avcodec_open2。它会检查参数自洽性（采样率、通道数、采样格式是否匹配），任何矛盾都在这一步暴露。打开之后有三件收尾小事，素材第七到九步：

// 第七步：打开编码器
int ret = avcodec_open2(enc_ctx, encoder, NULL);
if (ret < 0) {
    av_log(NULL, AV_LOG_ERROR, "打开编码器失败: %s\n", av_err2str(ret));
    return ret;
}

// 第八步：codec_tag 清零——流级别覆盖封装器默认的编码标签
audio_stream->codecpar->codec_tag = 0;

// 第九步：把编码器参数（码率/采样率/格式等）拷贝到流的 codecpar
ret = avcodec_parameters_from_context(audio_stream->codecpar, enc_ctx);
if (ret < 0) { av_log(NULL, AV_LOG_ERROR, "拷贝参数失败\n"); return ret; }

等等，素材第六步不是 GLOBAL_HEADER 吗？对，它在打开编码器之前设置：

// 第六步：全局头标志——部分封装器要求编解码参数放容器头而非每个包
if (ofmt_ctx->oformat->flags & AVFMT_GLOBALHEADER)
    enc_ctx->flags |= AV_CODEC_FLAG_GLOBAL_HEADER;

这个判断的意思是：先问封装器"你要不要全局头？"。MP4 要（extradata 写进文件头），ADTS 不要（每帧自带头）。avcodec_open2 会读这个标志决定把 extradata 放哪。实测 ADTS 封装器没有 AVFMT_GLOBALHEADER，标志不置位——符合预期。

# 实测（完整九步）
[ok  ] avformat_alloc_output_context2        oformat = adts
[ok  ] avformat_new_stream
[ok  ] avcodec_find_encoder_by_name("aac")
[ok  ] avcodec_alloc_context3
[ok  ] 参数设置(...)                          sample_fmt = fltp, channels = 2
[ok  ] GLOBAL_HEADER flag
[ok  ] avcodec_open2                          frame_size = 1024
[ok  ] codec_tag = 0
[ok  ] avcodec_parameters_from_context

=== 九步全部就绪，可以开始编码了（第 11 章 send/receive）===

frame_size = 1024 是编码器揭晓的关键数字：AAC 每次吃 1024 个采样样本，产出一个压缩包。你的数据流必须按这个尺寸喂给它——第 11 章的 send/receive 循环就是干这个的。

章末练习