arcodange/mediabunny
1
0
Fork 0
mirror of https://github.com/arcodange-org/mediabunny.git synced 2026-09-29 11:53:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation comments everywhere

Browse Source
This commit is contained in:
David Payr
2025-03-15 17:12:42 +01:00
parent 6eb5c02591
commit 3863ffe4d8
30 changed files with 1607 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/output-format.ts
+101 -19
View File
@@ -17,37 +17,60 @@ import { OggMuxer } from './ogg/ogg-muxer';
import { Output, TrackType } from './output';
import { WaveMuxer } from './wave/wave-muxer';
/** @public */
export type InclusiveRange = { min: number; max: number };
/** @public */
export type TrackCountLimits = {
[K in TrackType]: InclusiveRange;
} & {
total: InclusiveRange;
/**
* Specifies an inclusive range of integers.
* @public
*/
export type InclusiveIntegerRange = {
/** The integer cannot be less than this. */
min: number;
/** The integer cannot be greater than this. */
max: number;
};
/** @public */
/**
* Specifies the number of tracks (for each track type and in total) that an output format supports.
* @public
*/
export type TrackCountLimits = {
[K in TrackType]: InclusiveIntegerRange;
} & {
/** Specifies the overall allowed range of track counts for the output format. */
total: InclusiveIntegerRange;
};
/**
* Base class representing an output media file format.
* @public
*/
export abstract class OutputFormat {
/** @internal */
abstract _createMuxer(output: Output): Muxer;
/** @internal */
abstract get _name(): string;
/** The file extension used by this output format, beginning with a dot. */
abstract get fileExtension(): string;
/** Returns a list of media codecs that this output format can contain. */
abstract getSupportedCodecs(): MediaCodec[];
/** Returns the number of tracks that this output format supports. */
abstract getSupportedTrackCounts(): TrackCountLimits;
/** Whether this output format supports video rotation metadata. */
abstract get supportsVideoRotationMetadata(): boolean;
/** Returns a list of video codecs that this output format can contain. */
getSupportedVideoCodecs() {
return this.getSupportedCodecs()
.filter(codec => (VIDEO_CODECS as readonly string[]).includes(codec)) as VideoCodec[];
}
/** Returns a list of audio codecs that this output format can contain. */
getSupportedAudioCodecs() {
return this.getSupportedCodecs()
.filter(codec => (AUDIO_CODECS as readonly string[]).includes(codec)) as AudioCodec[];
}
/** Returns a list of subtitle codecs that this output format can contain. */
getSupportedSubtitleCodecs() {
return this.getSupportedCodecs()
.filter(codec => (SUBTITLE_CODECS as readonly string[]).includes(codec)) as SubtitleCodec[];
@@ -60,12 +83,39 @@ export abstract class OutputFormat {
}
}
/** @public */
/**
* Options controlling the format of an output ISOBMFF file.
* @public
*/
export type IsobmffOutputFormatOptions = {
/**
* Controls the placement of metadata in the file. Placing metadata at the start of the file is known as "Fast
* Start", which results in better playback at the cost of more required processing or memory.
*
* Use `false` to disable Fast Start, placing the metadata at the end of the file. Fastest and uses the least
* memory.
*
* Use `'in-memory'` to produce 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. Data will be written monotonically (in order) when this option is set.
*
* Use `'fragmented'` to place metadata at the start of the file by creating a fragmented file. In a
* fragmented file, chunks of media and their metadata are written to the file in "fragments", eliminating the need
* to put all metadata in one place. Fragmented files are useful for streaming, as they allow for better random
* access. Furthermore, they remain lightweight to create even for very large files, as they don't require all media
* to be kept in memory. However, fragmented files are not as widely and wholly supported as regular MP4/MOV files.
* Data will be written monotonically (in order) when this option is set.
*
* When this field is not defined, either `false` or `'in-memory'` will be used, automatically determined based on
* the type of output target used.
*/
fastStart?: false | 'in-memory' | 'fragmented';
};
/** @public */
/**
* Format representing files compatible with the ISO base media file format (ISOBMFF), like MP4 or MOV files.
* @public
*/
export abstract class IsobmffOutputFormat extends OutputFormat {
/** @internal */
_options: IsobmffOutputFormatOptions;
@@ -102,7 +152,10 @@ export abstract class IsobmffOutputFormat extends OutputFormat {
}
}
/** @public */
/**
* MPEG-4 Part 14 (MP4) file format. Supports all codecs except PCM audio codecs.
* @public
*/
export class Mp4OutputFormat extends IsobmffOutputFormat {
/** @internal */
get _name() {
@@ -131,7 +184,10 @@ export class Mp4OutputFormat extends IsobmffOutputFormat {
}
}
/** @public */
/**
* QuickTime File Format (QTFF), often called MOV. Supports all video and audio codecs, but not subtitle codecs.
* @public
*/
export class MovOutputFormat extends IsobmffOutputFormat {
/** @internal */
get _name() {
@@ -159,12 +215,23 @@ export class MovOutputFormat extends IsobmffOutputFormat {
}
}
/** @public */
/**
* Options controlling the format of an output Matroska file.
* @public
*/
export type MkvOutputFormatOptions = {
/**
* Configures the output to only write data monotonically, useful for live-streaming the file as it's being muxed.
* When enabled, some features such as storing duration and seeking will be disabled or impacted, so don't use this
* option when you want to write out a file for later use.
*/
streamable?: boolean;
};
/** @public */
/**
* Matroska file format.
* @public
*/
export class MkvOutputFormat extends OutputFormat {
/** @internal */
_options: MkvOutputFormatOptions;
@@ -220,10 +287,16 @@ export class MkvOutputFormat extends OutputFormat {
}
}
/** @public */
/**
* Options controlling the format of an output WebM file.
* @public
*/
export type WebMOutputFormatOptions = MkvOutputFormatOptions;
/** @public */
/**
* WebM file format, based on Matroska.
* @public
*/
export class WebMOutputFormat extends MkvOutputFormat {
override getSupportedCodecs(): MediaCodec[] {
return [
@@ -252,7 +325,10 @@ export class WebMOutputFormat extends MkvOutputFormat {
}
}
/** @public */
/**
* MP3 file format.
* @public
*/
export class Mp3OutputFormat extends OutputFormat {
/** @internal */
_createMuxer(output: Output) {
@@ -286,7 +362,10 @@ export class Mp3OutputFormat extends OutputFormat {
}
}
/** @public */
/**
* WAVE file format, based on RIFF.
* @public
*/
export class WaveOutputFormat extends OutputFormat {
/** @internal */
_createMuxer(output: Output) {
@@ -324,7 +403,10 @@ export class WaveOutputFormat extends OutputFormat {
}
}
/** @public */
/**
* Ogg file format.
* @public
*/
export class OggOutputFormat extends OutputFormat {
/** @internal */
_createMuxer(output: Output) {