0.05

Author: sudoevolve

docs/ffmpeg/00-目录.md

@@ -0,0 +1,22 @@
+# FFmpeg 文档目录（命令行 + vcpkg + libav 入门）
+
+FFmpeg 的使用大致分两类：
+
+- **把它当工具**：用 `ffmpeg/ffprobe` 命令处理音视频（最常见，也最省心）
+- **把它当库**：用 `libavformat/libavcodec/libswscale/libswresample` 在 C/C++ 里做解码/编码/转封装
+
+本目录按“先能用 → 再工程化 → 再深入”的顺序组织，默认面向 Windows + Visual Studio + vcpkg。
+
+## 学习路线
+
+- [01-安装与工程：vcpkg + CMake + VS（命令行与链接）](01-安装与工程-vcpkg-CMake-VS.md)
+- [02-命令行速查：转码、抽帧、拼接、音视频同步](02-命令行速查-转码-抽帧-拼接-同步.md)
+- [03-libav 入门：从打开文件到拿到帧（最小解码链路）](03-libav入门-打开文件-解码-拿到帧.md)
+- [04-概念总览：容器、编码、流、时间基、像素格式](04-概念总览-容器编码流时间基像素格式.md)
+- [05-编码参数与质量：CRF、码率、预设、GOP、像素格式](05-编码参数与质量-CRF码率预设GOP像素格式.md)
+- [06-滤镜与常见场景：filtergraph、缩放裁剪、叠加、水印、字幕](06-滤镜与常见场景-filtergraph-缩放裁剪叠加字幕.md)
+- [07-ffprobe 与排错：流选择（map）、同步、常见报错](07-ffprobe与排错-流选择map-同步-常见报错.md)
+
+## 01 从这里开始
+
+- 下一篇：见 [01-安装与工程：vcpkg + CMake + VS（命令行与链接）](01-安装与工程-vcpkg-CMake-VS.md)

docs/ffmpeg/01-安装与工程-vcpkg-CMake-VS.md

@@ -0,0 +1,103 @@
+# 01-安装与工程：vcpkg + CMake + VS（命令行与链接）
+
+目录页：见 [FFmpeg 文档目录](00-目录.md)
+
+## 目标
+
+- 在 Windows + VS 环境把 FFmpeg 安装到工程里（vcpkg）
+- 能稳定调用 `ffmpeg/ffprobe` 做命令行处理
+- 能在 CMake 工程里链接 FFmpeg 的库（libav*）
+
+---
+
+## 1. 用 vcpkg 安装 FFmpeg（推荐）
+
+FFmpeg 在 vcpkg 里的 port 名称就是 `ffmpeg`：
+
+```
+vcpkg install ffmpeg
+```
+
+FFmpeg 的能力非常多，vcpkg 里也提供了一堆 feature。初学阶段你可以先接受一个工程口径：
+
+- 先装默认的 `ffmpeg`，把“命令行能用 + 工程能链接 + 运行时 DLL 能找到”跑通
+- 之后再按需求加 feature（例如字幕、字体渲染、特定编码器、硬件加速等）
+
+如果你已经在 OpenGL 教程里用过 VS + CMake + vcpkg toolchain，这里保持同一套口径即可：
+
+- 固定 triplet（例如 `x64-windows`）
+- CMake 配置时固定 vcpkg toolchain
+
+参考（port 说明与 feature 列表）：https://vcpkg.link/ports/ffmpeg
+
+---
+
+## 2. 命令行可用性：ffmpeg / ffprobe 在哪里
+
+你可能会遇到“库安装了，但找不到 `ffmpeg.exe`”的情况。原因通常是：
+
+- vcpkg 安装的是库本体；命令行工具是否安装/是否在 PATH 上，取决于 port feature 与你的使用方式
+- VS 启动调试时 PATH 与终端 PATH 不是一回事
+
+建议工程化口径是：
+
+- **开发期**：在你自己的工程里固定一个 `tools/` 或 `third_party/tools/`，把 `ffmpeg.exe/ffprobe.exe` 作为外部工具管理
+- **发布期**：明确把运行时依赖的 DLL 与工具一起打包（避免“只在我电脑能跑”）
+
+如果你是通过 vcpkg 获取命令行工具，通常可以在 vcpkg 的 `installed/<triplet>/tools/ffmpeg/` 一类目录下找到它们（路径以你的 vcpkg 布局为准）。
+
+---
+
+## 3. CMake 链接 FFmpeg（libav*）
+
+FFmpeg 的库通常由这些组件组成：
+
+- `libavformat`：容器/封装（读写 mp4/mkv/flv…）
+- `libavcodec`：编解码（H.264/H.265/AAC…）
+- `libavutil`：通用工具（时间基、字典、缓冲区、像素格式…）
+- `libswscale`：图像缩放与像素格式转换
+- `libswresample`：音频重采样与格式转换
+
+vcpkg 的 `ffmpeg` port 提供 CMake 集成，典型用法是：
+
+```cmake
+find_package(FFMPEG REQUIRED)
+target_include_directories(app PRIVATE ${FFMPEG_INCLUDE_DIRS})
+target_link_directories(app PRIVATE ${FFMPEG_LIBRARY_DIRS})
+target_link_libraries(app PRIVATE ${FFMPEG_LIBRARIES})
+```
+
+如果你想让“工程可移植 + 配置更稳定”，建议把依赖放进 vcpkg manifest（`vcpkg.json`）并用 CMakePresets/VS 的 CMake 集成固定 toolchain 与 triplet。
+
+### 3.1 链接不等于能跑：运行时 DLL 要能被找到
+
+Windows 下最常见的问题是：
+
+- 编译链接通过，但运行时报 “找不到 xxx.dll”
+
+第一反应检查：
+
+- DLL 是否在可执行文件同目录
+- 或者是否在 PATH 可搜索目录中
+- Debug/Release、x86/x64 是否混用了不同目录的 DLL
+
+更推荐的工程习惯是：先把“能编译 + 能运行 + 能定位 DLL”跑通，再进入具体的解码/编码流程。因为 FFmpeg 真正难的部分往往不是 API，而是工程环境与数据路径。
+
+---
+
+## 4. License 的工程现实（你至少要知道的）
+
+FFmpeg 里有不同 license 组合（LGPL/GPL/nonfree）对应不同功能组合与可分发性。初学阶段不需要深究条款，但需要知道：
+
+- 你用的 FFmpeg build 是“带了哪些编码器/库”决定了你能不能用 `libx264`、`libx265` 等
+- 当你要把程序发布给别人时，license 选择会影响你能否合法分发对应二进制
+
+工程口径：不确定就先用“功能更基础、可分发性更清晰”的组合，等你真的需要某个编码器/滤镜再补齐。
+
+---
+
+## 常见坑
+
+- **Debug/Release 混用依赖**：同一个工程里用到不同 triplet/构建类型的库，会出现运行时找 DLL 或链接符号对不上的问题
+- **只链接了 avcodec**：很多符号实际在 avutil/avformat 里，缺一个就会一串 unresolved external
+- **把时间戳当成秒**：libav 的时间基是 `AVRational`，很多字段是“以 time_base 为单位”的整数

docs/ffmpeg/02-命令行速查-转码-抽帧-拼接-同步.md

@@ -0,0 +1,224 @@
+# 02-命令行速查：转码、抽帧、拼接、音视频同步
+
+目录页：见 [FFmpeg 文档目录](00-目录.md)
+
+这章只追求“能直接抄走用”。建议先用 `ffprobe` 看清楚容器/编码/时长/帧率/音轨/字幕，再决定要不要转码。
+
+如果你发现自己“会抄但不懂”，先把这两章看一遍：
+
+- 概念：见 [04-概念总览：容器、编码、流、时间基、像素格式](04-概念总览-容器编码流时间基像素格式.md)
+- 参数：见 [05-编码参数与质量：CRF、码率、预设、GOP、像素格式](05-编码参数与质量-CRF码率预设GOP像素格式.md)
+
+---
+
+## 1. 先看信息：ffprobe
+
+看流信息（视频/音频分别是什么编码）：
+
+```bash
+ffprobe -hide_banner -i input.mp4
+```
+
+只看时长与关键元信息（输出更干净）：
+
+```bash
+ffprobe -v error -show_entries format=duration:format_tags=title -of default=nk=1:nw=1 input.mp4
+```
+
+---
+
+## 2. 转封装（不转码，最快）
+
+只换容器（不重新编码）：
+
+```bash
+ffmpeg -i input.mp4 -c copy output.mkv
+```
+
+只要视频，不要音频/字幕：
+
+```bash
+ffmpeg -i input.mkv -map 0:v:0 -c copy out.mp4
+```
+
+只要视频 + 第一条音频（多音轨文件建议显式 map）：
+
+```bash
+ffmpeg -i input.mkv -map 0:v:0 -map 0:a:0 -c copy out.mkv
+```
+
+---
+
+## 3. 常见转码（通用模板）
+
+转 H.264 + AAC（最通用的组合之一）：
+
+```bash
+ffmpeg -i input.mov -c:v libx264 -pix_fmt yuv420p -c:a aac -b:a 192k output.mp4
+```
+
+缩放到 720p（保持宽高比）：
+
+```bash
+ffmpeg -i input.mp4 -vf "scale=-2:720" -c:v libx264 -c:a copy output_720p.mp4
+```
+
+---
+
+## 4. 截取/裁剪（尽量不踩同步坑）
+
+从 10s 开始取 5s（最稳的方式：重编码一遍）：
+
+```bash
+ffmpeg -ss 10 -t 5 -i input.mp4 -c:v libx264 -c:a aac out.mp4
+```
+
+如果你只想“无损裁剪”（`-c copy`），需要接受：不一定从精确帧切、也可能音画有偏差：
+
+```bash
+ffmpeg -ss 10 -t 5 -i input.mp4 -c copy out_copy.mp4
+```
+
+---
+
+## 5. 抽帧/导出图片序列
+
+按帧率抽（每秒 2 帧）：
+
+```bash
+ffmpeg -i input.mp4 -vf "fps=2" frames/%06d.png
+```
+
+按时间戳抽一张（第 3.5 秒）：
+
+```bash
+ffmpeg -ss 3.5 -i input.mp4 -frames:v 1 out.png
+```
+
+---
+
+## 6. 图片序列 ↔ 视频
+
+图片序列转视频（30fps）：
+
+```bash
+ffmpeg -framerate 30 -i frames/%06d.png -c:v libx264 -pix_fmt yuv420p out.mp4
+```
+
+视频转图片序列：
+
+```bash
+ffmpeg -i input.mp4 frames/%06d.png
+```
+
+---
+
+## 7. 导出音频 / 改格式
+
+导出 mp3：
+
+```bash
+ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 192k out.mp3
+```
+
+导出 wav（PCM，便于做分析/波形处理）：
+
+```bash
+ffmpeg -i input.mp4 -vn -c:a pcm_s16le -ar 48000 -ac 2 out.wav
+```
+
+---
+
+## 8. 字幕：封装与烧录
+
+把 srt 作为软字幕封装进 mkv：
+
+```bash
+ffmpeg -i input.mp4 -i sub.srt -c:v copy -c:a copy -c:s srt out.mkv
+```
+
+把字幕烧进画面（硬字幕）：
+
+```bash
+ffmpeg -i input.mp4 -vf "subtitles=sub.srt" -c:v libx264 -crf 20 -c:a copy out_hardsub.mp4
+```
+
+---
+
+## 9. 旋转/翻转
+
+旋转 90°：
+
+```bash
+ffmpeg -i input.mp4 -vf "transpose=1" -c:v libx264 -crf 20 -c:a copy out_rot.mp4
+```
+
+水平翻转：
+
+```bash
+ffmpeg -i input.mp4 -vf "hflip" -c:v libx264 -crf 20 -c:a copy out_hflip.mp4
+```
+
+---
+
+## 10. 水印/叠加
+
+叠加 logo 到右上角：
+
+```bash
+ffmpeg -i input.mp4 -i logo.png -filter_complex "overlay=W-w-20:20" -c:v libx264 -crf 20 -c:a copy out_logo.mp4
+```
+
+---
+
+## 11. 常见质量/体积控制
+
+CRF + preset（离线压缩常用）：
+
+```bash
+ffmpeg -i input.mp4 -c:v libx264 -crf 20 -preset slow -pix_fmt yuv420p -c:a aac -b:a 160k out.mp4
+```
+
+强行卡码率（带宽受限/推流常用）：
+
+```bash
+ffmpeg -i input.mp4 -c:v libx264 -b:v 2500k -maxrate 2500k -bufsize 5000k -g 60 -pix_fmt yuv420p -c:a aac -b:a 160k out.mp4
+```
+
+---
+
+## 12. 拼接（concat）
+
+同编码参数的 mp4 拼接（推荐先转封装到 TS 再 concat，兼容性更好）：
+
+```bash
+ffmpeg -i a.mp4 -c copy -bsf:v h264_mp4toannexb -f mpegts a.ts
+ffmpeg -i b.mp4 -c copy -bsf:v h264_mp4toannexb -f mpegts b.ts
+ffmpeg -i "concat:a.ts|b.ts" -c copy -bsf:a aac_adtstoasc out.mp4
+```
+
+如果你能保证输入文件编码参数完全一致，也可以用 concat demuxer（更标准）：
+
+准备一个 `list.txt`：
+
+```
+file 'a.mp4'
+file 'b.mp4'
+```
+
+然后：
+
+```bash
+ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4
+```
+
+---
+
+## 13. 常见同步问题的第一反应
+
+- 先用 `ffprobe` 看：是否 VFR（可变帧率）、音频采样率是否一致、是否有多音轨
+- 只要你不是强制无损（`-c copy`），多数同步问题都能通过“重编码 + 统一参数”解决
+
+如果你经常遇到“选错音轨/字幕/莫名其妙不同步/报错看不懂”，直接看：
+
+- [07-ffprobe 与排错：流选择（map）、同步、常见报错](07-ffprobe与排错-流选择map-同步-常见报错.md)