ffmprovisr is a cookbook of FFmpeg commands for moving image archivists

The objective is understanding, not just copying

The stated project objective is to facilitate better understanding of FFmpeg through collaborative sharing of useful scripts and detailed flag-level description of how each script works, so archivists can copy-paste and produce their own scripts, but also understand how and why they work. That second clause is the whole point, and it is unusual in a command cookbook. Most FFmpeg command collections are a wall of one-liners with no reasoning, which works until the input is not quite what the author assumed. Here the expectation is that a reader can adapt a recipe because the reasoning is in the same place as the command. The context matters too. The topics are digipres and ffmpeg, the project is hosted by AMIA Open Source, and the sister projects listed include The Cable Bible, a guide to cables and connectors used for audiovisual tech, which tells you the audience: people who handle physical and digital media as an archivist rather than as a video editor. The domain is preservation, where the output has to survive a decade in a repository, and the commands are chosen for that.

Everything is one index.html on a gh-pages branch

The repository layout is unusually simple, and it explains how the site is built. The top level holds index.html, readme.md, code_of_conduct.md, and then css/, img/, js/ and scripts/ directories, alongside.github/. The default branch is gh-pages, and the README says the code is found there and that it is the default primary branch. So the site is a static page that GitHub Pages serves directly, with no build step, no bundler and no framework. The readme is right there in the repository, alongside the site's code. That simplicity is a feature for a documentation project, because a contributor clones the repository, creates a branch and edits one file. It also means the site has no versioning discipline of its own beyond git history, and no automated test that a command still works on a current FFmpeg build, so the recipes are trusted on the strength of the review that went into them rather than on a CI run.

Contributing a recipe means editing one file

The contribution path is direct. You can edit the codebase yourself, or just supply the information and ask for it to be added to the site. To do it directly, you clone the repository, create a branch with the git checkout -b command and add or modify a new block in index.html, then submit a pull request and the maintainers review and integrate the code.

There is a commented-out sample block at the bottom of index.html that serves as a guideline for your command, which is the only template the project provides. The review guidelines are specific and sensible for a collection like this. Each sub-change should be committed separately, so a new recipe and a correction to an existing one are two commits rather than one, and a change with a large scope or covering multiple areas should be split into separate pull requests. A recipe should ideally do just one thing or solve one problem, to keep things user-friendly and avoid unintended side effects, and explanations and examples should be as generic as possible so a user can alter the command for their own use case, which may involve the use of variable names.

Recipes that need a GIF, a standard, or a very long filter graph

The recipe-specific guidelines anticipate the three situations where a single command stops being self-explanatory, and each one has a documented answer. When a recipe would benefit from showing its output, the project suggests including a GIF, with the example given being a graphical output showing decibel levels of an input file. When a recipe refers to a specific standard or vocabulary, the guidance is to link to it so a user can scale the recipe to their own case, with the example being generating a Broadcast WAV. And the hard case is called out directly, because recipes involving the filter_complex option can be some of the most verbose and difficult to understand, so breaking those down as much as possible into their relevant sections is the ideal. The site examples referenced include fading video and audio streams, playing a graphical output showing decibel levels, rewrapping a file, and generating two access MP3s from input. Each of those anchor points is a URL fragment on the site, which is a small design detail that makes the project usable from a search engine.

Three ways to contribute if you cannot write HTML

The contribution guidance is unusually accommodating, which is probably why the project has accumulated the contributor list it has. There are two explicit routes beyond editing the code. If you are having trouble with coding it yourself or with GitHub, the project asks you to submit an issue with the kind of command you would like to see added to the site, so a command can be requested without writing the markup. And if you want to help but do not have a new script to add, the project names three other ways in: testing out the scripts available, refining or clarifying the documentation, and creating an issue for anything that sounds confusing and requires clarification. That last option is the one most projects would forget to offer, and it is the one that produces the most useful issues in a collection like this, because a reader who cannot tell whether a command is correct has information the maintainers do not.

Who maintains it and how the project started

Four maintainers are named, Ashley Blewer, Katherine Frances Nagels, Kieran O'Leary and Andrew Weaver, and the contributor list is long, gathered with the octohatrack tool. The project came out of the AVHack Team, associated with the Association of Moving Image Archivists and Digital Library Federation Hack Day 2015, and the team roster includes several of the maintainers plus Eddy Colloton, Rebecca Dillmeier, Jonathan Farbowitz, Rebecca Fraimow, Samuel Gutterman, Kelly Haydon, Reto Kromer, Nicole Martin, Catriona Schlosser and Ben Turkus. A collection like this is a community artefact in a real sense, since the commands come from people who had to solve the same archival problem and wrote down what worked. The last push to the repository was on 2026-05-04, and the release tags are dated by content, with the most recent listed as v2026-03-09 after v2025-09-30 and v2025-04-16, which is the pattern of a site that is revised on a schedule tied to its own content rather than to a software release cycle.

Where ffmprovisr is the wrong place to look

Three limits. The first is that this is a cookbook, not a tool. There is no wrapper, no configuration file and no library, and nothing here will run a command for you or check that it worked. If your requirement is reproducible batch processing with logging and error handling, you will be writing that yourself and using these pages as reference documentation, which is a perfectly good use but a different one. The second is that the recipes are archival in flavour rather than general. The examples are about preservation, broadcast standards, decibel visualisation and access copies, and a reader looking for streaming, social video delivery or thumbnail extraction will find the coverage uneven, because the collection is shaped by what archivists needed. The third is the absence of an automated check that a command still behaves as documented. FFmpeg's flag set changes between releases, and a recipe verified in 2021 may silently produce different output on a current build, and nothing in the repository will tell you, which is why the review and the issue tracker carry the verification load instead.

Editorial conclusion

Adopt ffmprovisr as a reference if you work with moving image files and want proven FFmpeg invocations with an explanation of the flags, since the recipes are written for archival work rather than for streaming or social video. Skip it if you need a tool that runs FFmpeg for you, because this project has no API and no binary, it is a web page. Before you copy a recipe, read the flag explanation under it, and if you find the site lacking a command you need, note that contributions are made by editing index.html and opening a pull request, with each recipe expected to do one thing and stay as generic as possible.

Frequently asked questions

Official sources

1. amiaopensource/ffmprovisr on GitHub
2. Issues
3. Project website
4. README
5. Releases