pymp4dump/README.md

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