# ffmpeg-doc-lookup
An agent skill that answers FFmpeg and FFprobe questions from the HTML
documentation shipped with the installed build, instead of from memory or the web.
Options get renamed, deprecated, or moved between releases, so recalled details
are often stale. The docs sitting next to the `ffmpeg` binary are generated for
exactly the build being run — version-correct, local, and much faster to search
than the web.
## What it does
- Finds the doc directory next to the `ffmpeg` binary (or honours `FFMPEG_DOC_DIR`).
- Routes the question to the right page: filters, codecs, formats, protocols,
devices, bitstream filters, scaler, resampler, ffprobe, ffplay.
- Uses `scripts/ffdoc.py` to locate the section for a filter, an encoder option,
or a bitstream filter, and prints it as plain text with a `file:line` citation.
- Cross-checks option names against `ffmpeg -hide_banner -h ...`, which is the
ground truth for what the installed build actually accepts.
## Requirements
- FFmpeg/FFprobe on `PATH`, with the HTML docs at `<prefix>/doc/*.html`. Most
Windows and static Linux builds bundle them; on Debian/Ubuntu they may be a
separate package (`ffmpeg-doc`).
- Python 3.9+ and [lxml](https://pypi.org/project/lxml/).
```bash
python -m pip install lxml
```
Point `FFMPEG_DOC_DIR` at another directory if the docs are not beside the binary.
## Install
```bash
npx skills add AntaresFeng/ffmpeg-doc-lookup
```
Or copy this repository into `~/.claude/skills/ffmpeg-doc-lookup/`.
## Usage
The agent runs these on its own; they work by hand too:
```bash
python scripts/ffdoc.py path
python scripts/ffdoc.py find scale --in filters --lines 60
python scripts/ffdoc.py find crf --in codecs
python scripts/ffdoc.py find h264_mp4toannexb --in bsf
python scripts/ffdoc.py toc filters --pattern scale
python scripts/ffdoc.py grep yuv420p10
```
```text
$ python scripts/ffdoc.py find crf --in codecs --lines 6
# ffmpeg-codecs.html:4450 option: crf
Set the quality/size tradeoff for constant-quality (no bitrate target)
and constrained-quality (with maximum bitrate target) modes. Valid
range is 0 to 63, higher numbers indicating lower quality and smaller
output size. Only used if set; by default only the bitrate target is
used.
# option candidates (use --nth N):
# *1. ffmpeg-codecs.html:4450 crf
# 2. ffmpeg-codecs.html:4763 crf
# 3. ffmpeg-codecs.html:6083 crf
```
`--in` accepts short aliases (`filters`, `codecs`, `utils`, `main`, `formats`,
`protocols`, `devices`, `bsf`, `scaler`, `resampler`, `probe`, `play`, `all`) or
a page filename. Output is capped at 80 lines by default (`--lines 0` for all);
when several sections match, candidates are listed and `--nth N` picks one.
## Layout
```text
SKILL.md instructions the agent reads
scripts/ffdoc.py the lookup helper
```
## License
MIT