ffmpeg-doc-lookup

# FFmpeg Documentation Lookup ## Why local docs The HTML under the FFmpeg install directory is generated for the installed build. Options get renamed, deprecated, or moved between releases, so memory is often a version or two stale. Local docs are also far faster and more precise than web search for "does this option exist / what are its values". Requirements: FFmpeg on `PATH` with its `doc/` HTML pages, Python 3.9+, and lxml (`python -m pip install lxml`). Set `FFMPEG_DOC_DIR` if the docs live elsewhere — Debian/Ubuntu keep them in a separate package (`ffmpeg-doc`). ## 1. Find the doc directory Bash: ```bash DOC="$(dirname "$(dirname "$(command -v ffmpeg)")")/doc"; ls "$DOC" ``` PowerShell: ```powershell $doc = Join-Path (Split-Path (Split-Path (Get-Command ffmpeg).Source)) 'doc'; Get-ChildItem $doc ``` List it before assuming a filename. If there are no HTML files, skip to Fallback. ## 2. Pick the file | Question | File | |---|---| | General options, usage overview | ffmpeg.html | | Syntax, quoting/escaping, time durations, sizes, colors, expressions | ffmpeg-utils.html | | Encoder/decoder parameters | ffmpeg-codecs.html | | Filter syntax and filter options | ffmpeg-filters.html | | Container formats | ffmpeg-formats.html | | Protocols | ffmpeg-protocols.html | | Device inputs | ffmpeg-devices.html | | Bitstream filters (`-bsf`) | ffmpeg-bitstream-filters.html | | Scaling (`sws_flags`) / resampling | ffmpeg-scaler.html / ffmpeg-resampler.html | | ffprobe | ffprobe.html | | ffplay | ffplay.html | | Supported external libs, build features | general.html | `ffmpeg-all.html` is every page concatenated (~69k lines, 3 MB). Use it only when one term must be searched across categories — never read it end to end. ## 3. Look it up Use the bundled helper. It resolves the doc directory, matches anchor ids, headings, and option names (`<dt>` entries), strips HTML, and prints one section with a `file:line` citation: ```bash python scripts/ffdoc.py find scale --in filters --lines 60 python scripts/ffdoc.py find h264_mp4toannexb --in bsf python scripts/ffdoc.py find crf --in codecs python scripts/ffdoc.py toc filters --pattern scale python scripts/ffdoc.py grep yuv420p10 ``` `scripts/ffdoc.py` is relative to this skill's directory (agents load skills into their own directory, e.g. `~/.claude/skills/ffmpeg-doc-lookup/`), so resolve it from SKILL.md rather than from the current working directory. - `--in` accepts aliases: `filters`, `codecs`, `utils`, `main`, `formats`, `protocols`, `devices`, `bsf`, `scaler`, `resampler`, `probe`, `play`, `all`, or any doc filename. Without it, the common docs are searched. - Output is capped at 80 lines by default (`--lines 0` for all). When several sections match, candidates are listed and `--nth N` picks one. If the helper is unavailable (no Python or lxml), search the HTML directly: anchors look like `<a class="anchor" id="scale"></a>`, filter subsections like `<h4 class="subsection">...`. Grep with `-n -C 2`, then Read a 50–150 line window. Never read a whole file — they are 200 KB–3 MB and Read truncates them. ## 4. Cross-check against the running binary ```bash ffmpeg -hide_banner -h filter=scale ffmpeg -hide_banner -h encoder=libx264 ffmpeg -hide_banner -h muxer=mp4 ffmpeg -hide_banner -h full ffmpeg -hide_banner -filters ffmpeg -hide_banner -encoders ffmpeg -hide_banner -formats ffmpeg -hide_banner -bsfs ffmpeg -hide_banner -pix_fmts ffmpeg -hide_banner -hwaccels ``` `-hide_banner` matters: without it every help call dumps the build configuration first. `-h <type>=NAME` confirms an option exists in *this* build and lists its accepted values; the docs explain semantics. If they disagree, trust the binary. ## 5. Answer - Never invent option names; verify each one in the docs or in `-h` output. - State which file/section the answer came from so the user can re-check it. - On Windows, quote paths with spaces; filtergraph escaping differs between Bash and PowerShell — verify with a short `-f null -` test run when in doubt. ## Fallback 1. `ffmpeg -h full`, `-filters`, `-encoders`, `-pix_fmts`, and the other list commands above. 2. Web search: StackOverflow / Super User / Video Stack Exchange, GitHub Issues, r/ffmpeg, technical blogs. Prefer concrete solutions; note that older answers may describe options that were removed or renamed in the installed version.