pymp4v2 - Python Bindings for mp4v2

Alpha. Python bindings for a subset of the mp4v2 C API (v2.1.3). This is not a complete wrap of mp4v2: hint/streaming, generic iTMF, and most profile-level APIs are out of scope for Alpha.

What is bound

• pymp4v2.MP4File — open with mode "r" / "w" / "a" ("r+"), context manager, .tracks / Track, .tags / Tags, duration / timescale, get_info(), optimize(), save(), close()
• pymp4v2.raw — file I/O (MP4CreateEx for ftyp brands / iods; no I/O callbacks), tracks, file/track properties (named + generic get/set), sample read/write/copy (bytes, including lookup by time), iTMF tags (string + numeric setters, artwork as bytes), chapters (MP4GetChapters / MP4SetChapters / Qt + Nero)
• pymp4v2.MP4Error — raised on C failures (false / MP4_INVALID_*); subclass of RuntimeError
• PEP 561 type stubs (.pyi + py.typed) ship in the wheel

Not bound (Alpha, out of scope): iTMF generic atoms, hint/streaming, custom I/O callbacks, MP4ReadProvider, MPEG-4 profile-level setters.

Requirements

Build Dependencies

• Python 3.9+
• C++17 compatible compiler
• CMake 3.28+ (pulled in by the build backend if missing)
• Ninja (optional; pulled in by the build backend)

The extension is built with scikit-build-core. mp4v2 v2.1.3 is fetched by CMake FetchContent and statically linked.

Python Dependencies

• scikit-build-core >= 0.10
• pybind11 >= 2.12

Installation

See the Installation file.

Usage

See the Usage file.

Scripts in examples/ (dump_info.py, retag.py, extract_samples.py) exercise the same APIs against a real file.

API Reference

See the API file.

Running Tests

Tests generate a tiny MP4 with MP4Create; they do not need tests/sample.mp4.

pip install -e .[dev]
pytest tests/

Contributing

See the CONTRIBUTING.md file.

License

The pymp4v2 bindings are MIT.

The native extension statically links mp4v2 v2.1.3, which is MPL 1.1. See NOTICE for the pinned tarball URL and SHA256. The corresponding mp4v2 source is the official v2.1.3 release.

Acknowledgments

• mp4v2 library authors for the underlying C++ library
• Pybind11 team for the excellent binding infrastructure

Support

If you encounter any issues or have questions, please file an issue on the GitHub issue tracker.

Changelog

See the CHANGELOG.md file for a history of changes to the project.