mirror of
https://github.com/arcodange-org/mediabunny.git
synced 2026-09-27 19:03:46 +02:00
Add documentation on writing files
This commit is contained in:
Vanilagy
@@ -0,0 +1,225 @@
|
||||
# Output formats
|
||||
|
||||
## Introduction
|
||||
|
||||
An _output format_ specifies the container format of the data written by an `Output`. Mediakit supports many commonly used container formats, each having format-specific options.
|
||||
|
||||
Many formats also offer *data callbacks*, which are special callbacks that fire for specific data regions in the output file.
|
||||
|
||||
### Format properties
|
||||
|
||||
All output formats have a common set of properties you can query.
|
||||
|
||||
```ts
|
||||
// Get the format's file extension:
|
||||
format.fileExtension; // => '.mp4'
|
||||
|
||||
// Check which codecs can be contained by the format:
|
||||
format.getSupportedCodecs(); // => MediaCodec[]
|
||||
format.getSupportedVideoCodecs(); // => VideoCodec[]
|
||||
format.getSupportedAudioCodecs(); // => AudioCodec[]
|
||||
format.getSupportedSubtitleCodecs(); // => SubtitleCodec[]
|
||||
|
||||
// Check if the format supports video tracks with rotation metadata:
|
||||
format.supportsVideoRotationMetadata; // => boolean
|
||||
```
|
||||
|
||||
Refer to the [compatibility table](./supported-formats-and-codecs.md#compatibility-table) to see which codecs can be used with which output format.
|
||||
|
||||
Formats also differ in the amount and types of tracks they can contain. You can retrieve this information using:
|
||||
```ts
|
||||
format.getSupportedTrackCounts(); // => TrackCountLimits
|
||||
|
||||
type TrackCountLimits = {
|
||||
video: { min: number, max: number },
|
||||
audio: { min: number, max: number },
|
||||
subtitle: { min: number, max: number },
|
||||
total: { min: number, max: number },
|
||||
};
|
||||
```
|
||||
|
||||
## MP4
|
||||
|
||||
This output format creates MP4 files.
|
||||
```ts
|
||||
import { Output, Mp4OutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new Mp4OutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
```ts
|
||||
type IsobmffOutputFormatOptions = {
|
||||
fastStart?: false | 'in-memory' | 'fragmented';
|
||||
minimumFragmentDuration?: number;
|
||||
|
||||
onFtyp?: (data: Uint8Array, position: number) => unknown;
|
||||
onMoov?: (data: Uint8Array, position: number) => unknown;
|
||||
onMdat?: (data: Uint8Array, position: number) => unknown;
|
||||
onMoof?: (data: Uint8Array, position: number, timestamp: number) => unknown;
|
||||
};
|
||||
```
|
||||
- `fastStart`\
|
||||
Controls the placement of metadata in the file. Placing metadata at the start of the file is known as "Fast Start" and provides certain benefits: The file becomes easier to stream over the web without range requests, and sites like YouTube can start processing the video while it's uploading. However, placing metadata at the start of the file can require more processing and memory in the writing step. This library provides full control over the placement of metadata by setting `fastStart` to one of these options:
|
||||
- `false`\
|
||||
Disables Fast Start, placing the metadata at the end of the file. Fastest and uses the least memory.
|
||||
- `'in-memory'`\
|
||||
Produces a file with Fast Start by keeping all media chunks in memory until the file is finalized. This produces a high-quality and compact output at the cost of a more expensive finalization step and higher memory requirements.
|
||||
::: info
|
||||
This option ensures append-only writing.
|
||||
:::
|
||||
- `'fragmented'`\
|
||||
Produces a _fragmented MP4 (fMP4)_ file, evenly placing sample metadata throughout the file by grouping it into "fragments" (short sections of media), while placing general metadata at the beginning of the file. Fragmented files are ideal in streaming contexts, as each fragment can be played individually without requiring knowledge of the other fragments. Furthermore, they remain lightweight to create no matter how large the file becomes, as they don't require media to be kept in memory for very long. However, fragmented files are not as widely and wholly supported as regular MP4 files, and some players don't provide seeking functionality for them.
|
||||
::: info
|
||||
This option ensures append-only writing.
|
||||
:::
|
||||
::: warning
|
||||
This option requires [packet buffering](./writing-overview#packet-buffering).
|
||||
:::
|
||||
- `undefined`\
|
||||
The default option; it behaves like `'in-memory'` when using [`BufferTarget`](./writing-overview#buffertarget) and like `false` otherwise.
|
||||
- `minimumFragmentDuration`\
|
||||
Only relevant when `fastStart` is `'fragmented'`. Sets the minimum duration in seconds a fragment must have to be finalized and written to the file. Defaults to 1 second.
|
||||
- `onFtyp`\
|
||||
Will be called once the ftyp (File Type) box of the output file has been written.
|
||||
- `onMoov`\
|
||||
Will be called once the moov (Movie) box of the output file has been written.
|
||||
- `onMdat`\
|
||||
Will be called for each finalized mdat (Media Data) box of the output file. Usage of this callback is not recommended when not using `fastStart: 'fragmented'`, as there will be one monolithic mdat box which might require large amounts of memory.
|
||||
- `onMoof`\
|
||||
Will be called for each finalized moof (Movie Fragment) box of the output file. The fragment's start timestamp in seconds is also passed.
|
||||
|
||||
## QuickTime File Format (.mov)
|
||||
|
||||
This output format creates QuickTime files (.mov).
|
||||
```ts
|
||||
import { Output, MovOutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new MovOutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The available options are the same `IsobmffOutputFormatOptions` used by [MP4](#mp4).
|
||||
|
||||
## WebM
|
||||
|
||||
This output format creates WebM files.
|
||||
```ts
|
||||
import { Output, WebmOutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new WebmOutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
```ts
|
||||
type MkvOutputFormatOptions = {
|
||||
streamable?: boolean;
|
||||
minimumClusterDuration?: number;
|
||||
|
||||
onEbmlHeader?: (data: Uint8Array, position: number) => void;
|
||||
onSegmentHeader?: (data: Uint8Array, position: number) => unknown;
|
||||
onCluster?: (data: Uint8Array, position: number, timestamp: number) => unknown;
|
||||
};
|
||||
```
|
||||
- `streamable`\
|
||||
Configures the output to write data in an append-only fashion. This is useful for live-streaming the output as it's being created. Note that when enabled, certain features like file duration or seeking will be disabled or impacted, so don't use this option when you want to write out a media file for later use.
|
||||
::: info
|
||||
This option ensures append-only writing.
|
||||
:::
|
||||
- `minimumClusterDuration`\
|
||||
Sets the minimum duration in seconds a cluster must have to be finalized and written to the file. Defaults to 1 second.
|
||||
- `onEbmlHeader`\
|
||||
Will be called once the EBML header of the output file has been written.
|
||||
- `onSegmentHeader`\
|
||||
Will be called once the header part of the Matroska Segment element has been written. The header data includes the Segment element and everything inside it, up to (but excluding) the first Matroska Cluster.
|
||||
- `onCluster`\
|
||||
Will be called for each finalized Matroska Cluster of the output file. The cluster's start timestamp in seconds is also passed.
|
||||
|
||||
## Matroska (.mkv)
|
||||
|
||||
This output format creates Matroska files (.mkv).
|
||||
```ts
|
||||
import { Output, MkvOutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new MkvOutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The available options are the same `MkvOutputFormatOptions` used by [WebM](#webm).
|
||||
|
||||
## Ogg
|
||||
|
||||
This output format creates Ogg files.
|
||||
```ts
|
||||
import { Output, OggOutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new OggOutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
::: info
|
||||
This format ensures append-only writing.
|
||||
:::
|
||||
|
||||
The following options are available:
|
||||
```ts
|
||||
type OggOutputFormatOptions = {
|
||||
onPage?: (data: Uint8Array, position: number, source: MediaSource) => unknown;
|
||||
};
|
||||
```
|
||||
- `onPage`\
|
||||
Will be called for each finalized Ogg page of the output file. The [media source](./media-sources) backing the page's track (logical bitstream) is also passed.
|
||||
|
||||
## MP3
|
||||
|
||||
This output format creates MP3 files.
|
||||
```ts
|
||||
import { Output, Mp3OutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new Mp3OutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
```ts
|
||||
type Mp3OutputFormatOptions = {
|
||||
onXingFrame?: (data: Uint8Array, position: number) => unknown;
|
||||
};
|
||||
```
|
||||
- `onXingFrame`\
|
||||
Will be called once the Xing metadata frame is finalized, which happens at the end of the writing process.
|
||||
|
||||
## WAVE
|
||||
|
||||
This output format creates WAVE (.wav) files.
|
||||
```ts
|
||||
import { Output, WavOutputFormat } from 'mediakit';
|
||||
|
||||
const output = new Output({
|
||||
format: new WavOutputFormat(options),
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
```ts
|
||||
type WavOutputFormatOptions = {
|
||||
onHeader?: (data: Uint8Array, position: number) => unknown;
|
||||
};
|
||||
```
|
||||
- `onHeader`\
|
||||
Will be called once the file header is written. The header consists of the RIFF header, the format chunk, and the start of the data chunk (with a placeholder size of 0).
|
||||
Reference in New Issue
Block a user