# FFMS2 hides the FFmpeg API behind a plain C interface

> FFMS2 is a C++ wrapper library around FFmpeg with a pure C public API, built so that frame accurate decoding is available without wrestling with the FFmpeg interface directly. It is also the engine behind the Avisynth and VapourSynth source plugins, and its licence depends on how FFmpeg was compiled.

**FFMS/ffms2** — An FFmpeg based source library and Avisynth/VapourSynth plugin for easy frame accurate access

- Repository: https://github.com/FFMS/ffms2
- Stars: 662 · Forks: 111
- Language: C++
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ffms-ffms2

## FFMS2 exists to hide FFmpeg's awkward API

The value proposition is stated plainly in the project description: FFMS2 gives you an easy, convenient way to say open and decompress this media file for me, I don't care how you do it, and get frame and sample accurate access, usually, without having to bother with the sometimes less than straightforward and less than perfectly documented FFmpeg API.

The target reader is a developer building a media tool who needs random access into a file rather than a sequential decode. Frame accurate indexing is the hard part. A tool that seeks to a given frame, or that must read a specific audio sample, has to know where the frames sit, and doing that on your own means dealing with keyframe tables, timestamp handling and codec differences directly against FFmpeg.

FFMS2 does that indexing work once and exposes it. The word usually in the description is doing real work there, since the project does not claim perfect accuracy in all cases, and a tool that must guarantee sample exactness for mastering still has to prove that for its own formats. The plugin for Avisynth and VapourSynth is the visible end of this library, but the library itself is the more interesting part for anyone building something new.

## C++ inside, plain C at the boundary

The library is written in C++, but the public API is pure C. The stated consequence is direct: if you can link to a C library, you can use FFMS2. That is an unusual and useful constraint in a media world where many of the surrounding tools are C++ or Rust, because it removes the need for a C++ toolchain and any ABI coupling to a compiler's standard library.

The repository layout backs up the cross-platform claim in a conventional way. There is an autotools build with configure.ac, Makefile.am, m4/ and autogen.sh, plus a build-msvc/ directory for the Microsoft compiler route, an include/ directory for the public headers, src/ for the implementation, test/ for the test suite, doc/ for documentation, and etc/ for packaging files. The presence of ffms2.pc.in shows that a pkg-config file is generated during the build, so downstream builds can locate the library through pkg-config rather than hard coded paths.

There is also a version.sh script and a .gitmodules file, which tells you the build pulls in at least one dependency as a submodule rather than vendoring it in the tree.

## The Avisynth and VapourSynth plugins are how most users arrive

For the end user, the description calls the Avisynth and VapourSynth source plugin the most visible use of FFMS, and it is part of the same project rather than a separate codebase. Both plugins open media files through the FFMS library, which means the plugin inherits the library's decoding coverage and its indexing behaviour.

This is the practical installation path for people who only want to use FFMS rather than program against it. The project documentation for that path is the Avisynth user guide at doc/ffms2-avisynth.md, and the library side is documented separately in doc/ffms2-api.md with a changelog at doc/ffms2-changelog.md.

The distinction between library and plugin matters for maintenance. A bug in the plugin, a new Avisynth colourspace, or a Windows build problem touches only the front end. A bug in indexing or decoding touches everything, including the plugins. Reading the changelog tells you which layer a given change belongs to, and it is the first file to consult before upgrading a build that a project depends on.

## Five source filter properties the plugin claims for itself

The description lists properties the Avisynth plugin has that other Avisynth source filters lack. It is the only source filter with support for Unicode filenames that are not representable in the system codepage. It is the only source filter with proper variable framerate support. It is the only general-purpose source filter that works reliably when Avisynth runs under Wine, and the only general-purpose source filter that does not rely on external decoders.

The fifth claim is hedged differently from the others. The plugin is described as probably the only source filter supporting mid-stream video resolution switches, which is the sort of claim that is hard to prove exhaustively.

Three of these are worth unpacking. Variable framerate support matters for anything that has to present timestamps correctly, since a source filter that assumes constant frame duration will drift on such footage. Unicode filenames outside the system codepage matter on Windows, where legacy source filters tend to fail on non Latin paths. And not relying on external decoders removes a whole class of setup failure, since there is no separate codec binary to install, although the plugin still depends on the FFmpeg build compiled into FFMS2 itself.

## Variant suffixes that decide what you download

The project anticipates confusion here and explains the variants directly. A package with no suffix is the standard 32-bit version, and the guidance for anyone unsure is blunt: if you don't know what you want, you want this. The -x64 build is the 64-bit version, mostly for use with 64-bit Avisynth.

The -avs-cplugin variant is the Avisynth plugin written in C, whose stated primary purpose is to get access to the new colourspaces available in Avisynth 2.6. The SDK package is a software developer's kit for people who want to develop Windows applications that use FFMS2 with Microsoft Visual Studio 2008 or later.

Packages marked with an r followed by a number are testing builds made between releases. The description says to download them if you need a bleeding edge feature or want to test the upcoming version, and warns that they may be less stable than the official release builds. That warning is the deciding factor for most installations: an r build in a production pipeline trades the newest fix for a stability risk that the release notes will not cover.

## The licence you ship depends on your FFmpeg build

This is the part that surprises people, and it is stated clearly. The source is available under the MIT licence, but the licence of the binaries depends on how FFmpeg was compiled. There are optional components that require a GPL FFmpeg, and if those are compiled in, FFMS2 itself becomes covered by the GPL as well. The official Windows builds are GPLv3 for this reason.

The practical consequence is that you cannot answer the licence question by looking at FFMS2 alone. You have to know which optional components were compiled in and which FFmpeg build sits underneath. A team shipping a desktop application that bundles FFMS2 has to track the configuration of the FFmpeg dependency, and a change in that dependency changes the obligations of the shipped binary.

The repository listing classifies the licence as Other, described as a custom licence that GitHub cannot classify, and points to a LICENSE file, while a COPYING file sits in the top level entries next to the readme's MIT statement. Those two descriptions do not obviously agree, so anyone with a compliance obligation should read both files rather than rely on the readme summary.

## Building from source, and reading the changelog before you do

The repository contains an autogen.sh script next to configure.ac, so the conventional autotools path is available on Unix-like systems, while build-msvc/ covers the Microsoft compiler. The test/ directory exists for the test suite, and ffms2.pc.in is the template for the pkg-config metadata. The readme does not spell out the exact configure invocation for the plugin components, so anyone building from source should work from the INSTALL file and the configure options rather than from guesses.

The build sequence that is clear from the layout is autogen.sh, then configure, then make, with the exact flags depending on which optional components you want, and those choices in turn determine the licence of what you produce.

Version information comes from version.sh, and the release history lives in doc/ffms2-changelog.md. The tagged releases show 5.0-RC3 on 2024-03-07, 5.0-RC4 on 2024-05-08 and 5.0 on 2024-05-28, so the 5.0 line has been stable across a fair stretch of time, while the last push to the repository was on 2026-04-27. The repository is not archived.

## Where calling FFmpeg directly is the better choice

The real alternative is to link against FFmpeg's own libraries and do the indexing yourself. The difference in approach is straightforward: FFmpeg exposes decoders and demuxers, while FFMS2 exposes indexed frames and samples on top of them. If your tool only needs to decode straight through, for example to transcode or to read a handful of packets, the wrapper adds a layer and buys you nothing.

The wrapper earns its place when the workload is random access. Frame accurate seeking, a preview generator, a comparison tool, an encoder that needs to reference an earlier frame, all of these need the index that FFMS2 builds. Building it yourself is possible but it means maintaining format specific knowledge that the library already encodes.

Two things argue against it regardless of workload. The first is the licence entanglement described above, which a direct FFmpeg build at least lets you control explicitly. The second is the dependency surface: FFMS2 tracks FFmpeg changes on its own schedule, and if your project needs a feature fixed in a specific FFmpeg revision you may be waiting on the wrapper rather than on the library underneath.

## Conclusion

Adopt FFMS2 when you are writing a tool that must open arbitrary media and index frames precisely, and when a C linkable API matters to you. Do not adopt it if you need a guaranteed licence for shipped binaries, because the official Windows builds are GPLv3 because of how FFmpeg was compiled, and the source tree lists a COPYING file alongside the MIT statement in the readme. Before starting, read doc/ffms2-api.md and doc/ffms2-changelog.md, confirm your FFmpeg build against the optional GPL components, and check the 5.0 release notes, since the last push was on 2026-04-27 and the newest tagged release is 5.0 from 2024-05-28.

## FAQ

### What is FFMS2 used for?

FFMS2 is a cross-platform wrapper library around FFmpeg that provides frame and sample accurate access to media files without requiring the caller to handle the FFmpeg API directly. The same library powers the Avisynth and VapourSynth source plugins.

### Is FFMS2 written in C or C++?

The implementation is written in C++, but the public API is pure C, so any project that can link to a C library can use it. The repository builds with autotools on Unix-like systems and with the Microsoft compiler through build-msvc/.

### Which licence applies to FFMS2 binaries?

The source is available under the MIT licence, but the licence of the binaries depends on how FFmpeg was compiled. Optional components that require a GPL FFmpeg make the build GPL as well, and the official Windows builds are GPLv3 for that reason.

### Which FFMS2 build should I download?

The project says that if you do not know what you want, you want the standard 32-bit build with no suffix. The -x64 build is for 64-bit Avisynth, -avs-cplugin is the C written plugin for the newer Avisynth 2.6 colourspaces, and rNUMBER packages are testing builds that may be less stable.

### How do I add the FFMS2 source plugin to Avisynth?

The project documents that path in doc/ffms2-avisynth.md, and the plugin is part of the FFMS2 project itself rather than a separate download. Its properties include support for Unicode filenames outside the system codepage, variable framerate support and not relying on external decoders.

### Is FFMS2 still being worked on?

The repository is not archived and the last push was on 2026-04-27. The most recent tagged release is 5.0, published on 2024-05-28, with 5.0-RC4 and 5.0-RC3 before it, and the changes between tags are listed in doc/ffms2-changelog.md.

## Sources

- [FFMS/ffms2 on GitHub](https://github.com/FFMS/ffms2)
- [Issues](https://github.com/FFMS/ffms2/issues)
- [README](https://github.com/FFMS/ffms2/blob/master/README.md)
- [Releases](https://github.com/FFMS/ffms2/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ffms-ffms2