📚 课程目录第4章 FFmpeg重采样框架

4、FFmpeg重采样框架：libswresample库介绍、API概览

4.1 libswresample 在 FFmpeg 生态中的定位

在 FFmpeg 的音频处理链路中，libswresample（常简称为 swr）是专门负责音频重采样、声道布局转换、样本格式转换以及时间基调整的底层库。它位于 libavcodec 与 libavutil 之间，向上为编码器、过滤器提供统一的音频数据格式，向下则直接操作 PCM 缓冲区。与早期独立的 libavresample 不同，libswresample 自 FFmpeg 3.x 起成为默认的音频重采样实现，并被 libavfilter 的 aresample 滤镜、libavdevice 的采集模块以及诸多封装层广泛调用。

理解 libswresample 的关键在于：它并非简单执行“插值-抽取”算法，而是围绕一个核心结构体 SwrContext 构建的完整状态机。开发者通过配置输入/输出参数，由库内部自动选择最优的重采样算法（如线性、样条、FFT 加速的 sinc 等），并管理内部缓冲与延迟补偿。调试重采样问题时，绝大多数排查工作都围绕 SwrContext 的配置一致性、数据供给节奏以及延迟参数展开。

  核心概念：libswresample 的输入与输出三元组（样本格式、采样率、声道布局）必须分别明确指定。任何一项不匹配，都会触发隐式转换，而这种隐式转换往往是音调异常、声道错乱或时间戳漂移的根源。

4.2 API 核心调用流程

libswresample 的 API 设计遵循“配置-初始化-转换-释放”四步范式。与编码器不同，它没有“打开/关闭”的异步状态，所有操作都是同步的，但内部可能维护多相滤波器组或 FIFO 缓冲。调试时最常打交道的函数集中在 <libswresample/swresample.h> 中。

4.2.1 配置与初始化

// 1. 分配上下文
SwrContext *swr = swr_alloc();

// 2. 设置输入/输出参数（推荐使用 av_opt_set_* 系列）
av_opt_set_int(swr, "in_channel_layout",  in_layout,  0);
av_opt_set_int(swr, "in_sample_rate",     in_rate,    0);
av_opt_set_int(swr, "in_sample_fmt",      in_fmt,     0);
av_opt_set_int(swr, "out_channel_layout", out_layout, 0);
av_opt_set_int(swr, "out_sample_rate",    out_rate,   0);
av_opt_set_int(swr, "out_sample_fmt",     out_fmt,    0);

// 3. 初始化（内部完成滤波器设计、缓冲分配）
int ret = swr_init(swr);
if (ret < 0) {
    // 此处是调试第一站：参数不合法、布局冲突都会在此暴露
    av_log(NULL, AV_LOG_ERROR, "swr_init failed: %s\n", av_err2str(ret));
}

值得强调的是，swr_init() 并不执行任何样本转换，它只负责根据配置建立内部状态。如果输入与输出的采样率相同、格式相同、声道布局一致，swr 会进入“直通模式”，此时 swr_convert() 仅做内存拷贝。调试时可通过 swr_is_initialized(swr) 检查状态。

4.2.2 数据转换与缓冲管理

// 4. 转换数据（核心函数）
int swr_convert(struct SwrContext *s,
                uint8_t **out, int out_count,
                const uint8_t **in, int in_count);

// 5. 冲刷内部延迟（结尾调用）
swr_convert(s, out, out_count, NULL, 0);

// 6. 释放资源
swr_free(&swr);

这里有两个极易出错的细节：out_count 与 in_count 的换算关系。libswresample 要求调用者保证输出缓冲区足够容纳 out_count 个样本，而 in_count 是输入样本数。两者之间的比例由采样率决定，但声道数不影响样本数（样本数按单声道计）。例如从 48kHz 转 44.1kHz，若输入 48000 个样本，输出最多需要 44100 个样本（实际可能因内部延迟略多）。

调试建议：在调用 swr_convert() 之前，先使用 swr_get_out_samples(swr, in_count) 查询所需输出样本数，避免缓冲区溢出。该函数会考虑内部 FIFO 中残留的数据。

4.3 关键数据结构与参数映射

libswresample 的参数传递高度依赖 AVOption 机制，这意味着所有配置项都可以通过字符串键值对访问。下表列出了调试中最常检查的参数及其含义：

参数名	类型	调试关注点
`in_sample_rate`	int	必须大于 0，且与解码器实际输出一致
`out_sample_rate`	int	目标采样率，常见 44100/48000
`in_channel_layout`	uint64_t	使用 `AV_CH_LAYOUT_*` 宏，注意与 `av_get_default_channel_layout()` 区分
`out_channel_layout`	uint64_t	声道布局不匹配时，swr 会执行混音或抽声道
`in_sample_fmt`	enum AVSampleFormat	如 `AV_SAMPLE_FMT_FLTP` 与 `AV_SAMPLE_FMT_S16` 转换会触发格式重排
`swr_flags`	int	可设置 `SWR_FLAG_RESAMPLE` 强制重采样，否则可能直通
`min_comp` / `min_hard_comp`	double	压缩/硬压缩阈值，影响动态范围，调试音量异常时检查

4.4 典型场景：从解码到编码的重采样桥接

在实际调试中，最常见的场景是：解码器输出 48kHz/FLTP/立体声，而编码器（如 AAC-LC）要求 44100Hz/S16/立体声。此时需要构建一个 swr 实例完成三重转换。以下代码展示了完整的桥接逻辑，并标注了调试断点位置：

// 场景：FLTP 48k 立体声 → S16 44.1k 立体声
SwrContext *swr = swr_alloc();
av_opt_set_sample_fmt(swr, "in_sample_fmt",  AV_SAMPLE_FMT_FLTP, 0);
av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16,  0);
av_opt_set_int(swr, "in_sample_rate",  48000, 0);
av_opt_set_int(swr, "out_sample_rate", 44100, 0);
av_opt_set_int(swr, "in_channel_layout",  AV_CH_LAYOUT_STEREO, 0);
av_opt_set_int(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);

if (swr_init(swr) < 0) {
    // 断点1：检查参数是否被正确解析
    fprintf(stderr, "swr_init failed\n");
    return -1;
}

// 假设从解码器拿到一帧 FLTP 数据
uint8_t *in_data[2] = { decoded_frame->data[0], decoded_frame->data[1] };
int in_samples = decoded_frame->nb_samples;

// 计算输出缓冲大小
int out_samples = swr_get_out_samples(swr, in_samples);
uint8_t *out_data = av_malloc(out_samples * 2 * 2); // S16 双声道

// 断点2：转换前打印输入参数
av_log(NULL, AV_LOG_DEBUG, "in_rate=%d out_rate=%d in_fmt=%d out_fmt=%d\n",
       48000, 44100, AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16);

int converted = swr_convert(swr, &out_data, out_samples,
                            (const uint8_t **)in_data, in_samples);

// 断点3：检查 converted 是否等于预期值
if (converted < 0) {
    fprintf(stderr, "swr_convert error: %s\n", av_err2str(converted));
}

// 冲刷尾部延迟
while (1) {
    int ret = swr_convert(swr, &out_data, out_samples, NULL, 0);
    if (ret <= 0) break;
    // 处理 ret 个样本
}

4.5 常见误区与调试复盘

误区一：忽略声道布局的隐式转换。当输入为立体声、输出为单声道时，swr 默认执行下混（downmix）。但若输入是 5.1 环绕声，输出立体声，则下混系数由内部矩阵决定，可能造成音量下降或相位抵消。调试时务必使用 swr_get_out_samples() 验证样本数，并使用 av_channel_layout_describe() 打印实际布局。

误区二：混淆样本数与字节数。许多新手在分配输出缓冲区时，直接使用 in_samples * 2（假设 S16 双声道），但若输出格式为 FLTP（浮点平面），每个样本占 4 字节且数据分开存储，缓冲区大小应为 out_samples * 4。这种错误通常导致内存越界或转换后数据“花屏”般的噪声。

误区三：忘记冲刷内部延迟。重采样滤波器具有固有的群延迟（通常为数十个样本）。如果转换完所有输入后直接释放 swr，尾部会丢失一段音频。正确做法是在输入耗尽后，以 NULL 输入调用 swr_convert() 直到返回 0。调试时可通过对比输入总样本数与输出总样本数来验证是否丢失数据。

复盘建议：当遇到重采样后音调异常（偏高或偏低），首先检查采样率参数是否写反；当遇到声道内容串扰，检查声道布局掩码是否使用了错误的宏（如 AV_CH_LAYOUT_STEREO_DOWNMIX 与 AV_CH_LAYOUT_STEREO 的区别）；当遇到转换后数据全部为 0，检查输入数据指针是否指向了 frame->extended_data 而非 data——对于平面格式，必须使用 extended_data 数组。

最后，libswresample 提供了 swr_convert_frame() 这一便捷 API，可直接操作 AVFrame，内部自动处理缓冲与格式匹配。在调试阶段，建议先用该函数快速验证参数配置是否正确，再切换到底层 swr_convert() 进行精细控制。通过上述 API 概览与调试要点，你已经掌握了定位重采样问题的基础工具集。