{"id":12970,"library":"codem-isoboxer","title":"codem-isoboxer","description":"codem-isoboxer is a lightweight JavaScript parser for MP4 (MPEG-4, ISOBMFF) files and boxes, primarily designed for browser environments. Its current stable version is 0.3.10, with releases occurring as features and bug fixes are integrated, rather than on a fixed schedule. The library's core purpose is to provide a small, fast, and efficient way to extract metadata and validate ISOBMFF segments, making it suitable for integration into player frameworks or for analyzing media files. Key differentiators include its focus on minimal overhead, direct manipulation of ArrayBuffers and DataViews, and specific support for boxes relevant to emerging standards like MPEG-DASH (e.g., `emsg` boxes) and HLS using fragmented MP4, as well as timed text overlays. It offers a relatively raw interface, providing box structures with minimal abstraction, allowing developers fine-grained control over parsing and data access.","status":"active","version":"0.3.10","language":"javascript","source_language":"en","source_url":"https://github.com/madebyhiro/codem-isoboxer","tags":["javascript","mp4","mpeg-4","mpeg4","isobmff","parser"],"install":[{"cmd":"npm install codem-isoboxer","lang":"bash","label":"npm"},{"cmd":"yarn add codem-isoboxer","lang":"bash","label":"yarn"},{"cmd":"pnpm add codem-isoboxer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is designed for browser environments and exposes `ISOBoxer` as a global variable. It does not provide ESM or CommonJS module exports for direct `import` or `require`.","wrong":"import ISOBoxer from 'codem-isoboxer';\nconst ISOBoxer = require('codem-isoboxer');","symbol":"ISOBoxer","correct":"// ISOBoxer is available globally after <script src=\"iso_boxer.min.js\"></script>"},{"note":"`parseBuffer` is a method of the global `ISOBoxer` object, not a named export. It expects an `ArrayBuffer` as input.","wrong":"import { parseBuffer } from 'codem-isoboxer';","symbol":"ISOBoxer.parseBuffer","correct":"const parsedFile = ISOBoxer.parseBuffer(arrayBuffer);"},{"note":"`fetch` and `fetchAll` are methods available on the `parsedFile` object returned by `ISOBoxer.parseBuffer`, used for traversing the box structure.","wrong":"import { fetch } from 'codem-isoboxer';","symbol":"ParsedFile.prototype.fetch","correct":"const ftypBox = parsedFile.fetch('ftyp');"}],"quickstart":{"code":"// Simulate an ArrayBuffer for demonstration (a minimal ftyp box)\n// In a real scenario, this buffer would come from XHR, FileReader, etc.\nconst buffer = new ArrayBuffer(16);\nconst view = new DataView(buffer);\nview.setUint32(0, 16, false); // Box size: 16 bytes\nview.setUint32(4, 0x66747970, false); // Box type: \"ftyp\"\nview.setUint32(8, 0x69736f6d, false); // Major brand: \"isom\"\nview.setUint32(12, 0x00000001, false); // Minor version: 1\n\n// In a browser, ISOBoxer would be globally available after including the script:\n// <script src=\"iso_boxer.min.js\"></script>\n\n// For this runnable quickstart demonstration, we'll mock ISOBoxer\n// In your actual browser code, remove this mock and assume ISOBoxer is global.\nconst ISOBoxer = (() => {\n    const parseBuffer = (arrayBuffer) => {\n        const dv = new DataView(arrayBuffer);\n        const boxes = [];\n        let offset = 0;\n        while (offset < arrayBuffer.byteLength) {\n            const size = dv.getUint32(offset, false);\n            const typeCode = dv.getUint32(offset + 4, false);\n            const type = String.fromCharCode(\n                (typeCode >> 24) & 0xFF,\n                (typeCode >> 16) & 0xFF,\n                (typeCode >> 8) & 0xFF,\n                typeCode & 0xFF\n            );\n            // In a real parse, more box-specific data would be extracted\n            boxes.push({ _type: type, _size: size, _offset: offset });\n            offset += size;\n            if (size === 0) break; // Avoid infinite loop for malformed box\n        }\n        return {\n            boxes: boxes,\n            fetch: (boxType) => boxes.find(b => b._type === boxType),\n            fetchAll: (boxType) => boxes.filter(b => b._type === boxType)\n        };\n    };\n    return { parseBuffer };\n})();\n\nconst parsedFile = ISOBoxer.parseBuffer(buffer);\nconsole.log('All parsed boxes:', parsedFile.boxes); \n// Expected: [{ _type: 'ftyp', _size: 16, _offset: 0 }]\n\nconst ftypBox = parsedFile.fetch('ftyp');\nif (ftypBox) {\n    console.log('Fetched ftyp box:', ftypBox); \n}\n\nconst allMdatBoxes = parsedFile.fetchAll('mdat');\nif (allMdatBoxes.length === 0) {\n    console.log('No mdat boxes found in this example buffer.');\n}","lang":"javascript","description":"This quickstart demonstrates how to parse an `ArrayBuffer` containing ISOBMFF data using `ISOBoxer.parseBuffer` and then how to retrieve specific boxes using `fetch` and `fetchAll` methods from the resulting `ParsedFile` object. It includes a mock for `ISOBoxer` to make the code runnable outside a browser environment for testing purposes, but in a real browser, `ISOBoxer` is a global."},"warnings":[{"fix":"Include the library via a `<script>` tag in your HTML (`<script src=\"path/to/iso_boxer.min.js\"></script>`) and access its functionality through the global `ISOBoxer` object.","message":"codem-isoboxer is designed for browser environments and exposes its API as a global `ISOBoxer` object. It does not provide CommonJS or ESM module exports, meaning standard `import` or `require` statements will not work without a build step that specifically bundles or adapts it.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consult the 'Box Support' wiki page on GitHub. For unsupported boxes, refer to the `src/parsers` directory in the source code to understand how to add new box parsers.","message":"The library supports a limited, though extensible, set of ISOBMFF boxes. If you need to parse a box type not listed in the README or Wiki, you will need to implement a custom parser for it and extend the library.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Be prepared to implement additional logic to interpret the specific data structures within the parsed boxes, especially for more complex or application-specific fields. Understand the ISOBMFF specification for the boxes you are parsing.","message":"codem-isoboxer provides a relatively raw interface to ISOBMFF data. It makes minimal assumptions about file validity and performs limited handling of complex data types, often returning raw buffer views or basic parsed values. Developers must handle further interpretation of specific box contents.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your target browser environment supports these APIs. For Node.js usage, consider alternative libraries or integrate polyfills for the required browser APIs.","message":"The library explicitly requires `ArrayBuffer` and `DataView` support, and optionally `TextDecoder`, which are standard modern browser APIs. It is not intended for Node.js environments without polyfills or specific browser-emulating setups.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `iso_boxer.min.js` script is correctly included in your HTML before attempting to use `ISOBoxer`. Verify the script path and that it's loaded synchronously or before your script executes.","cause":"The `ISOBoxer` global object was not loaded or is not in scope.","error":"ReferenceError: ISOBoxer is not defined"},{"fix":"Check the network tab in your browser's developer tools to confirm `iso_boxer.min.js` loaded successfully without errors. Ensure no other script is overwriting the `ISOBoxer` global variable.","cause":"The `ISOBoxer` object exists, but `parseBuffer` is not a property or is not a function. This often indicates incorrect loading or a corrupt script.","error":"TypeError: ISOBoxer.parseBuffer is not a function"},{"fix":"Ensure you are passing a valid `ArrayBuffer` instance to `ISOBoxer.parseBuffer`. Common mistakes include passing a `Blob`, `File` object, or `Uint8Array` directly without converting to `ArrayBuffer` first (e.g., `await blob.arrayBuffer()`).","cause":"The `parseBuffer` function was called with an argument that is not a valid `ArrayBuffer` or a compatible object.","error":"TypeError: Cannot read properties of undefined (reading 'byteLength')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}