简介：本资源是一套基于FFmpeg API实现摄像头视频与麦克风音频同步采集的完整C++工程，面向多媒体开发初学者及音视频工程师，解决DirectShow框架学习门槛高、FFmpeg设备采集示例稀缺的实践痛点，适用于本地录制、推流预处理等轻量级音视频采集场景。压缩包共162个文件，含102个头文件（h）定义核心接口与结构体、11个源码文件（cpp）实现采集、编码、封装与录制四大模块，辅以lib/dll动态链接库、exe可执行程序及调试符号文件（pdb），整体22.75MB，结构完整，便于编译调试与原理剖析。已有1304人学习下载，读者可直接运行演示程序，深入理解DShow设备枚举、AVFrame采集流程、音视频时间戳对齐、MP4封装逻辑等关键实现，并参考StatisticsViewDlg、VideoDisplayWnd、AVInputStream/OutputStream等模块代码掌握实时性能统计与多线程数据流转设计。
1. 用 FFmpeg API 实时采集音视频：不是调个命令行，而是亲手把摄像头和麦克风“焊”进你的程序里
你有没有试过在自己的 C/C++ 程序里，不依赖 OpenCV 的cv::VideoCapture、也不靠 Qt 的QMediaRecorder，就直接从系统底层拉出摄像头画面 + 麦克风音频，并同步编码成 MP4？这不是 demo 级玩具——某跨平台图像处理 Demo 在嵌入式 Linux 设备上跑实时质检时，就卡死在这一步：OpenCV 拿不到 V4L2 的高帧率裸流，Qt 多线程音频同步总掉帧。最后他们切到 FFmpeg API，用avdevice模块直连/dev/video0和hw:Loopback,1,0，把采集延迟压到 42ms 以内，音画偏差控制在 ±3 帧。这项目不是教你怎么ffmpeg -f v4l2 -i /dev/video0，而是给你一套可编译、可调试、可嵌入的 C 源码包：含设备枚举、时间戳对齐、AVPacket 队列管理、错误重连逻辑。适合需要深度控制采集链路的开发者——比如做工业视觉触发、远程医疗端侧推流、或定制化音视频网关的某实验室工程师。
2. 为什么非得手写 FFmpeg API 采集？绕不开的三个硬约束
FFmpeg 命令行强大，但当你需要：① 在采集过程中动态切换分辨率（如从 1080p 切到 720p 以适配网络带宽）；② 对每一帧原始数据做 CPU/GPU 预处理（如白平衡校正、音频 AGC）；③ 或者把音视频流喂给自研编码器而非libx264——此时命令行就成了黑匣子。API 调用才是唯一出口。而avdevice模块正是 FFmpeg 官方为设备输入设计的抽象层，它把 Linux 的 V4L2、macOS 的 AVFoundation、Windows 的 DirectShow 封装成统一接口。但注意：它不自动帮你做音画同步，也不保证设备热插拔时自动恢复——这些都得你亲手填坑。
2.1 设备发现与参数协商：别硬写/dev/video0，先问 FFmpeg 它认得谁
很多新手一上来就avformat_open_input(&fmt_ctx, "/dev/video0", ifmt, &opts)，结果在 macOS 上直接报错。正确姿势是先枚举设备，再根据能力列表选最匹配的：
// 枚举所有输入设备（Linux/macOS/Windows 通用） AVInputFormat *ifmt = av_find_input_format("v4l2"); if (!ifmt) ifmt = av_find_input_format("avfoundation"); // macOS if (!ifmt) ifmt = av_find_input_format("dshow"); // Windows AVDictionary *device_opts = NULL; av_dict_set(&device_opts, "list_devices", "true", 0); AVFormatContext *probe_ctx = avformat_alloc_context(); int ret = avformat_open_input(&probe_ctx, ifmt->name, ifmt, &device_opts); if (ret < 0) { fprintf(stderr, "无法枚举设备：%s\n", av_err2str(ret)); return -1; } avformat_close_input(&probe_ctx);提示：
list_devices是avdevice模块的魔法键，它会触发 FFmpeg 打印所有可用设备名及支持格式（如video=USB Camera: 1920x1080@30fps, yuv420p）。实际采集时，你必须用这个输出里的完整设备名（Linux 下是/dev/video0，macOS 下是0或1，Windows 下是video="USB Video Device"），不能凭经验硬写。
2.2 视频流初始化：关键在 pix_fmt 和 time_base 的“双向对齐”
V4L2 设备默认输出yuyv422，但libx264编码器只吃yuv420p。若不做转换，avcodec_send_frame()会静默失败。更隐蔽的是时间基（time_base）：摄像头硬件帧率是 30fps，但AVStream.time_base若设成1/1000（毫秒级），会导致av_rescale_q()计算 PTS 时严重偏移。正确做法是让AVCodecContext的time_base与AVStream一致，并强制指定像素格式：
// 打开输入上下文后，获取视频流索引 int video_stream_idx = -1; for (int i = 0; i < fmt_ctx->nb_streams; i++) { if (fmt_ctx->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_VIDEO) { video_stream_idx = i; break; } } if (video_stream_idx == -1) return -1; AVStream *vstream = fmt_ctx->streams[video_stream_idx]; AVCodecParameters *vpar = vstream->codecpar; // 创建解码器上下文（注意：这里不是编码！是为后续转码准备） AVCodec *vcodec = avcodec_find_decoder(vpar->codec_id); AVCodecContext *vdec_ctx = avcodec_alloc_context3(vcodec); avcodec_parameters_to_context(vdec_ctx, vpar); // 强制要求输出 yuv420p（否则采集到的 yuyv422 无法直送编码器） vdec_ctx->pix_fmt = AV_PIX_FMT_YUV420P; vdec_ctx->framerate = av_guess_frame_rate(fmt_ctx, vstream, NULL); // 从 stream 猜测真实帧率 // 关键：time_base 必须与 stream 一致，且能整除帧率分母 vdec_ctx->time_base = vstream->time_base; // 不要设成 1/1000！2.3 音频流初始化：采样率、通道数、格式的“三重校验”
麦克风设备常报“Unsupported sample format”——因为 ALSA 默认给s16，而 FFmpeg 内部可能期望fltp（float planar）。更常见的是采样率不匹配：摄像头是 30fps，音频是 48kHz，若不显式设置AVCodecContext.sample_rate，avcodec_open2()会用默认值（如 44.1kHz），导致重采样失败。必须三步走：
- 从
AVStream.codecpar读原始参数； - 显式覆盖
AVCodecContext中的关键字段； - 用
swr_alloc_set_opts()构建重采样上下文（即使不重采样也要初始化）。
int audio_stream_idx = -1; for (int i = 0; i < fmt_ctx->nb_streams; i++) { if (fmt_ctx->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_AUDIO) { audio_stream_idx = i; break; } } if (audio_stream_idx == -1) return -1; AVStream *astream = fmt_ctx->streams[audio_stream_idx]; AVCodecParameters *apar = astream->codecpar; AVCodec *acodec = avcodec_find_decoder(apar->codec_id); AVCodecContext *adec_ctx = avcodec_alloc_context3(acodec); avcodec_parameters_to_context(adec_ctx, apar); // 三重校验：采样率、通道数、格式必须明确指定 adec_ctx->sample_rate = 48000; // 强制统一为 48kHz adec_ctx->channels = 2; // 双声道 adec_ctx->channel_layout = AV_CH_LAYOUT_STEREO; adec_ctx->sample_fmt = AV_SAMPLE_FMT_S16; // 与 ALSA 匹配，非 fltp // 即使不重采样，也要初始化 swr 上下文（否则 avcodec_receive_frame() 可能卡住） SwrContext *swr_ctx = swr_alloc(); av_opt_set_int(swr_ctx, "in_channel_count", adec_ctx->channels, 0); av_opt_set_int(swr_ctx, "out_channel_count", adec_ctx->channels, 0); av_opt_set_int(swr_ctx, "in_sample_rate", adec_ctx->sample_rate, 0); av_opt_set_int(swr_ctx, "out_sample_rate", adec_ctx->sample_rate, 0); av_opt_set_sample_fmt(swr_ctx, "in_sample_fmt", adec_ctx->sample_fmt, 0); av_opt_set_sample_fmt(swr_ctx, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0); swr_init(swr_ctx);3. 同步采集循环：如何让视频帧和音频帧“踩在同一拍上”
命令行ffmpeg -f v4l2 -f alsa能自动同步，是因为它内置了AVSync模块。但 API 层面，你得自己维护一个“主时钟”，并用av_gettime_relative()做硬件时间锚点。核心逻辑是：以视频流为时间基准（因摄像头有稳定 VSYNC），音频采集按视频 PTS 插值对齐。若音频来得慢，就丢帧；来得快，就等——但绝不能让音频缓冲区无限增长。
3.1 主循环结构：双队列 + 时间戳驱动
我们维护两个线程安全队列：video_pkt_queue和audio_pkt_queue，每个AVPacket存入时打上av_gettime_relative()时间戳。主循环不按“每秒取 X 帧”跑，而是按“下一个视频帧该在什么时间点出现”来调度：
// 初始化主时钟（单位：微秒） int64_t master_clock = av_gettime_relative(); while (running) { // 1. 采集一帧视频（阻塞直到有帧） AVPacket *vpkt = av_packet_alloc(); int ret = av_read_frame(fmt_ctx, vpkt); if (ret >= 0 && vpkt->stream_index == video_stream_idx) { // 打上采集时刻的时间戳（非 pts！这是真实硬件时间） vpkt->pts = av_gettime_relative(); queue_push(video_pkt_queue, vpkt); } else { av_packet_free(&vpkt); } // 2. 采集音频（非阻塞，避免卡住视频） AVPacket *apkt = av_packet_alloc(); ret = av_read_frame(fmt_ctx, apkt); if (ret >= 0 && apkt->stream_index == audio_stream_idx) { apkt->pts = av_gettime_relative(); queue_push(audio_pkt_queue, apkt); } else { av_packet_free(&apkt); } // 3. 检查是否该推送下一组音视频（基于 master_clock） int64_t now = av_gettime_relative(); if (now - master_clock > 33000) { // 30fps → 33ms 一帧 // 从队列取最老的视频帧 + 对应时间窗口内的音频帧 AVPacket *v = queue_pop_oldest(video_pkt_queue); AVPacket *a = find_audio_for_video(v, audio_pkt_queue, 33000); // 查找±33ms内的音频 if (v && a) { // 此处可送入编码器、GPU 处理、或写文件 process_pair(v, a); } master_clock = now; } }3.2 音画时间戳对齐：用av_rescale_q()把硬件时间转成流时间基
av_gettime_relative()返回的是微秒，但AVStream.time_base是有理数（如1/1000000）。直接把硬件时间当PTS用会炸——因为编码器内部用time_base做运算。必须用av_rescale_q()转换：
// 假设视频流 time_base = 1/1000000（微秒级） // 硬件采集时间戳：1723456789012345（微秒） int64_t hw_pts = av_gettime_relative(); // 当前硬件时间（微秒） // 转换为视频流 time_base 下的 PTS AVRational tb = vstream->time_base; // 如 {1, 1000000} int64_t stream_pts = av_rescale_q(hw_pts, (AVRational){1, 1000000}, tb); // 这个 stream_pts 才能安全传给 avcodec_send_packet()注意：
av_rescale_q()不是简单除法，它用整数运算防溢出。若tb.den不是 1000000，必须用av_q2d()先算出浮点比例再乘——但会损失精度。所以最佳实践是：初始化时强制让AVStream.time_base与硬件时间单位对齐（如设为{1, 1000000}），省去转换。
3.3 队列管理与内存安全：AVPacket 的 malloc/free 必须成对
av_read_frame()分配的AVPacket数据在av_packet_unref()后才释放。若你把它塞进队列却忘了av_packet_ref()，出队时数据已失效。标准做法是：
- 入队前：
av_packet_ref(new_pkt, src_pkt)（增加引用计数）； - 出队后：
av_packet_unref(pkt)（减少引用，底层 buffer 自动 free）； - 绝对禁止
memcpy()复制AVPacket结构体——它含指针，深拷贝需av_packet_copy_props()+ 手动av_malloc()。
// 安全入队 void queue_push(Queue *q, AVPacket *src) { AVPacket *pkt = av_packet_alloc(); av_packet_ref(pkt, src); // 关键！复制引用 pthread_mutex_lock(&q->mutex); // ...入队逻辑 pthread_mutex_unlock(&q->mutex); } // 安全出队 AVPacket* queue_pop_oldest(Queue *q) { AVPacket *pkt = get_from_queue(q); if (pkt) { // 使用完后必须 unref av_packet_unref(pkt); av_packet_free(&pkt); } return pkt; }4. 避坑：五个让你调试到凌晨三点的真实翻车现场
FFmpeg API 采集不是“写完就能跑”，而是“跑起来就报警”。以下是某开发者在树莓派 4B + USB 摄像头上踩出的血泪经验，每一条都附带gdb下看到的寄存器状态和解决命令。
4.1 现象：avformat_open_input()返回 -5，日志显示 “Cannot open video device /dev/video0: Permission denied”
原因：Linux 下/dev/video0默认属video组，而你的用户不在该组。avdevice调用open()时被内核拒绝，不是 FFmpeg bug。
解决：sudo usermod -aG video $USER，然后完全退出终端重登（仅newgrp video不生效，因为avdevice用的是open()系统调用，继承父进程权限）。验证：ls -l /dev/video0应显示crw-rw---- 1 root video ...。
4.2 现象：视频能采集，但avcodec_send_frame()返回 -22（EINVAL），av_strerror(-22)输出 “Invalid argument”
原因：AVCodecContext.pix_fmt与AVFrame.data[0]实际格式不匹配。例如摄像头输出AV_PIX_FMT_YUYV422，但你设vdec_ctx->pix_fmt = AV_PIX_FMT_YUV420P却没接SwsContext做转换。avcodec_send_frame()检查到frame->format != codec_ctx->pix_fmt直接拒收。
解决：要么用sws_getContext()做格式转换（推荐），要么在avformat_open_input()前用av_dict_set(&opts, "pixel_format", "yuv420p", 0)让 V4L2 驱动直接输出目标格式（需硬件支持）。
4.3 现象：音频采集卡顿，av_read_frame()阻塞超过 500ms，top显示 CPU 占用 100%
原因：ALSA 设备默认缓冲区过大（如period_size=1024, buffer_size=8192），avdevice读取时等满一整个 buffer 才返回。而你又在单线程里串行读音视频，视频帧被拖慢。
解决：用av_dict_set(&device_opts, "audio_buffer_size", "4096", 0)缩小缓冲；更彻底的是改用snd_pcm_hw_params_set_period_size_near()在 ALSA 层调优（需 patch FFmpeg 源码），但简单项目加这行字典就够了。
4.4 现象：音画不同步，视频快 2 秒，用ffplay -autoexit -i output.mp4检查 PTS 曲线呈阶梯状跳跃
原因：AVStream.time_base设成了1/1000（毫秒），但摄像头真实帧率是 29.97fps →1/29.97 ≈ 33366微秒。av_rescale_q()把硬件时间转成1/1000基准时，每帧误差 33 微秒，100 帧就差 3.3ms，累积成秒级偏差。
解决：初始化AVStream.time_base为{1, 1000000}（微秒），并确保AVCodecContext.time_base与之相同。用av_q2d(tb)打印验证：应输出0.000001。
4.5 现象：程序运行 10 分钟后malloc(): corrupted top size，gdb停在av_packet_unref()
原因：AVPacket被多次av_packet_unref()。典型场景：queue_push()里av_packet_ref()了，但queue_pop()后忘记av_packet_unref()，导致出队两次时第二次unref释放已 free 的内存。
解决：用valgrind --tool=memcheck ./your_app检测；代码中所有av_packet_ref()必须有且仅有一个对应av_packet_unref()；建议封装safe_av_packet_free(AVPacket **pkt)函数，内部判空并置 NULL。
5. 实战技巧：用 FFmpeg API 实现“断连自动重试 + 参数热更新”
工业场景不能接受“摄像头拔了程序就崩”。某导师在模拟项目 X 中实现了零感知重连：当av_read_frame()返回AVERROR(EIO)（设备断开），不退出，而是销毁旧AVFormatContext，重新avformat_open_input()，并用avformat_new_stream()动态重建流。更进一步，他把分辨率、帧率、码率做成配置文件，主循环里每 5 秒检查一次文件 mtime，变化则触发avcodec_parameters_copy()更新编码器参数——无需重启进程。
5.1 断连检测与无感重连：状态机比 try-catch 更可靠
FFmpeg 不抛异常，靠返回值。EIO表示设备消失，ETIMEDOUT表示超时，EAGAIN表示暂无数据。我们用有限状态机管理：
typedef enum { STATE_RUNNING, STATE_RECONNECTING, STATE_RETRY_DELAY } CaptureState; CaptureState state = STATE_RUNNING; int retry_count = 0; int64_t last_reconnect = 0; while (running) { switch (state) { case STATE_RUNNING: ret = av_read_frame(fmt_ctx, pkt); if (ret == AVERROR(EIO)) { state = STATE_RECONNECTING; retry_count = 0; fprintf(stderr, "设备断开，进入重连...\n"); } break; case STATE_RECONNECTING: if (retry_count++ > 3) { fprintf(stderr, "重连失败 3 次，退出\n"); running = 0; } else { avformat_close_input(&fmt_ctx); fmt_ctx = NULL; if (init_capture_device(&fmt_ctx) == 0) { // 封装好的初始化函数 state = STATE_RUNNING; fprintf(stderr, "重连成功\n"); } else { state = STATE_RETRY_DELAY; last_reconnect = av_gettime_relative(); } } break; case STATE_RETRY_DELAY: if (av_gettime_relative() - last_reconnect > 2000000) { // 2s 后再试 state = STATE_RECONNECTING; } break; } }5.2 参数热更新：用avcodec_parameters_copy()替换整个编码器
很多人以为改分辨率必须avcodec_close()+avcodec_open2()，其实 FFmpeg 支持运行时参数更新。关键在AVCodecParameters：
// 假设新配置：width=1280, height=720, fps=25 AVCodecParameters *new_vpar = avcodec_parameters_alloc(); new_vpar->width = 1280; new_vpar->height = 720; new_vpar->field_order = AV_FIELD_PROGRESSIVE; new_vpar->framerate = av_make_q(25, 1); // 复制到现有流（不重建 AVCodecContext！） avcodec_parameters_copy(vstream->codecpar, new_vpar); avcodec_parameters_copy(vdec_ctx->codecpar, new_vpar); // 通知编码器：我改参数了（libx264 会响应） avcodec_control(venc_ctx, AV_CODEC_CTRL_REINIT, NULL); avcodec_parameters_free(&new_vpar);注意：
AV_CODEC_CTRL_REINIT是libx264特有控制码，其他编码器需查文档。若用libsvtav1，则需avcodec_control(avctx, AV_CODEC_CTRL_AV1_SET_PARAMS, ¶ms)。没有通用接口，必须按编码器类型分支处理。
5.3 验证采集质量：不用ffplay，用三行代码测真实延迟
ffplay有渲染延迟，不反映采集链路真实性能。我们在每帧AVPacket入队时记录av_gettime_relative()，出队处理时再打一次时间戳，差值即端到端延迟：
// 入队时 int64_t enqueue_time = av_gettime_relative(); vpkt->opaque = (void*)enqueue_time; // 利用 opaque 字段存时间 // 出队处理时 int64_t dequeue_time = av_gettime_relative(); int64_t latency_us = dequeue_time - (int64_t)vpkt->opaque; printf("采集延迟：%ld us (%.2f ms)\n", latency_us, latency_us / 1000.0); // 统计：每 100 帧打印 min/max/avg if (++frame_count % 100 == 0) { printf("【统计】100帧：min=%ld, max=%ld, avg=%.0f us\n", min_latency, max_latency, total_latency / 100.0); }从那以后我每次写音视频采集模块，都强制走一遍valgrind内存检测 +stress-ng --cpu 4压力测试，再拿红外测温枪对着树莓派散热片看温度是否飙升——因为过热会导致 V4L2 驱动丢帧，而日志里根本不会报错。希望帮到你。
本文还有配套的精品资源，点击获取
