### Basic File Creation Example

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Demonstrates the basic usage of creating a new MP4Box file object.

```typescript
// TypeScript/JavaScript examples
const mp4file = createFile();
```

--------------------------------

### Basic MP4Box.js Setup

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/quick-start.md

Initializes MP4Box.js, sets up event handlers for file readiness and errors, and appends an ArrayBuffer to the parser. This is the fundamental setup for processing an MP4 file.

```typescript
import { createFile, MP4BoxBuffer } from 'mp4box';

const mp4file = createFile();

mp4file.onReady = (info) => {
  console.log('File loaded with', info.tracks.length, 'tracks');
};

mp4file.onError = (module, message) => {
  console.error(`Error: ${message}`);
};

const buffer = new MP4BoxBuffer(arrayBuffer.byteLength);
new Uint8Array(buffer).set(new Uint8Array(arrayBuffer));
buffer.fileStart = 0;

mp4file.appendBuffer(buffer, true);
```

--------------------------------

### Sample Extraction Example

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Shows how to extract samples from an MP4 file, specifically for metadata tracks. It configures sample extraction options, starts the process, and logs details of each extracted sample.

```typescript
const mp4file = createFile();

mp4file.onReady = (info) => {
  const textTrack = video.addTextTrack('metadata', 'Metadata');
  mp4file.setExtractionOptions(info.tracks[0].id, textTrack);
  mp4file.start();
};

mp4file.onSamples = (id, user, samples) => {
  for (const sample of samples) {
    console.log(`Sample: CTS=${sample.cts}, DTS=${sample.dts}, size=${sample.size}`);
  }
};
```

--------------------------------

### Create ISOFile Instance Example

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Demonstrates how to create a new ISOFile instance using the createFile helper function or by providing a custom MultiBufferStream.

```typescript
import { createFile } from 'mp4box';

const mp4file = createFile();
// or with custom stream:
import { MultiBufferStream } from 'mp4box';
const stream = new MultiBufferStream();
const mp4file = new ISOFile(stream, true);
```

--------------------------------

### Creating an MP4 File

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Provides an example of initializing MP4Box.js to create a new MP4 file, setting its properties, and adding tracks.

```APIDOC
## Creating an MP4 File

### Description
This example demonstrates the initial steps for creating a new MP4 file using MP4Box.js, including setting file brands, timescale, dimensions, and adding a video track.

### Method
```typescript
const mp4file = createFile();

mp4file.init({
  brands: ['isom', 'iso2', 'avc1'],
  timescale: 1000,
  width: 1920,
  height: 1080
});

mp4file.addTrack({
  type: 'avc1',
  width: 1920,
  height: 1080
});

// Add samples...
// Get buffer and save...
```

### See Also
- [Configuration Reference](./configuration.md)
- [ISOFile Reference](./api-reference-isofile.md#file-creation)
```

--------------------------------

### start

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Initiates the processing of samples, enabling segmentation or extraction. Once started, appending new buffers will also trigger sample processing.

```APIDOC
## start()

### Description
Indicates that sample processing can start (segmentation or extraction). Sample data already received will be processed and new buffer append operation will trigger sample processing as well.

### Method
`start`

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```javascript
mp4boxfile.start();
```

### Response
None
```

--------------------------------

### Install MP4Box.js Dependencies

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Installs the necessary dependencies for the MP4Box.js project using npm. This is a prerequisite for building the library.

```bash
npm install
```

--------------------------------

### Install MP4Box.js via npm

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Install the latest version of MP4Box.js using npm. This command is typically run in your project's root directory.

```bash
npm install mp4box@latest
```

--------------------------------

### Create and Log an MP4Box Instance in Browser

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Demonstrates the basic usage of MP4Box.js in a browser environment by creating a new MP4Box instance and logging it to the console. This example assumes the library has been included via a script tag.

```javascript
      // Create a new MP4Box instance
      const mp4box = MP4Box.createFile();

      // Example usage: Add a file to the MP4Box instance
      // Note: You would typically fetch or read a file here
      // For demonstration, we will just log the instance
      console.log(mp4box);
```

--------------------------------

### Append Buffer Example

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Shows how to append buffers to an ISOFile instance, including setting up the onReady callback and simulating file chunk reading. Ensure the 'fileStart' property is correctly set for each buffer.

```typescript
const mp4file = createFile();
mp4file.onReady = (info) => {
  console.log('File info:', info);
};

// Simulate reading file in chunks
const fileBuffer = /* ArrayBuffer from fetch or file read */;
const buffer = new MP4BoxBuffer(fileBuffer.byteLength);
new Uint8Array(buffer).set(new Uint8Array(fileBuffer));
buffer.fileStart = 0;

mp4file.appendBuffer(buffer, false);
// ... append more buffers ...
mp4file.appendBuffer(lastBuffer, true);
```

--------------------------------

### MP4Box ISOFile for Media Source Extensions (MSE)

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-create-file.md

Example demonstrating how to use createFile with Media Source Extensions for adaptive streaming. It sets up source buffers and appends initialization and media segments.

```typescript
import { createFile } from 'mp4box';

const video = document.querySelector('video');
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);

const mp4file = createFile();

mediaSource.addEventListener('sourceopen', () => {
  const sourceBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.42c00d"');
  
  mp4file.onReady = (info) => {
    console.log('File loaded, setting up segmentation');
    mp4file.setSegmentOptions(info.tracks[0].id, sourceBuffer, {
      nbSamples: 1000
    });
    
    const initSegs = mp4file.initializeSegmentation();
    sourceBuffer.appendBuffer(initSegs.buffer);
  };
  
  mp4file.onSegment = (trackId, user, buffer, nextSample, last) => {
    user.appendBuffer(buffer);
  };
});

// Fetch and append file data
fetch('video.mp4')
  .then(response => response.arrayBuffer())
  .then(arrayBuffer => {
    const mp4buffer = new MP4BoxBuffer(arrayBuffer.byteLength);
    new Uint8Array(mp4buffer).set(new Uint8Array(arrayBuffer));
    mp4buffer.fileStart = 0;
    mp4file.appendBuffer(mp4buffer, true);
  });
```

--------------------------------

### createFile Function Reference

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Documentation for the primary entry point function `createFile`. It details the function signature, parameters, return values, and provides usage examples for building MP4 files.

```APIDOC
## createFile Function

### Description
The main entry point function for creating MP4 files programmatically. It allows users to build MP4 files from scratch, supporting multiple tracks and fragmentation.

### Signature
`createFile(options, callback)`

### Parameters
- **options** (object): Configuration options for file creation, including track definitions, codecs, and fragmentation settings.
- **callback** (function): A callback function to receive the created MP4 file data or an error.

### Return Value
- The function typically returns an `ISOFile` instance or initiates a callback with the file data.

### Usage
```javascript
// Example usage (conceptual)
createFile({
  tracks: [
    { type: 'video', ... },
    { type: 'audio', ... }
  ]
}, (fileData) => {
  // Use the created file data
});
```
```

--------------------------------

### Progressive Parsing and Playback Example

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Demonstrates how to progressively parse an MP4 file and prepare it for playback using Media Source Extensions. It includes setting up event handlers for file readiness, segment processing, and errors, and simulates streaming by appending buffer chunks.

```typescript
import { createFile } from 'mp4box';

const mp4file = createFile();
const sourceBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.42c00d"');

mp4file.onReady = (info) => {
  console.log('File ready:', info);
};

mp4file.onSegment = (id, user, buffer) => {
  user.appendBuffer(buffer);
};

mp4file.onError = (module, message) => {
  console.error(`${module}: ${message}`);
};

// Simulate streaming
const fileSize = 1000000;
const chunkSize = 65536;

for (let offset = 0; offset < fileSize; offset += chunkSize) {
  const chunk = /* fetch bytes from offset to offset + chunkSize */;
  const buffer = new MP4BoxBuffer(chunk.byteLength);
  new Uint8Array(buffer).set(new Uint8Array(chunk));
  buffer.fileStart = offset;
  
  mp4file.appendBuffer(buffer, offset + chunkSize >= fileSize);
}
```

--------------------------------

### Conventional Commit Example (Feature)

Source: https://github.com/gpac/mp4box.js/blob/main/CONTRIBUTING.md

Example of a commit message following Conventional Commits for a new feature.

```git
feat: Add new 'prft' box from 14496-12
```

--------------------------------

### Start Sample Processing

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Enables sample processing for all configured tracks. This should be called after setting up segmentation or extraction options and initializing segments.

```typescript
start(): void
```

```typescript
mp4file.onReady = (info) => {
  mp4file.setSegmentOptions(info.tracks[0].id, sourceBuffer);
  mp4file.initializeSegmentation();
  mp4file.start(); // Begin processing
};
```

--------------------------------

### seek

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Sets the starting point for sample processing to a specific time or the nearest Random Access Point.

```APIDOC
## seek(time, useRap)

### Description
Indicates that the next samples to process (for extraction or segmentation) start at the given time (Number, in seconds) or at the time of the previous Random Access Point (if useRap is true, default is false). Returns the offset in the file of the next bytes to be provided via [appendBuffer](#appendbufferdata).

### Parameters
#### Path Parameters
- **time** (Number) - Required - The time in seconds to seek to.
- **useRap** (boolean) - Optional - If true, seek to the nearest Random Access Point before the specified time. Defaults to false.

### Request Example
```javascript
mp4boxfile.seek(10, true);
```
```

--------------------------------

### Extracting Media Samples

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

This example demonstrates how to configure MP4Box.js for sample extraction from an MP4 track. The `onSamples` callback is used to process the raw media sample data, which can then be used for various purposes like analysis or re-encoding.

```typescript
const mp4file = createFile(true);

mp4file.onReady = (info) => {
  mp4file.setExtractionOptions(info.tracks[0].id, user);
  mp4file.start();
};

mp4file.onSamples = (id, user, samples) => {
  for (const sample of samples) {
    // Process raw sample data...
  }
};

// Load file...
```

--------------------------------

### Handle 'moov' Box Parsing Start

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

This callback is triggered when the parsing of the 'moov' box begins. It's useful for logging or initiating actions while the 'moov' box data is being processed.

```javascript
mp4boxfile.onMoovStart = function () {
  console.log('Starting to receive File Information');
};
```

--------------------------------

### Example MP4 Box Implementation (prftBox)

Source: https://github.com/gpac/mp4box.js/blob/main/CONTRIBUTING.md

This TypeScript code demonstrates the structure for implementing a new MP4 box, specifically the 'prft' (ProducerReferenceTimeBox). It includes parsing logic based on the box version.

```typescript
import { FullBox } from '#/box';
import type { MultiBufferStream } from '#/buffer';

export class prftBox extends FullBox {
  static override readonly fourcc = 'prft' as const;
  box_name = 'ProducerReferenceTimeBox' as const;

  ref_track_id: number;
  ntp_timestamp: number;
  media_time: number;

  parse(stream: MultiBufferStream) {
    this.parseFullHeader(stream);
    this.ref_track_id = stream.readUint32();
    this.ntp_timestamp = stream.readUint64();
    if (this.version === 0) {
      this.media_time = stream.readUint32();
    } else {
      this.media_time = stream.readUint64();
    }
  }
}
```

--------------------------------

### Configure Track for Sample Extraction

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Configures a track for sample extraction. Specify the number of samples per callback and whether to start with Random Access Points only.

```typescript
setExtractionOptions(
  track_id: number,
  user: TSampleUser,
  options: Partial <{
    nbSamples: number;
    rapAlignement: boolean;
  }>;
): void
```

```typescript
mp4file.onReady = (info) => {
  const textTrack = video.addTextTrack('metadata', 'Extracted metadata');
  mp4file.setExtractionOptions(info.tracks[0].id, textTrack, {
    nbSamples: 500
  });
  mp4file.start();
};

mp4file.onSamples = (id, user, samples) => {
  for (const sample of samples) {
    // Process sample data
    const data = new Uint8Array(sample.data);
    console.log(`Sample ${sample.number}: ${data.byteLength} bytes`);
  }
};
```

--------------------------------

### Progressive Download and MSE Playback

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/quick-start.md

Sets up MP4Box.js for progressive download and playback using Media Source Extensions (MSE). It configures source buffers for each track and appends initialization segments, then starts processing the stream.

```typescript
import { createFile, MP4BoxBuffer } from 'mp4box';

const video = document.querySelector('video');
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);

const mp4file = createFile();

mediaSource.addEventListener('sourceopen', () => {
  mp4file.onReady = (info) => {
    // Set up segmentation for each track
    for (const track of info.tracks) {
      const sourceBuffer = mediaSource.addSourceBuffer(
        `video/mp4; codecs="${info.tracks[0].codec}"`
      );
      
      mp4file.setSegmentOptions(track.id, sourceBuffer, {
        nbSamples: 1000,
        rapAlignement: true
      });
    }
    
    // Get initialization segment
    const initSegs = mp4file.initializeSegmentation();
    sourceBuffer.appendBuffer(initSegs.buffer);
    
    // Start processing
    mp4file.start();
  };
  
  mp4file.onSegment = (id, sourceBuffer, buffer, nextSample, last) => {
    sourceBuffer.appendBuffer(buffer);
  };
});

// Stream file data
async function streamFile(url) {
  const response = await fetch(url);
  const reader = response.body.getReader();
  let offset = 0;
  
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      mp4file.flush();
      break;
    }
    
    const buffer = new MP4BoxBuffer(value.length);
    new Uint8Array(buffer).set(value);
    buffer.fileStart = offset;
    offset = mp4file.appendBuffer(buffer);
  }
}

streamFile('video.mp4');
```

--------------------------------

### Sample Access Pattern

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/INDEX.md

Shows the pattern for extracting and processing individual samples from an MP4 track. This involves setting extraction options, starting the extraction process, and handling the received samples.

```typescript
mp4file.setExtractionOptions(trackId, user);
mp4file.onSamples = (id, user, samples) => {
  for (const s of samples) { /* process */ }
};
mp4file.start();
```

--------------------------------

### Streaming with Segmentation Pattern

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/INDEX.md

Demonstrates the common pattern for streaming MP4 data using segmentation. This involves setting segment options, initializing segmentation, starting the stream, and handling incoming segments.

```typescript
mp4file.onReady = (info) => {
  mp4file.setSegmentOptions(trackId, user);
  const init = mp4file.initializeSegmentation();
  mp4file.start();
};
mp4file.onSegment = (id, user, buffer) => { /* ... */ };
mp4file.appendBuffer(buffer);
```

--------------------------------

### Conventional Commit Example (Fix)

Source: https://github.com/gpac/mp4box.js/blob/main/CONTRIBUTING.md

Example of a commit message following Conventional Commits for a bug fix.

```git
fix: Correct parsing of 'prft' box under specific conditions
```

--------------------------------

### Entry Point: createFile

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Details the `createFile` function, which serves as the entry point for creating an MP4Box instance.

```APIDOC
## Entry Point

### Description
The `createFile` function is the primary way to instantiate an MP4Box object, allowing for optional parameters to control data handling and streaming.

### Method
```typescript
createFile(keepMdatData?: boolean, stream?: MultiBufferStream): ISOFile
```

### See Also
- [createFile Reference](./api-reference-create-file.md)
```

--------------------------------

### getMetaHandler()

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Gets the handler type of the meta box within the MP4 file.

```APIDOC
## getMetaHandler()

### Description
Gets the handler type of the meta box within the MP4 file.

### Method
```typescript
getMetaHandler(): string | undefined
```

### Response
#### Success Response
- **handlerType** (string | undefined) - The handler type of the meta box, or undefined if not present
```

--------------------------------

### Initialize MP4Box.js and Load File

Source: https://github.com/gpac/mp4box.js/blob/main/demo/file-segmenter.html

This snippet demonstrates how to initialize MP4Box.js, set up error and ready handlers, and begin processing an MP4 file chunk by chunk. It includes logic for memory usage updates.

```javascript
for (const key in MP4Box) if (MP4Box.hasOwnProperty(key)) window[key] = MP4Box[key];
var mp4 = null;
function updateMemory() {
    document.getElementById('memory_usage').innerText = "jsHeapSizeLimit: "+Math.round(window.performance.memory.jsHeapSizeLimit/(1024*1024))+"MB\n"+
    "totalJSHeapSize: "+Math.round(window.performance.memory.totalJSHeapSize/(1024*1024))+"MB\n"+
    "usedJSHeapSize: "+Math.round(window.performance.memory.usedJSHeapSize/(1024*1024))+"MB";
}
updateMemory();
function load() {
    Log.setLogLevel(Log.info);
    console.log("Creating MP4Box file with parameter: "+document.getElementById('keepMdatInput').checked);
    mp4 = MP4Box.createFile(document.getElementById('keepMdatInput').checked);
    mp4.onError = function(e) {
        console.log(e);
    };
    mp4.onReady = function(info) {
        if (document.getElementById('doSegmentation').checked) {
            console.log("Sample batch size: "+(+document.getElementById('nbSamples').value));
            for (var i = 0; i < info.tracks.length; i++) {
                var track = info.tracks[i];
                mp4.setSegmentOptions(info.tracks[i].id, undefined, { nbSamples: +document.getElementById('nbSamples').value } );
            }
            mp4.initializeSegmentation();
        }
        mp4.start();
    };
    updateMemory();
    mp4.onSegment = function (id, user, buffer, sampleNum, is_last) {
        console.log("Received"+(is_last?" last":"")+" segment on track "+id+" with sample up to "+sampleNum);
        if (document.getElementById('doReleaseSamples').checked) {
            mp4.releaseUsedSamples(id, sampleNum);
        }
        if (is_last) {
            updateMemory();
        }
    }
    var offset = 0;
    var file = document.getElementById('fileInput').files[0];
    if (file) {
        var reader = file.stream().getReader();
        reader.read().then(function getNextChunk({done, value}) {
            if (done) {
                mp4.flush();
                console.log("done");
                document.getElementById('file_size').innerText = Math.round(offset/(1024*1024))+"MB";
                updateMemory();
                // mp4 = null;
                return;
            }
            var copy = value.buffer;
            copy.fileStart = offset;
            offset += value.length;
            mp4.appendBuffer(copy);
            return reader.read().then(getNextChunk);
        });
    }
}
```

--------------------------------

### Process Buffered Samples

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Manually processes buffered samples. This is called automatically when buffers are appended if sample processing is started.

```typescript
processSamples(last?: boolean): void
```

--------------------------------

### init()

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Initializes a new MP4 file structure, preparing it for creation or writing operations. Configuration options can be provided.

```APIDOC
## init()

### Description
Initializes a new MP4 file structure, preparing it for creation or writing operations. Configuration options can be provided.

### Method
```typescript
init(options?: IsoFileOptions): void
```

### Parameters
#### Path Parameters
- **options** (IsoFileOptions) - Optional - Creation options (see Configuration section)
```

--------------------------------

### Initialize MP4 Extraction

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Sets up extraction options for a track and prepares for sample extraction. The `onSamples` callback will be invoked with extracted samples. Requires `MP4Box.createFile()` and `onReady` to be handled.

```javascript
var mp4boxfile = MP4Box.createFile();
mp4boxfile.onReady = function(info) {
  ...
  /* create a texttrack */
  var texttrack = v.addTextTrack("metadata", "Text track for extraction of track "+info.tracks[0].id);
  mp4boxfile.onSamples = function (id, user, samples) {}
  mp4boxfile.setExtractionOptions(info.tracks[0].id, texttrack, options);
  mp4boxfile.start();
  ...
```

--------------------------------

### Get Specific Track Sample

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Retrieves a specific sample from a track by its number. Returns the Sample object or undefined if not found.

```typescript
getTrackSample(track_id: number, number: number): Sample | undefined
```

--------------------------------

### Start Parsing MP4 Data

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Initiates the parsing process from the current stream position. This is usually called automatically when buffers are appended.

```typescript
parse(): void
```

--------------------------------

### File Initialization Configuration

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Defines initial options for file creation, including brands, timescale, and duration.

```typescript
{
  brands?: ['isom', 'iso2', 'avc1'];
  timescale?: 1000;
  duration?: number;
}
```

--------------------------------

### Get fragment duration

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Retrieve the fragment duration using getFragmentDuration(). It returns an object with numerator and denominator or undefined if the file is not fragmented.

```typescript
const fragDuration = mp4file.getFragmentDuration();
if (fragDuration) {
  const seconds = fragDuration.num / fragDuration.den;
  console.log(`Fragment duration: ${seconds}s`);
}
```

--------------------------------

### buildSampleLists()

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Builds the internal sample information tables based on the metadata extracted from the MP4 file.

```APIDOC
## buildSampleLists()

### Description
Builds the internal sample information tables from file metadata.

### Method
`buildSampleLists`

### Parameters
None

### Request Example
```typescript
mp4file.buildSampleLists();
```

### Response
#### Success Response (void)
This method does not return a value.
```

--------------------------------

### Conditional Debug Logging

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/errors-logging.md

Example of enabling debug logging conditionally, for instance, based on an environment variable. This is useful for development and debugging purposes.

```typescript
// Enable debug logging during development
if (process.env.DEBUG) {
  Log.setLogLevel(Log.debug);
}

const mp4file = createFile();
mp4file.appendBuffer(buffer);  // Debug messages now printed
```

--------------------------------

### Create MP4Box File Object and Append Data

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Demonstrates creating an MP4Box ISOFile object, setting error and ready callbacks, and appending data buffers for progressive parsing. The 'onReady' callback is invoked once the 'moov' box is parsed.

```javascript
var MP4Box = require('mp4box'); // Or whatever import method you prefer. 
var mp4boxfile = MP4Box.createFile();
mp4boxfile.onError = function(e) {};
mp4boxfile.onReady = function(info) {};
mp4boxfile.appendBuffer(data);
mp4boxfile.appendBuffer(data);
mp4boxfile.appendBuffer(data);
...
mp4boxfile.flush();
```

--------------------------------

### Get Sample from Track

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Retrieves a specific sample from a track's sample list based on its number. Returns undefined if the sample is not found.

```typescript
getSample(trak: trakBox, sampleNum: number): Sample | undefined
```

--------------------------------

### Access Sample Dependencies

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/advanced-topics.md

Retrieve information about sample dependencies, including whether a sample depends on others, is depended upon, or has redundancy. This is crucial for understanding inter-sample relationships in compressed video streams.

```typescript
const mp4file = createFile();

mp4file.onReady = (info) => {
  const trak = mp4file.getTrackById(1);
  
  for (const sample of trak.samples) {
    // Sample dependency information
    const depends_on = sample.depends_on;  // 0=unknown, 1=yes, 2=no, 3=reserved
    const is_depended_on = sample.is_depended_on;
    const has_redundancy = sample.has_redundancy;
    
    if (depends_on === 1) {
      console.log(`Sample ${sample.number} depends on other samples`);
    }
    if (is_depended_on === 1) {
      console.log(`Sample ${sample.number} is depended on`);
    }
  }
};
```

--------------------------------

### MP4Box.js Entry Point: createFile

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

The `createFile` function is the primary entry point for creating an MP4Box instance. It can optionally accept parameters to control data handling and streaming behavior.

```typescript
createFile(keepMdatData?: boolean, stream?: MultiBufferStream): ISOFile
```

--------------------------------

### Get All Track Samples

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Retrieves all parsed samples for a given track ID. Returns an array of Sample objects or undefined if the track is not found.

```typescript
getTrackSamplesInfo(track_id: number): Sample[] | undefined
```

--------------------------------

### Complete Video File Initialization

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/configuration.md

Initializes an MP4 file with comprehensive video and audio track details. This pattern is suitable for creating feature-rich media files.

```typescript
const mp4file = createFile();

mp4file.init({
  brands: ['isom', 'iso2', 'avc1'],
  timescale: 1000,
  duration: 30000,  // 30 seconds
  width: 1280,
  height: 720
});

mp4file.addTrack({
  id: 1,
  type: 'avc1',
  name: 'Main Video',
  width: 1280,
  height: 720,
  duration: 30000,
  avcDecoderConfigRecord: h264Config
});

mp4file.addTrack({
  id: 2,
  type: 'mp4a',
  name: 'Stereo Audio',
  language: 'eng',
  samplerate: 48000,
  channel_count: 2,
  samplesize: 16,
  duration: 30000
});
```

--------------------------------

### Get the entire MP4 file as a Uint8Array

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Returns the complete parsed MP4 file content as a single `Uint8Array`. This is useful for downloading or further processing the entire file.

```typescript
const fileData = mp4file.getBuffer();
// Download or process fileData
```

--------------------------------

### Create and Download an MP4 File

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/quick-start.md

Initializes an MP4 file, adds video track and samples, then generates and downloads the file as a Blob.

```typescript
const mp4file = createFile();

// Initialize file
mp4file.init({
  brands: ['isom', 'iso2', 'avc1'],
  timescale: 1000,
  duration: 5000,  // 5 seconds
  width: 1920,
  height: 1080
});

// Add video track
mp4file.addTrack({
  id: 1,
  type: 'avc1',
  width: 1920,
  height: 1080,
  timescale: 30000,
  duration: 5000
});

// Add samples (from encoder)
for (const frame of encodedFrames) {
  mp4file.addSample({
    number: sampleNum,
    track_id: 1,
    timescale: 30000,
    dts: frame.timestamp,
    cts: frame.timestamp,
    duration: 1001,
    size: frame.data.length,
    is_sync: frame.isKeyframe,
    data: new Uint8Array(frame.data)
  });
  sampleNum++;
}

// Generate file
const uint8Array = mp4file.getBuffer();
const blob = new Blob([uint8Array], { type: 'video/mp4' });
const url = URL.createObjectURL(blob);

// Download
const link = document.createElement('a');
link.href = url;
link.download = 'video.mp4';
link.click();
```

--------------------------------

### Handling Parsing Errors with onError

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/errors-logging.md

Example of how to implement the onError callback to log errors and potentially handle them. Ensure the file is ready before performing operations like seeking.

```typescript
const mp4file = createFile();

mp4file.onError = (module, message) => {
  console.error(`[${module}] ${message}`);
  // Handle error: show user message, retry, etc.
};

mp4file.appendBuffer(buffer);
```

--------------------------------

### Get Total Allocated Sample Data Size

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Returns the total number of bytes currently allocated for sample data in memory. Useful for monitoring memory usage.

```typescript
getAllocatedSampleDataSize(): number
```

--------------------------------

### Initialize a new MP4 file for creation

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Initializes a new MP4 file structure, preparing it for writing new content. Options can be provided to configure the creation process.

```typescript
init(options?: IsoFileOptions);
```

--------------------------------

### Get codec strings for all tracks

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Returns an array of codec strings for all tracks in the MP4 file, formatted according to RFC 6381. This is useful for constructing MIME types.

```typescript
const codecs = mp4file.getCodecs();
const mimeType = `video/mp4; codecs="${codecs.join(',')}"
```

--------------------------------

### Create MP4Box ISOFile Instance

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-create-file.md

Basic usage of createFile to create a new ISOFile instance for progressive parsing. Callbacks for ready state and errors should be set up before appending buffer data.

```typescript
import { createFile } from 'mp4box';

// Create a file for progressive parsing
const mp4file = createFile();

// Set up callbacks
mp4file.onReady = (info) => {
  console.log('File metadata loaded');
  console.log(`Tracks: ${info.tracks.length}`);
};

mp4file.onError = (module, message) => {
  console.error(`Error in ${module}: ${message}`);
};

// Append buffer data
const buffer = /* ArrayBuffer from fetch or file input */;
const mp4buffer = new MP4BoxBuffer(buffer.byteLength);
new Uint8Array(mp4buffer).set(new Uint8Array(buffer));
mp4buffer.fileStart = 0;

mp4file.appendBuffer(mp4buffer);
```

--------------------------------

### Initialize Segmentation

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Prepares segmentation and returns initialization segment(s) containing media headers. Use 'combined' mode for a single init segment or 'per-track' for separate segments per track.

```typescript
initializeSegmentation(mode?: 'combined'): SegmentationInitialization<TSegmentUser>;
initializeSegmentation(mode: 'per-track'): Array<SegmentationInitializationPerTrack<TSegmentUser>>;
```

```typescript
// Combined mode (single initialization segment)
const initSegs = mp4file.initializeSegmentation('combined');
console.log(`Tracks to segment: ${initSegs.tracks.map(t => t.id).join(',')}`);
sourceBuffer.appendBuffer(initSegs.buffer);

// Per-track mode (separate init per track)
const initSegs = mp4file.initializeSegmentation('per-track');
for (const initSeg of initSegs) {
  const sb = sourceBuffers[initSeg.id];
  sb.appendBuffer(initSeg.buffer);
}
```

--------------------------------

### Manage Position and Size in DataStream

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/advanced-topics.md

Demonstrates how to get the current position, set a specific position, and retrieve the total size of a DataStream. Updates the position after reading bytes.

```typescript
const stream = new DataStream(arrayBuffer);

console.log(stream.getPosition());      // Current position
stream.setPosition(100);                // Jump to position
console.log(stream.getSize());          // Total size
stream.readBytes(10);                   // Position now at 110
```

--------------------------------

### Build Internal Sample Information Tables

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Builds the internal sample information tables from the file's metadata. This is a preparatory step for sample management.

```typescript
buildSampleLists(): void
```

--------------------------------

### Setting Valid Segment Options

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/errors-logging.md

Example of setting segment options with valid parameters. Ensure that `nbSamples`, `nbSamplesPerFragment`, and `sizePerSegment` are greater than zero to avoid 'Invalid segment options' errors.

```typescript
mp4file.setSegmentOptions(trackId, user, {
  nbSamples: 1000,        // Must be > 0
  nbSamplesPerFragment: 1000,
  sizePerSegment: Number.MAX_SAFE_INTEGER,
  rapAlignement: true
});
```

--------------------------------

### Initialize MP4 Segmentation

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Sets up segmentation options for a track and initializes the segmentation process. The `onSegment` callback will be invoked when segments are ready. Ensure `MP4Box.createFile()` is called and `onReady` is handled.

```javascript
var mp4boxfile = MP4Box.createFile();
mp4boxfile.onReady = function(info) {
  ...
  mp4boxfile.onSegment = function (id, user, buffer, sampleNumber, last) {}
  mp4boxfile.setSegmentOptions(info.tracks[0].id, sb, options);
  var initSegs = mp4boxfile.initializeSegmentation();
  mp4boxfile.start();
  ...
```

--------------------------------

### Checking File Readiness Before Seeking

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/errors-logging.md

Demonstrates how to use the onReady callback to ensure the 'moov' box has been parsed before attempting to seek. This prevents 'Cannot seek: moov not received' errors.

```typescript
let canSeek = false;

mp4file.onReady = (info) => {
  canSeek = true;
};

function performSeek(time) {
  if (!canSeek) {
    console.error('Cannot seek: file not ready');
    return;
  }
  const seekInfo = mp4file.seek(time, false);
}
```

--------------------------------

### mp4box.js Architecture Overview

Source: https://github.com/gpac/mp4box.js/wiki/Home

Illustrates the data flow and component interactions within the mp4box.js library, from the application to the network layer.

```text
+===============+===========================================================+
| Application   |                                                           |
+===============+===========================================================+
| MP4Box.js API | append() / setExtractOptions() / flush() / ...            |
+===============+===========================================================+
| MP4Box.js     |                  ISOFile: API                             |
+               +=================+==============+==========================+
|               |    MPEG-4 'esd' |      Box     |  Sample                  |
|               |    Parsing      | read & write | management               |
+               +=================+==============+==========================+
|               |      DataView or DataStream or MultiByte Stream           |
+===============+===========================================================+
| Data          |                   ArrayBuffer                             |
+===============+===========================================================+
| Network       |                                                           |
| (controlled   |  Protocol independent: XHR, WebRTC DataChannel, File,     |
| by the        |                        Stream API                         |
| Application)  |                                                           |
+===============+===========================================================+
```

--------------------------------

### SampleEntryFourCC Type Alias

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/types.md

Represents valid sample entry format codes (4CC). Examples include 'avc1', 'hev1', 'vp09', 'av01' for video and 'mp4a', 'ac-3', 'ec-3', 'Opus' for audio.

```typescript
type SampleEntryFourCC = /* union of all registered sample entry 4CC codes */
```

--------------------------------

### ISOFile Constructor

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Initializes a new ISOFile instance. Optionally accepts a pre-existing stream and allows configuration to discard media data after parsing to conserve memory.

```typescript
constructor(stream?: MultiBufferStream, discardMdatData = true)
```

--------------------------------

### Add Video Track with Codec Type

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/configuration.md

Adds a video track, specifying the codec type using a FourCC code. This example uses 'avc1' for H.264 and also sets the video dimensions.

```typescript
mp4file.addTrack({
  type: 'avc1',  // H.264
  width: 1920,
  height: 1080
});
```

--------------------------------

### buildTrakSampleLists()

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Builds the sample list specifically for a given track within the MP4 file.

```APIDOC
## buildTrakSampleLists(trak: trakBox)

### Description
Builds sample list for a specific track.

### Method
`buildTrakSampleLists`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **trak** (trakBox) - Required - The track box object for which to build the sample list.

### Request Example
```typescript
const trak = mp4file.getTrackById(1);
if (trak) {
  mp4file.buildTrakSampleLists(trak);
}
```

### Response
#### Success Response (void)
This method does not return a value.
```

--------------------------------

### Key Methods by Category

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Categorizes and lists essential methods within the ISOFile class for various operations like information queries, buffer management, segmentation, extraction, seeking, and file creation.

```APIDOC
## Key Methods by Category

### Information Queries
- `getInfo()` - File metadata
- `getFragmentDuration()` - Fragment duration
- `getTrackById()` - Get specific track
- `getTrackSamplesInfo()` - Get all samples
- `getCodecs()` - Codec identification

### Buffer Management
- `appendBuffer()` - Add file data
- `checkBuffer()` - Validate buffer
- `flush()` - Process remaining data
- `getBuffer()` - Get entire file data

### Segmentation
- `setSegmentOptions()` - Enable segmentation
- `unsetSegmentOptions()` - Disable segmentation
- `initializeSegmentation()` - Generate init segment
- `start()` / `stop()` - Control processing

### Extraction
- `setExtractionOptions()` - Enable extraction
- `unsetExtractionOptions()` - Disable extraction
- `getTrackSample()` - Get specific sample
- `releaseUsedSamples()` - Free memory

### Seeking
- `seek()` - Seek to time
- `seekTrack()` - Seek within track

### File Creation
- `init()` - Initialize file
- `addTrack()` - Create track
- `addSample()` - Add sample data
- `createFragment()` - Create moof box
- `save()` / `getBuffer()` - Export file
```

--------------------------------

### Progressive Video Playback (MSE)

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/README.md

Demonstrates how to use MP4Box.js to create MP4 segments for Media Source Extensions (MSE) for progressive video playback.

```APIDOC
## Progressive Video Playback (MSE)

### Description
This example shows how to initialize MP4Box.js, set up segment options for a track, append initialization segments, and start streaming data for MSE playback.

### Method
```typescript
import { createFile, MP4BoxBuffer } from 'mp4box';

const mp4file = createFile();
const sourceBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.42c00d"');

mp4file.onReady = (info) => {
  mp4file.setSegmentOptions(info.tracks[0].id, sourceBuffer);
  const initSegs = mp4file.initializeSegmentation();
  sourceBuffer.appendBuffer(initSegs.buffer);
  mp4file.start();
};

mp4file.onSegment = (id, user, buffer) => {
  user.appendBuffer(buffer);
};

// Stream data...
```

### See Also
- [Quick Start Guide](./quick-start.md#progressive-download--mse-playback)
```

--------------------------------

### Import Full mp4box Library

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/INDEX.md

Import all necessary components from the main mp4box library. This includes functions for file creation, ISOFile class, MP4BoxBuffer, and logging utilities.

```typescript
import { createFile, ISOFile, MP4BoxBuffer, Log } from 'mp4box';
```

--------------------------------

### Get MP4 file information

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Use getInfo() to retrieve comprehensive details about the MP4 file, including duration, timescale, track metadata, and brands. This information is often used in the onReady callback.

```typescript
mp4file.onReady = (info) => {
  console.log(`File has ${info.tracks.length} tracks`);
  console.log(`Duration: ${info.duration / info.timescale} seconds`);
  
  for (const track of info.videoTracks) {
    console.log(`Video: ${track.video.width}x${track.video.height}`);
  }
};
```

--------------------------------

### Build Sample List for a Specific Track

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/api-reference-isofile.md

Builds the sample list specifically for a given track. Requires a trakBox object as input.

```typescript
buildTrakSampleLists(trak: trakBox): void
```

--------------------------------

### Manage MP4 Memory with Sample Release

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/quick-start.md

Demonstrates how to monitor allocated sample data size and release memory for processed samples and segments to prevent leaks.

```typescript
const mp4file = createFile();

mp4file.onReady = (info) => {
  // Only keep data if needed
  console.log('Sample data size:', mp4file.getAllocatedSampleDataSize(), 'bytes');
};

mp4file.onSamples = (id, user, samples) => {
  // Process samples...
  
  // Release memory after use
  const lastSample = samples[samples.length - 1];
  mp4file.releaseUsedSamples(id, lastSample.number + 1);
};

mp4file.onSegment = (id, user, buffer) => {
  // Process segment...
  
  // Release items if extracted
  for (let i = 1; i <= 100; i++) {
    mp4file.releaseItem(i);
  }
};
```

--------------------------------

### Configure Track Segmentation

Source: https://github.com/gpac/mp4box.js/blob/main/README.md

Configures segmentation options for a specific track. `nbSamples` defines frames per segment, `rapAlignement` ensures segments start with a RAP, and `normalizeAudioSampleEntriesForMSE` adjusts audio sample entries for MSE compatibility.

```javascript
mp4boxfile.setSegmentOptions(1, sb, { nbSamples: 1000 });
```

--------------------------------

### Import Simple mp4box for Parsing

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/INDEX.md

Import only the essential components for parsing MP4 files, which includes createFile and ISOFile. This is a lighter import for read-only operations.

```typescript
import { createFile, ISOFile } from 'mp4box/simple';
```

--------------------------------

### Track MP4 Parsing Progress

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/errors-logging.md

Monitor download progress and parsing status by implementing callbacks for metadata start, readiness, and errors. This snippet shows how to stream an MP4 file and log download percentages and parsing states.

```typescript
const mp4file = createFile();
let dataReceived = 0;
let parsingStarted = false;
let moovFound = false;

mp4file.onMoovStart = () => {
  parsingStarted = true;
  console.log('Parsing metadata... (moov started)');
};

mp4file.onReady = (info) => {
  moovFound = true;
  console.log(`Metadata ready: ${info.tracks.length} tracks, ${info.duration / info.timescale}s duration`);
};

mp4file.onError = (module, message) => {
  console.error(`Parse error: [${module}] ${message}`);
};

async function streamAndTrack(url) {
  const response = await fetch(url);
  const reader = response.body.getReader();
  const totalSize = parseInt(response.headers.get('content-length'), 10);
  
  let offset = 0;
  
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    dataReceived += value.length;
    const percent = ((dataReceived / totalSize) * 100).toFixed(1);
    console.log(`Downloaded: ${percent}% (${dataReceived}/${totalSize} bytes)`);
    
    const buffer = new MP4BoxBuffer(value.length);
    new Uint8Array(buffer).set(value);
    buffer.fileStart = offset;
    offset = mp4file.appendBuffer(buffer);
  }
  
  mp4file.flush();
  
  console.log('Stream complete');
  console.log(`Parsing: ${parsingStarted ? 'started' : 'not started'}`);
  console.log(`Metadata: ${moovFound ? 'found' : 'not found'}`);
}

streamAndTrack('video.mp4');
```

--------------------------------

### Example emsg Box Test Data

Source: https://github.com/gpac/mp4box.js/wiki/Writing-tests

This JSON object defines a test case for the DASH emsg box. It includes the URL for the box structure file, optional byte range for fetching, the box name, and the expected data properties for validation.

```json
{
  url: "./mp4/box/emsg.m4s",
  rangeStart: 106,
  rangeSize: 494,
  boxname: "emsg",
  data: {
    type: "emsg",
    size: 482,
    flags: 0,
    version: 0,
    scheme_id_uri: "urn:mpeg:dash:event:2012",
    value: "advert",
    timescale: 1,
    presentation_time_delta: 1,
    event_duration: 1,
    id: 1
  }
}
```

--------------------------------

### Minimal Video File Initialization

Source: https://github.com/gpac/mp4box.js/blob/main/_autodocs/configuration.md

Initializes an MP4 file with basic video track information. Use this for simple video files where only essential details are needed.

```typescript
const mp4file = createFile();

mp4file.init({
  brands: ['isom'],
  timescale: 1000,
  width: 1920,
  height: 1080
});

mp4file.addTrack({
  id: 1,
  type: 'avc1',
  width: 1920,
  height: 1080
});
```