pymp4dump

pymp4dump is a Python-based tool for parsing, inspecting, and extracting data from MP4 / ISO BMFF (CENC) files. It focuses on accurate box-level parsing, DRM metadata extraction, and structured output for analysis workflows.

Features

Full parsing of MP4 / ISO BMFF box structure
Support for fragmented (fMP4) and non-fragmented files
Detailed decoding of:
- Track metadata (video, audio, subtitles)
- Sample tables (stsz, stsc, stco, etc.)
- Codec configurations (avcC, hvcC, dvcC, etc.)
Built-in support for DRM systems:
- PlayReady
- Widevine
- FairPlay
Extraction of:
- Complete PSSH boxes (base64 / hex)
- Inner PSSH payload (base64)
JSON and human-readable output modes
Track dumping (raw sample extraction)
Stream-safe parsing for large files

Requirements

Python 3.9 or higher

No external dependencies required (standard library only).

Usage

Basic dump:

python pymp4dump.py input.mp4

With verbosity:

python pymp4dump.py input.mp4 --verbosity 2

JSON output:

python pymp4dump.py input.mp4 --format json

DRM / PSSH Extraction

Extract full PlayReady PSSH (base64):

python pymp4dump.py input.mp4 --extract-playready-pssh

Extract only PlayReady payload (base64):

python pymp4dump.py input.mp4 --extract-playready-payload

Track Dumping

Dump a specific track:

python pymp4dump.py input.mp4 --track 1

Output will be:

input.mp4.1

Note: Decryption keys are accepted for CLI compatibility but decryption is not performed.

Python Usage

Basic PlayReady extraction:

from pymp4dump import extract_playready_pssh_from_mp4

pssh = extract_playready_pssh_from_mp4("init.mp4")

print("PlayReady PSSH:", pssh)

Alternative helper:

from pymp4dump import extract_playready_pssh_payload_from_mp4

payload = extract_playready_pssh_payload_from_mp4("init.mp4")
print("PlayReady Payload:", payload)

Notes

This project is inspired by tools like Bento4 mp4dump, but implemented fully in Python for flexibility and integration into custom workflows.

It is especially useful for:

DRM analysis
Media reverse engineering
Automation pipelines (Widevine / PlayReady workflows)
Inspecting initialization segments (init.mp4)

Limitations

No media decryption is performed
Track dumping outputs raw samples only
Some proprietary or uncommon box types may not be fully decoded

Issues and Support

If you encounter any issues, please open an issue in the repository. Support and updates will be provided as time permits.

Acknowledgements

Inspired by:

Bento4
ISO BMFF specification
DRM reverse engineering community