简介本资源是一套基于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 打印所有可用设备名及支持格式如videoUSB Camera: 1920x108030fps, yuv420p。实际采集时你必须用这个输出里的完整设备名Linux 下是/dev/video0macOS 下是0或1Windows 下是videoUSB 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/10002.3 音频流初始化采样率、通道数、格式的“三重校验”麦克风设备常报“Unsupported sample format”——因为 ALSA 默认给s16而 FFmpeg 内部可能期望fltpfloat planar。更常见的是采样率不匹配摄像头是 30fps音频是 48kHz若不显式设置AVCodecContext.sample_rateavcodec_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()返回 -22EINVALav_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()阻塞超过 500mstop显示 CPU 占用 100%原因ALSA 设备默认缓冲区过大如period_size1024, buffer_size8192avdevice读取时等满一整个 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 sizegdb停在av_packet_unref()原因AVPacket被多次av_packet_unref()。典型场景queue_push()里av_packet_ref()了但queue_pop()后忘记av_packet_unref()导致出队两次时第二次unref释放已 free 的内存。解决用valgrind --toolmemcheck ./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// 假设新配置width1280, height720, fps25 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, params)。没有通用接口必须按编码器类型分支处理。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 驱动丢帧而日志里根本不会报错。希望帮到你。本文还有配套的精品资源点击获取