{"id":6061,"library":"pymp4","title":"pymp4: MP4 Box Parser","description":"pymp4 is a Python library designed for parsing MP4 boxes, providing a structured way to read and interpret the internal components of an MP4 file. It focuses on low-level access to box data. The current version is 1.4.0, and releases occur periodically, often in response to bug fixes or new box definitions.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/beardypig/pymp4","tags":["mp4","parser","video","media","boxes","isobmff"],"install":[{"cmd":"pip install pymp4","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"BoxParser","correct":"from pymp4.parser import BoxParser"},{"note":"Base class for all MP4 boxes; often used for type hinting or general box iteration.","symbol":"Box","correct":"from pymp4.dataclasses import Box"},{"note":"Example of importing a specific box type for direct access or inspection. Other box types are available in `pymp4.boxes`.","symbol":"ftyp","correct":"from pymp4.boxes import ftyp"}],"quickstart":{"code":"import os\nfrom pymp4.parser import BoxParser\n\n# For demonstration, we'll create a dummy MP4 file.\n# In a real scenario, you would open an existing MP4 file.\ndummy_mp4_path = \"dummy_test.mp4\"\ntry:\n    # A minimal, valid MP4 often starts with an 'ftyp' box.\n    # This is not a full MP4 file, just a placeholder to demonstrate parsing.\n    # Real files are more complex and would have many more boxes.\n    with open(dummy_mp4_path, \"wb\") as f:\n        f.write(b'\\x00\\x00\\x00\\x18ftypisom\\x00\\x00\\x00\\x01isomiso2avc1mp41')\n        f.write(b'\\x00\\x00\\x00\\x08moov') # Placeholder for a moov box\n\n    # Initialize the parser\n    parser = BoxParser()\n\n    # Open the MP4 file in binary read mode\n    with open(dummy_mp4_path, \"rb\") as f:\n        # Parse all top-level boxes\n        print(f\"Parsing boxes from '{dummy_mp4_path}':\")\n        for box in parser.parse(f):\n            print(f\"  Parsed Box: type={box.type.decode('ascii')}, size={box.size}\")\n            if box.type == b'ftyp':\n                print(f\"    Major Brand: {box.major_brand.decode('ascii')}\")\n                print(f\"    Minor Version: {box.minor_version}\")\n                print(f\"    Compatible Brands: {[b.decode('ascii') for b in box.compatible_brands]}\")\n            elif box.type == b'moov':\n                print(f\"    (This is a placeholder moov box. Real ones contain child boxes like 'trak', 'mvhd' etc.)\")\n\nexcept FileNotFoundError:\n    print(f\"Error: Dummy file '{dummy_mp4_path}' could not be created or found.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dummy_mp4_path):\n        os.remove(dummy_mp4_path)\n        print(f\"Cleaned up '{dummy_mp4_path}'.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.4.0 onwards"},{"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`).","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}