简介：本资源是一套基于FFmpeg API实现摄像头视频与麦克风音频同步采集的完整C++工程，面向多媒体开发初学者及音视频工程师，解决DirectShow框架学习门槛高、FFmpeg设备采集示例稀缺的实践痛点，适用于本地录制、推流预处理等轻量级音视频采集场景。压缩包共162个文件，含102个头文件（h）与11个源码文件（cpp），涵盖采集（AVInputStream）、编码封装（AVOutputStream）、显示渲染（VideoDisplayWnd）、设备选择（SelectCaptureDeviceDlg）等核心模块；另有9个DLL/LIB依赖库、1个可执行程序（exe）及配套资源文件，整体大小22.75MB。已有1304人学习下载，提供从命令行设备枚举、工程编译运行到各模块源码级实现原理的完整链路，包含DShow设备适配细节、音视频时间戳同步策略、多线程采集封装结构等关键排错与设计经验。
1. 为什么不用现成的推流工具，而要亲手调 FFmpeg API 做音视频采集？
因为“能跑通”和“能交付”之间，隔着整整一套可控、可调试、可嵌入的采集链路。我带过两个课程设计小组，学生用 OBS 或 ffmpeg 命令行一键推流，答辩时被问“如果麦克风突然静音，你怎么定位是驱动问题、权限问题，还是音频采样格式不匹配？”，当场卡住——命令行是黑匣子，API 才是手术刀。本方案不是教你怎么拼一条ffmpeg -f v4l2 -i /dev/video0 ...，而是从零手写 C++ 程序，用 FFmpeg 官方 API（avdevice + avcodec + avformat）同步打开摄像头与麦克风，完成设备枚举、参数协商、时间戳对齐、帧级缓冲管理、异常重连等真实工业场景必做动作。它适合需要交毕设/课设源码+设计文档的学生，也适合嵌入式或边缘端需轻量集成音视频采集能力的开发者。整套代码无第三方封装层，所有关键路径（如 AVPacket 分配策略、audio resample 的 buffer 复用逻辑、video timestamp 校准公式）全部展开，附带完整编译脚本、设备检测工具和断点调试建议。
2. 总体架构设计：三层结构与四个核心模块的职责划分
本方案采用清晰的分层架构：底层为 FFmpeg 原生 API 调用层（纯 C 接口封装），中间为设备抽象层（DeviceManager），上层为业务控制层（CaptureController）。不引入 Qt、OpenCV 等 GUI 或图像处理库，避免依赖污染，确保在无图形界面的 Linux ARM 设备（如树莓派、Jetson Nano）上可直接编译运行。四个核心模块分工明确：
- DeviceEnumerator 模块：负责枚举系统可用的视频输入设备（v4l2、dshow、avfoundation）和音频输入设备（alsa、pulse、coreaudio），输出标准化设备列表（含名称、ID、支持格式），解决“找不到摄像头/麦克风”的第一道门槛；
- StreamConfigurator 模块：针对选定设备，协商最优采集参数（分辨率、帧率、采样率、声道数、像素/样本格式），自动 fallback 到系统实际支持的组合，避免硬编码导致的
Invalid argument错误； - SyncCaptureEngine 模块：核心采集引擎，实现音视频时间戳对齐（PTS 同步）、独立线程双路采集（video thread + audio thread）、环形缓冲区（RingBuffer）跨线程安全传递 AVFrame，杜绝音画不同步；
- OutputMuxer 模块：将采集帧实时 mux 成 MP4/FLV 文件或 RTMP 流，支持 H.264 + AAC 编码（软编）或直接使用设备原生编码器（如 Raspberry Pi 的 MMAL），并暴露关键统计回调（丢帧数、音频抖动 ms、PTS 差值）。
提示：本方案默认关闭硬件加速编码（如 nvenc、qsv），优先保障跨平台可编译性；若需启用，仅需修改
EncoderFactory::createVideoEncoder()中的 codec_id 和 option 字典，无需重构采集主干。
2.1 DeviceEnumerator：如何让程序“看见”你的摄像头和麦克风
Linux 下设备枚举依赖avdevice_list_input_sources()，但该函数返回的设备名（如video=HD Pro Webcam C920）常与/dev/video*不一致，且不包含音频设备。我们绕过高层封装，直接解析 udev 数据并交叉验证：
# 实际调试中，我总先手动执行这三行确认设备状态 ls /dev/video* # 查看视频设备节点 arecord -l # 列出 ALSA 音频卡及设备 cat /proc/asound/cards # 验证声卡是否被内核识别对应 C++ 实现中，DeviceEnumerator::listVideoDevices()先调用av_input_video_device_next(nullptr)获取 FFmpeg 支持的输入设备类型，再对每种类型（如"v4l2"）调用avdevice_list_devices()获取具体设备。关键在于：必须在调用前显式注册设备组件：
// 初始化时必须注册，否则 list_devices 返回空 avdevice_register_all(); // 注意：此函数已废弃，但旧版 FFmpeg 仍需 // 新版（>=4.4）应改用： avformat_network_init(); // 并确保链接时包含 -lavdevice我们进一步增强鲁棒性：对每个返回的AVDeviceInfo，尝试avformat_open_input()打开设备（超时 500ms），仅将成功打开的设备加入最终列表。这样可过滤掉虽被系统识别但实际不可用的设备（如被其他进程独占的摄像头）。
2.2 StreamConfigurator：参数协商不是“选最高”，而是“找交集”
学生常犯的错误是：硬写width=1920, height=1080, fps=30，结果在老旧 USB 摄像头上直接失败。正确做法是让 FFmpeg 告诉你设备真正支持什么：
// 以 v4l2 为例：先获取设备支持的所有格式 AVInputFormat *iformat = av_find_input_format("v4l2"); AVFormatContext *ic = avformat_alloc_context(); ic->interrupt_callback.callback = interrupt_cb; // 设置超时中断 int ret = avformat_open_input(&ic, "/dev/video0", iformat, &options); if (ret < 0) { /* 处理错误 */ } // 遍历所有支持的视频流格式 for (int i = 0; i < ic->nb_streams; i++) { AVStream *st = ic->streams[i]; if (st->codecpar->codec_type == AVMEDIA_TYPE_VIDEO) { // 解析 st->codecpar->codec_id 及其支持的分辨率/帧率 // 此处省略具体解析逻辑，见源码 stream_configurator.cpp 第 127 行 } } avformat_close_input(&ic);StreamConfigurator的核心策略是：
- 优先级队列：按
width×height×fps降序排列候选分辨率（如[1920x1080@30, 1280x720@60, 640x480@30]）； - 逐级试探：对每个候选，构造
AVDictionary *format_opts，设置framerate="30",video_size="1920x1080"，调用avformat_open_input()； - fallback 机制：若失败，自动降级到下一档，并记录日志
"Failed 1920x1080@30 → trying 1280x720@60"； - 音频对齐：视频帧率确定后，音频采样率强制匹配为
44100或48000（主流设备均支持），声道数固定为2（立体声），避免 resample 引入延迟。
注意：Windows 下 dshow 设备需额外设置
video_device_number和audio_device_number，这些索引由DeviceEnumerator返回的列表顺序决定，而非系统设备管理器中的序号。
2.3 SyncCaptureEngine：音视频同步不是“加个 sleep”，而是 PTS 校准
双线程采集天然存在时钟漂移。常见错误方案：视频线程usleep(33333)，音频线程usleep(21333)（对应 48kHz 单帧），结果运行 10 分钟音画偏移超 2 秒。本方案采用Master Clock 同步法：以视频时钟为 Master，音频采集线程根据当前视频 PTS 动态调整下一次采集时机。
核心逻辑在SyncCaptureEngine::audioCaptureLoop()：
// 音频线程主循环（简化版） while (running_) { // 1. 获取当前视频帧的 PTS（来自 video_ring_buffer） int64_t video_pts = video_clock_.getLatestPTS(); // 2. 计算音频应采集的时间点（单位：微秒） // 假设音频采样率 48000，每帧 1024 样本 → 每帧耗时 1024/48000≈21.33ms int64_t target_audio_us = video_pts * 1000000LL / av_q2d(video_time_base_); // 3. 计算需等待的微秒数（考虑线程调度误差） int64_t now_us = av_gettime_relative(); int64_t wait_us = target_audio_us - now_us + 5000; // +5ms 补偿误差 if (wait_us > 0) { av_usleep(wait_us); } // 4. 采集一帧音频并打上校准后 PTS AVFrame *audio_frame = captureAudioFrame(); audio_frame->pts = av_rescale_q(target_audio_us, AV_TIME_BASE_Q, audio_time_base_); audio_ring_buffer_.push(audio_frame); }video_clock_是一个线程安全的单例，由视频采集线程在每次成功 push 帧时更新latest_pts_。该设计确保音频帧 PTS 始终锚定在视频时间轴上，即使某次音频采集因系统负载延迟，后续帧也会自动追赶，而非累积偏移。
2.4 OutputMuxer：muxer 不是“塞数据”，而是流控与错误恢复
OutputMuxer模块直连 FFmpeg 的AVFormatContext，但关键在于主动流控。若采集速度 > 编码/写入速度，环形缓冲区会爆满，导致丢帧。我们实现两级保护：
- 缓冲区水位告警：当
video_ring_buffer_.size() > buffer_capacity_ * 0.8时，触发onHighWaterMark()回调，可选择降低采集帧率或打印警告； - 写入失败恢复：
av_interleaved_write_frame()返回负值时，不直接退出，而是：- 检查错误码：
AVERROR(EIO)尝试重连设备；AVERROR(ENOMEM)清空缓冲区；AVERROR_INVALIDDATA跳过当前帧； - 记录连续失败次数，超过 3 次则触发
onMuxerError()通知上层重启 muxer。
- 检查错误码：
int ret = av_interleaved_write_frame(ofmt_ctx_, &pkt); if (ret < 0) { char errbuf[128]; av_strerror(ret, errbuf, sizeof(errbuf)); LOG_WARN("Muxer write failed: %s (code %d)", errbuf, ret); if (ret == AVERROR(EIO)) { // 设备可能断开，触发重连 reconnectDevice(); } else if (ret == AVERROR(ENOMEM)) { // 内存不足，清空音频缓冲（视频缓冲更关键，保留） audio_ring_buffer_.clear(); } av_packet_unref(&pkt); continue; }该策略使程序在 USB 摄像头意外拔插、网络流目标宕机等场景下，能自动恢复而非崩溃，符合工业级健壮性要求。
3. 关键实现细节：从设备打开到帧级处理的 7 个技术决策点
本章不罗列 API 函数，而是聚焦 7 个真实开发中必须拍板的技术决策点。每个点都附带代码片段、参数含义说明、以及我踩过的坑。
3.1 视频设备打开：为什么必须设置framerate选项而非time_base
很多教程教你在avformat_open_input()前设置AVDictionary *format_opts，然后av_dict_set(&format_opts, "framerate", "30", 0)。这看似合理，但实测在 v4l2 下无效——因为 v4l2 的帧率控制在ioctl(VIDIOC_S_PARM)中完成，FFmpeg 的framerate选项只影响某些封装器（如 image2）。正确做法是：在avformat_find_stream_info()后，手动修改视频流的r_frame_rate和avg_frame_rate：
// 在 avformat_find_stream_info() 之后 AVStream *vst = ic->streams[video_stream_index]; vst->r_frame_rate = av_make_q(30, 1); vst->avg_frame_rate = av_make_q(30, 1); // 这会强制解复用器按 30fps 解析 PTS血泪经验：某次在树莓派上，摄像头固件报告支持
30fps，但实际只稳定输出25fps。若强行设r_frame_rate=30/1，会导致 PTS 跳变。解决方案是：先以15fps打开，用av_q2d(vst->r_frame_rate)实测真实帧率，再动态调整。
3.2 音频重采样：为什么swr_convert()必须预分配输出 buffer
libswresample的swr_convert()要求输出 buffer 大小精确匹配目标样本数。学生常写：
uint8_t *out_buf; int out_samples = swr_get_out_samples(swr_ctx, in_samples); // 错！ swr_convert(swr_ctx, &out_buf, out_samples, (const uint8_t**)&in_buf, in_samples);问题在于swr_get_out_samples()返回的是“理论最大值”，实际转换后样本数可能更少（如重采样时相位对齐需要丢弃首尾若干样本）。正确流程是：
- 调用
swr_convert()时传入NULL作为输出 buffer，获取实际需要的out_samples； - malloc 对应大小的 buffer；
- 再次调用
swr_convert()填充数据。
// 第一次：获取所需输出样本数 int out_samples = swr_convert(swr_ctx, NULL, 0, (const uint8_t**)&in_buf, in_samples); // 分配 buffer（注意：swr_convert 要求按 channel 对齐） uint8_t **out_buf; av_samples_alloc_array_and_samples(&out_buf, NULL, out_channels, out_samples, out_sample_fmt, 0); // 第二次：执行转换 int real_out = swr_convert(swr_ctx, out_buf, out_samples, (const uint8_t**)&in_buf, in_samples);3.3 时间戳生成：av_gettime_relative()与av_gettime()的选择
采集线程需为每一帧打上 PTS。av_gettime()返回自 Unix epoch 的微秒数，但受系统时钟跳变影响（如 NTP 校正）；av_gettime_relative()返回自程序启动的单调递增时间，不受系统时钟干扰。必须用av_gettime_relative()：
// 视频帧 PTS（单位：微秒） int64_t now_us = av_gettime_relative(); video_frame->pts = av_rescale_q(now_us, AV_TIME_BASE_Q, video_time_base_);但注意：video_time_base_不能简单设为AVRational{1, 1000000}。它应与视频流的time_base一致（如AVRational{1, 1000}表示毫秒级），否则 muxer 会因时间基不匹配报错。因此，video_time_base_应在StreamConfigurator协商后确定，通常取av_inv_q(av_guess_frame_rate(ic, vst, NULL))的倒数。
3.4 环形缓冲区：为什么用std::vector<AVFrame*>而非std::queue
跨线程传递AVFrame*时，必须保证帧内存生命周期长于消费线程处理时间。std::queue的pop()会销毁指针，但AVFrame内存需由av_frame_free()释放。我们采用引用计数式环形缓冲区：
class RingBuffer { private: std::vector<std::shared_ptr<AVFrame>> buffer_; size_t head_, tail_, capacity_; public: void push(std::shared_ptr<AVFrame> frame) { if (isFull()) dropOldest(); // 主动丢帧，避免阻塞 buffer_[tail_] = frame; tail_ = (tail_ + 1) % capacity_; } std::shared_ptr<AVFrame> pop() { if (isEmpty()) return nullptr; auto frame = buffer_[head_]; buffer_[head_].reset(); // 释放 shared_ptr 引用 head_ = (head_ + 1) % capacity_; return frame; } };std::shared_ptr<AVFrame>封装了av_frame_free()的自动释放，且push/pop操作原子性由std::mutex保证。相比裸指针，它彻底规避了“生产者释放内存，消费者访问野指针”的经典并发 bug。
3.5 设备重连：如何检测摄像头是否被拔掉
Linux 下read()视频设备文件返回0表示 EOF（设备断开），但 v4l2 驱动常返回-1并置errno=ENODEV。可靠检测方式是：在采集循环中检查av_read_frame()返回值：
int ret = av_read_frame(ic_, &pkt); if (ret < 0) { if (ret == AVERROR(EIO) || ret == AVERROR(ENODEV)) { LOG_ERROR("Device disconnected: %s", av_err2str(ret)); triggerReconnect(); // 重连逻辑 } av_packet_unref(&pkt); continue; }AVERROR(ENODEV)是设备消失的明确信号；AVERROR(EIO)则涵盖 USB 断开、权限丢失等广义 I/O 错误。重连时需重建整个AVFormatContext，包括重新枚举设备、协商参数，不能简单avformat_open_input()。
3.6 内存对齐：为什么av_image_fill_arrays()必须指定linesize
AVFrame的data[0]指向 YUV 数据起始地址，但linesize[0]表示每行字节数，它可能大于width * bytes_per_pixel（因内存对齐要求）。若手动计算data[0][y * width]访问像素，会越界。必须用av_image_fill_arrays()自动计算：
// 分配对齐内存 uint8_t *buffer; int buffer_size = av_image_get_buffer_size(AV_PIX_FMT_YUV420P, width, height, 32); buffer = (uint8_t*)av_malloc(buffer_size); // 填充 data[] 和 linesize[] 数组 av_image_fill_arrays(frame->data, frame->linesize, buffer, AV_PIX_FMT_YUV420P, width, height, 32);参数32表示 32 字节对齐（x86/x64 常用），FFmpeg 会据此调整linesize[0]（如 1920→1920，但 1921→1952）。忽略此步，H.264 编码器可能因内存越界崩溃。
3.7 日志与调试：如何让av_log()输出到文件而非终端
FFmpeg 默认日志输出到 stderr，干扰程序日志。需重定向：
// 自定义日志回调 void custom_log_callback(void *ptr, int level, const char *fmt, va_list vl) { static std::ofstream log_file("capture_debug.log", std::ios::app); if (level <= AV_LOG_INFO) { // 只记录 info 及以上 char line[1024]; vsnprintf(line, sizeof(line), fmt, vl); log_file << "[" << av_ts2timestr(av_gettime_relative(), &AV_TIME_BASE_Q) << "] " << line << std::endl; } } // 初始化时注册 av_log_set_callback(custom_log_callback);配合av_log_set_level(AV_LOG_INFO)，可精准捕获avformat_open_input()的详细协商过程（如 “v4l2: input format: yuv420p, framerate: 30/1”），这是排查“为什么开不了 1080p”的唯一途径。
4. 常见问题排查：5 个高频翻车点与根治方案
学生交作业最常卡在这 5 个点，每个都附带现象、根本原因和可立即执行的修复命令/代码。
4.1 现象：avformat_open_input()返回-22（Invalid argument）
原因：设备路径错误，或AVDictionary中设置了设备不支持的选项（如 v4l2 设备设audio_device_number）。
解决：
- 先用
ffprobe -f v4l2 -list_formats all -i /dev/video0确认设备路径和格式； - 检查
format_opts字典，删除所有音频相关 key（v4l2 只管视频）； - 代码中添加调试输出：
char options_str[512]; av_dict_get_string(format_opts, options_str, sizeof(options_str), '='); LOG_DEBUG("Opening device with options: %s", options_str);4.2 现象：视频能采集，音频一直av_read_frame()返回 0
原因：音频设备被其他进程占用（如 PulseAudio、Chrome），或 ALSA 设备名错误（hw:0,0vsplughw:0,0）。
解决：
- 终止干扰进程：
pkill pulseaudio && sudo alsa force-reload； - 用
arecord -D plughw:0,0 -f cd -d 1 test.wav测试设备； - 代码中尝试
plughw前缀：
av_dict_set(&format_opts, "audio_device_number", "plughw:0,0", 0);4.3 现象：音画严重不同步（音频快于视频 2 秒以上）
原因：未启用 Master Clock 同步，或音频线程未根据视频 PTS 动态 sleep。
解决：
- 确认
SyncCaptureEngine中audioCaptureLoop()包含target_audio_us计算逻辑； - 在音频线程中添加时间戳打印：
LOG_DEBUG("Audio PTS: %ld, Target: %ld, Diff: %ld us", audio_frame->pts, target_audio_us, target_audio_us - now_us);- 若
Diff持续为负，说明视频采集太慢，需降低目标帧率。
4.4 现象：编译时报undefined reference to 'avdevice_register_all'
原因：链接时未添加-lavdevice，或 FFmpeg 版本 >= 4.4 后该函数废弃。
解决：
- 检查
pkg-config --libs libavdevice输出是否包含-lavdevice； - 若版本 ≥ 4.4，删除
avdevice_register_all()调用，改为：
avformat_network_init(); // 必须调用 // 设备枚举函数仍可用，无需注册4.5 现象：RTMP 推流到 Nginx-rtmp 时，客户端播放卡顿
原因：未设置关键 muxer 选项，导致 GOP 过大或关键帧间隔过长。
解决：
在OutputMuxer::openOutput()中，为AVFormatContext添加选项：
av_dict_set(&ofmt_ctx_->oformat->priv_class, "gop_size", "30", 0); av_dict_set(&ofmt_ctx_->oformat->priv_class, "keyint_min", "30", 0); av_dict_set(&ofmt_ctx_->oformat->priv_class, "sc_threshold", "0", 0);并确保视频编码器AVCodecContext中：
video_codec_ctx_->gop_size = 30; video_codec_ctx_->keyint_min = 30;5. 方案验收与答辩技巧：用 3 份材料证明你真的懂
交毕设/课设不是交一堆.cpp文件，而是交付一份能让导师快速验证、提问时从容应对的完整证据链。我带过的项目，最终通过的关键是这三份材料，缺一不可。
5.1 验收清单：5 项必测功能与预期结果
| 测试项 | 操作步骤 | 预期结果 | 失败定位点 |
|---|---|---|---|
| 设备自动发现 | 运行./capture --list-devices | 输出至少 1 个视频设备（如v4l2:/dev/video0: HD Camera）和 1 个音频设备（如alsa:hw:0,0: Built-in Audio） | DeviceEnumerator枚举逻辑或 FFmpeg 初始化失败 |
| 参数协商验证 | 运行./capture -v /dev/video0 -a hw:0,0 -r 1280x720@30 | 控制台打印"Negotiated: 1280x720@30 (v4l2), 48000Hz/2ch (alsa)" | StreamConfigurator试探逻辑或设备驱动不支持 |
| 音画同步测试 | 录制 60 秒 MP4，用 VLC 播放并开启“工具 → 节目信息 → 编解码器” | 视频流Frame rate显示30.000，音频流Sample rate显示48000，无Dropped frames | SyncCaptureEnginePTS 校准或OutputMuxer时间基设置错误 |
| 异常恢复测试 | 录制中拔掉 USB 摄像头，等待 5 秒后插回 | 控制台打印"Device disconnected → Reconnecting..."，10 秒内恢复录制 | SyncCaptureEngine的重连回调未触发或avformat_open_input()重试逻辑缺失 |
| 资源泄漏检查 | 运行valgrind --leak-check=full ./capture -v /dev/video0 -a hw:0,0 -o test.mp4 -d 10 | 输出All heap blocks were freed -- no leaks are possible | AVFrame/AVPacket未av_frame_free()或av_packet_unref() |
提示：答辩前务必用
valgrind跑一遍，导师极大概率会问“内存管理怎么做的”。若出现definitely lost，直接指向RingBuffer::pop()中shared_ptr.reset()是否遗漏。
5.2 答辩话术：3 个高频问题与满分回答模板
Q1：为什么不用 OpenCV 的cv::VideoCapture？
“OpenCV 的 VideoCapture 封装了底层设备，无法获取原始 AVFrame 和 PTS，也无法精细控制音频采集。本方案用 FFmpeg API 直接操作，是为了满足课程设计‘掌握音视频同步原理’的要求。比如，我们实现了基于视频时钟的音频 PTS 校准（指向
SyncCaptureEngine.cpp第 215 行），这在 OpenCV 中无法做到。”
Q2：如果摄像头支持 H.264 硬编码，怎么接入？
“只需修改
EncoderFactory::createVideoEncoder()，将codec_id从AV_CODEC_ID_H264改为AV_CODEC_ID_H264_OMX（树莓派）或AV_CODEC_ID_H264_NVENC（NVIDIA），并添加硬件专用选项：av_dict_set(&opts, "preset", "llhp", 0)。我们预留了HardwareEncoder抽象类，所有硬件编码器都继承它，确保上层采集逻辑完全不变。”
Q3：如何证明你实现了‘实时性’？
“我们在
SyncCaptureEngine中埋点了三处时间戳：采集开始（av_gettime_relative()）、帧处理完成、muxer 写入完成。运行时开启--verbose，会输出每帧的端到端延迟（如Frame #123: capture=3.2ms, encode=12.7ms, mux=0.8ms, total=16.7ms）。实测在树莓派 4B 上，1280x720@30 场景下平均 total < 25ms，满足实时定义（< 40ms）。”
5.3 文档与代码组织：让导师 5 分钟看懂你的工作量
学生常把所有代码塞进一个main.cpp，导师翻半天找不到重点。我要求团队严格按以下结构组织：
capture/ ├── CMakeLists.txt # 含 pkg_check_modules 检查 FFmpeg 版本 ├── src/ │ ├── core/ # 核心模块（DeviceEnumerator 等） │ ├── engine/ # SyncCaptureEngine 实现 │ ├── muxer/ # OutputMuxer 及编码器工厂 │ └── main.cpp # 仅含命令行解析和 CaptureController 启动 ├── docs/ │ ├── design.md # 本方案全文档（含架构图、模块接口表） │ ├── build_guide.md # Ubuntu/树莓派/Windows 编译步骤（含 apt install 命令） │ └── test_report.pdf # 5 项验收测试的截图与日志（答辩必带） └── assets/ └── test_pattern.yuv # 用于无摄像头时的离线测试其中design.md必须包含一张手绘风格架构图（用 Mermaid 语法，但导出为 PNG 插入）：
graph LR A[DeviceEnumerator] -->|设备列表| B[StreamConfigurator] B -->|协商参数| C[SyncCaptureEngine] C -->|AVFrame| D[RingBuffer] D -->|多线程安全| E[OutputMuxer] E -->|MP4/RTMP| F[存储/网络]从那以后我每次带新项目，都强制要求成员在
docs/design.md里用 Mermaid 画出模块交互图，并标注每个箭头的数据类型（如DeviceList、AVRational）。这逼着他们想清楚数据流向，而不是堆砌代码。希望帮到你。
本文还有配套的精品资源，点击获取
