// the find
lucemia/typed-ffmpeg
Type-safe FFmpeg bindings for Python & TypeScript — filters, typing, and docs
A typed builder API for constructing FFmpeg filter graphs instead of hand-assembling CLI strings, with a mature Python package and an experimental TypeScript port. It's aimed at people doing more than trivial transcodes — chained filters, overlays, concat, trim — who are tired of ffmpeg-python's stale/incomplete typing.
Splits bindings per FFmpeg major version (v5 through v9) so the typing and filter metadata actually match the binary you're running, instead of one generic wrapper that silently drifts from whatever ffmpeg is installed. The Python core has zero runtime dependencies, built entirely on stdlib. It supports round-tripping: filter graphs serialize to JSON and, via the `[parse]` extra, an existing ffmpeg command line can be parsed back into the typed Python builder — useful for migrating scripts that currently shell out raw commands. CI is split into separate workflows for codegen, monorepo lint/test, playground, and TS, which suggests the version-sync machinery is actually exercised rather than assumed to work.
TypeScript is flagged experimental, so half the audience implied by the repo's own topics isn't getting a stable API yet. The per-FFmpeg-version package split pushes a burden onto the user — pick the wrong package (`typed-ffmpeg-v6` against an FFmpeg 8 binary) and you get a typed API lying about what the installed binary actually supports, with no runtime check visible in the README. It's still a filter-graph DSL, not an abstraction over FFmpeg's complexity — you need to understand streams, pads, and filter chaining before the autocomplete helps you. Maintaining five parallel sets of filter definitions as FFmpeg adds/changes filters each release is an ongoing correctness burden, and nothing in the README says how quickly a new FFmpeg release gets picked up.