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:

```bash
python pymp4dump.py input.mp4
```

With verbosity:

```bash
python pymp4dump.py input.mp4 --verbosity 2
```

JSON output:

```bash
python pymp4dump.py input.mp4 --format json
```

---

## DRM / PSSH Extraction

Extract full PlayReady PSSH (base64):

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

Extract only PlayReady payload (base64):

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

---

## Track Dumping

Dump a specific track:

```bash
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:

```python
from pymp4dump import extract_playready_pssh_from_mp4

pssh = extract_playready_pssh_from_mp4("init.mp4")

print("PlayReady PSSH:", pssh)
```

Alternative helper:

```python
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