pymp4: MP4 Box Parser

Warnings

• breaking The definition of `TrackEncryptionBox` (tenc) was significantly corrected in v1.4.0. Fields like `version`, `is_encrypted`, and `iv_size` now have strict value constraints.
  Fix: If your code interacts with or inspects `TrackEncryptionBox` fields, review the updated definitions. Ensure that `version` is 0 or 1, `is_encrypted` is 0 or 1, and `iv_size` is 0 or 8. Relying on previous, potentially incorrect, field values may lead to parsing errors or unexpected behavior.
• gotcha `pymp4` is exclusively a parser library. It is designed to read and interpret existing MP4 box structures but does not provide functionality for creating, modifying, or writing MP4 files.
  Fix: Understand the library's scope. If you need to manipulate or generate MP4 files, you will need to combine `pymp4` with other libraries or tools (e.g., `mp4box.js` via external processes, `ffmpeg`).
• gotcha The library expects valid MP4 box structures. Parsing malformed or corrupted MP4 files may lead to exceptions, partial parsing, or incorrect data interpretation rather than graceful error recovery in all scenarios.
  Fix: Ensure input MP4 files are well-formed. Implement robust `try-except` blocks around parsing logic when dealing with files from untrusted sources or those that might be incomplete/corrupted, to handle potential `struct.error`, `IndexError`, or `EOFError`.

Install

• pip install pymp4 Install stable version

Imports

• BoxParser

  from pymp4.parser import BoxParser

• Box

  from pymp4.dataclasses import Box

  Base class for all MP4 boxes; often used for type hinting or general box iteration.
• ftyp

  from pymp4.boxes import ftyp

  Example of importing a specific box type for direct access or inspection. Other box types are available in `pymp4.boxes`.

Quickstart

This quickstart demonstrates how to use `pymp4` to parse top-level boxes from an MP4 file. It creates a simple dummy MP4 file for demonstration, then uses `BoxParser` to iterate through and print information about the parsed boxes. In a real application, you would replace the dummy file creation with opening an existing MP4 file.

import os
from pymp4.parser import BoxParser

# For demonstration, we'll create a dummy MP4 file.
# In a real scenario, you would open an existing MP4 file.
dummy_mp4_path = "dummy_test.mp4"
try:
    # A minimal, valid MP4 often starts with an 'ftyp' box.
    # This is not a full MP4 file, just a placeholder to demonstrate parsing.
    # Real files are more complex and would have many more boxes.
    with open(dummy_mp4_path, "wb") as f:
        f.write(b'\x00\x00\x00\x18ftypisom\x00\x00\x00\x01isomiso2avc1mp41')
        f.write(b'\x00\x00\x00\x08moov') # Placeholder for a moov box

    # Initialize the parser
    parser = BoxParser()

    # Open the MP4 file in binary read mode
    with open(dummy_mp4_path, "rb") as f:
        # Parse all top-level boxes
        print(f"Parsing boxes from '{dummy_mp4_path}':")
        for box in parser.parse(f):
            print(f"  Parsed Box: type={box.type.decode('ascii')}, size={box.size}")
            if box.type == b'ftyp':
                print(f"    Major Brand: {box.major_brand.decode('ascii')}")
                print(f"    Minor Version: {box.minor_version}")
                print(f"    Compatible Brands: {[b.decode('ascii') for b in box.compatible_brands]}")
            elif box.type == b'moov':
                print(f"    (This is a placeholder moov box. Real ones contain child boxes like 'trak', 'mvhd' etc.)")

except FileNotFoundError:
    print(f"Error: Dummy file '{dummy_mp4_path}' could not be created or found.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(dummy_mp4_path):
        os.remove(dummy_mp4_path)
        print(f"Cleaned up '{dummy_mp4_path}'.")