mediabunny 1.0.2 → 1.0.4

package/src/custom-coder.ts

@@ -0,0 +1,162 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { AudioCodec, VideoCodec } from './codec';
+import { EncodedPacket } from './packet';
+import { AudioSample, VideoSample } from './sample';
+
+/**
+ * Base class for custom video decoders. To add your own custom video decoder, extend this class, implement the
+ * abstract methods and static `supports` method, and register the decoder using `registerDecoder`.
+ * @public
+ */
+export abstract class CustomVideoDecoder {
+	/** The input video's codec. */
+	readonly codec!: VideoCodec;
+	/** The input video's decoder config. */
+	readonly config!: VideoDecoderConfig;
+	/** The callback to call when a decoded VideoSample is available. */
+	readonly onSample!: (sample: VideoSample) => unknown;
+
+	/** Returns true iff the decoder can decode the given codec configuration. */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	static supports(codec: VideoCodec, config: VideoDecoderConfig): boolean {
+		return false;
+	}
+
+	/** Called after decoder creation; can be used for custom initialization logic. */
+	abstract init(): Promise<void> | void;
+	/** Decodes the provided encoded packet. */
+	abstract decode(packet: EncodedPacket): Promise<void> | void;
+	/** Decodes all remaining packets and then resolves. */
+	abstract flush(): Promise<void> | void;
+	/** Called when the decoder is no longer needed and its resources can be freed. */
+	abstract close(): Promise<void> | void;
+}
+
+/**
+ * Base class for custom audio decoders. To add your own custom audio decoder, extend this class, implement the
+ * abstract methods and static `supports` method, and register the decoder using `registerDecoder`.
+ * @public
+ */
+export abstract class CustomAudioDecoder {
+	/** The input audio's codec. */
+	readonly codec!: AudioCodec;
+	/** The input audio's decoder config. */
+	readonly config!: AudioDecoderConfig;
+	/** The callback to call when a decoded AudioSample is available. */
+	readonly onSample!: (sample: AudioSample) => unknown;
+
+	/** Returns true iff the decoder can decode the given codec configuration. */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	static supports(codec: AudioCodec, config: AudioDecoderConfig): boolean {
+		return false;
+	}
+
+	/** Called after decoder creation; can be used for custom initialization logic. */
+	abstract init(): Promise<void> | void;
+	/** Decodes the provided encoded packet. */
+	abstract decode(packet: EncodedPacket): Promise<void> | void;
+	/** Decodes all remaining packets and then resolves. */
+	abstract flush(): Promise<void> | void;
+	/** Called when the decoder is no longer needed and its resources can be freed. */
+	abstract close(): Promise<void> | void;
+}
+
+/**
+ * Base class for custom video encoders. To add your own custom video encoder, extend this class, implement the
+ * abstract methods and static `supports` method, and register the encoder using `registerEncoder`.
+ * @public
+ */
+export abstract class CustomVideoEncoder {
+	/** The codec with which to encode the video. */
+	readonly codec!: VideoCodec;
+	/** Config for the encoder. */
+	readonly config!: VideoEncoderConfig;
+	/** The callback to call when an EncodedPacket is available. */
+	readonly onPacket!: (packet: EncodedPacket, meta?: EncodedVideoChunkMetadata) => unknown;
+
+	/** Returns true iff the encoder can encode the given codec configuration. */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	static supports(codec: VideoCodec, config: VideoEncoderConfig): boolean {
+		return false;
+	}
+
+	/** Called after encoder creation; can be used for custom initialization logic. */
+	abstract init(): Promise<void> | void;
+	/** Encodes the provided video sample. */
+	abstract encode(videoSample: VideoSample, options: VideoEncoderEncodeOptions): Promise<void> | void;
+	/** Encodes all remaining video samples and then resolves. */
+	abstract flush(): Promise<void> | void;
+	/** Called when the encoder is no longer needed and its resources can be freed. */
+	abstract close(): Promise<void> | void;
+}
+
+/**
+ * Base class for custom audio encoders. To add your own custom audio encoder, extend this class, implement the
+ * abstract methods and static `supports` method, and register the encoder using `registerEncoder`.
+ * @public
+ */
+export abstract class CustomAudioEncoder {
+	/** The codec with which to encode the audio. */
+	readonly codec!: AudioCodec;
+	/** Config for the encoder. */
+	readonly config!: AudioEncoderConfig;
+	/** The callback to call when an EncodedPacket is available. */
+	readonly onPacket!: (packet: EncodedPacket, meta?: EncodedAudioChunkMetadata) => unknown;
+
+	/** Returns true iff the encoder can encode the given codec configuration. */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	static supports(codec: AudioCodec, config: AudioEncoderConfig): boolean {
+		return false;
+	}
+
+	/** Called after encoder creation; can be used for custom initialization logic. */
+	abstract init(): Promise<void> | void;
+	/** Encodes the provided audio sample. */
+	abstract encode(audioSample: AudioSample): Promise<void> | void;
+	/** Encodes all remaining audio samples and then resolves. */
+	abstract flush(): Promise<void> | void;
+	/** Called when the encoder is no longer needed and its resources can be freed. */
+	abstract close(): Promise<void> | void;
+}
+
+export const customVideoDecoders: typeof CustomVideoDecoder[] = [];
+export const customAudioDecoders: typeof CustomAudioDecoder[] = [];
+export const customVideoEncoders: typeof CustomVideoEncoder[] = [];
+export const customAudioEncoders: typeof CustomAudioEncoder[] = [];
+
+/**
+ * Registers a custom video or audio decoder. Registered decoders will automatically be used for decoding whenever
+ * possible.
+ * @public
+ */
+export const registerDecoder = (decoder: typeof CustomVideoDecoder | typeof CustomAudioDecoder) => {
+	if (decoder.prototype instanceof CustomVideoDecoder) {
+		customVideoDecoders.push(decoder as typeof CustomVideoDecoder);
+	} else if (decoder.prototype instanceof CustomAudioDecoder) {
+		customAudioDecoders.push(decoder as typeof CustomAudioDecoder);
+	} else {
+		throw new TypeError('Decoder must be a CustomVideoDecoder or CustomAudioDecoder.');
+	}
+};
+
+/**
+ * Registers a custom video or audio encoder. Registered encoders will automatically be used for encoding whenever
+ * possible.
+ * @public
+ */
+export const registerEncoder = (encoder: typeof CustomVideoEncoder | typeof CustomAudioEncoder) => {
+	if (encoder.prototype instanceof CustomVideoEncoder) {
+		customVideoEncoders.push(encoder as	typeof CustomVideoEncoder);
+	} else if (encoder.prototype instanceof CustomAudioEncoder) {
+		customAudioEncoders.push(encoder as typeof CustomAudioEncoder);
+	} else {
+		throw new TypeError('Encoder must be a CustomVideoEncoder or CustomAudioEncoder.');
+	}
+};

package/src/demuxer.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { Input } from './input';
+import { InputTrack } from './input-track';
+
+export abstract class Demuxer {
+	input: Input;
+
+	constructor(input: Input) {
+		this.input = input;
+	}
+
+	abstract computeDuration(): Promise<number>;
+	abstract getTracks(): Promise<InputTrack[]>;
+	abstract getMimeType(): Promise<string>;
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/// <reference types="dom-mediacapture-transform" preserve="true" />
+/// <reference types="dom-webcodecs" preserve="true" />
+
+export {
+	Output,
+	OutputOptions,
+	BaseTrackMetadata,
+	VideoTrackMetadata,
+	AudioTrackMetadata,
+	SubtitleTrackMetadata,
+	TrackType,
+	ALL_TRACK_TYPES,
+} from './output';
+export {
+	OutputFormat,
+	IsobmffOutputFormat,
+	Mp4OutputFormat,
+	MovOutputFormat,
+	IsobmffOutputFormatOptions,
+	MkvOutputFormat,
+	MkvOutputFormatOptions,
+	WebMOutputFormat,
+	WebMOutputFormatOptions,
+	Mp3OutputFormat,
+	Mp3OutputFormatOptions,
+	WavOutputFormat,
+	WavOutputFormatOptions,
+	OggOutputFormat,
+	OggOutputFormatOptions,
+	TrackCountLimits,
+	InclusiveIntegerRange,
+} from './output-format';
+export {
+	VideoEncodingConfig,
+	AudioEncodingConfig,
+	MediaSource,
+	VideoSource,
+	EncodedVideoPacketSource,
+	VideoSampleSource,
+	CanvasSource,
+	MediaStreamVideoTrackSource,
+	AudioSource,
+	EncodedAudioPacketSource,
+	AudioSampleSource,
+	AudioBufferSource,
+	MediaStreamAudioTrackSource,
+	SubtitleSource,
+	TextSubtitleSource,
+} from './media-source';
+export {
+	VIDEO_CODECS,
+	VideoCodec,
+	PCM_AUDIO_CODECS,
+	NON_PCM_AUDIO_CODECS,
+	AUDIO_CODECS,
+	AudioCodec,
+	SUBTITLE_CODECS,
+	SubtitleCodec,
+	MediaCodec,
+	Quality,
+	QUALITY_VERY_LOW,
+	QUALITY_LOW,
+	QUALITY_MEDIUM,
+	QUALITY_HIGH,
+	QUALITY_VERY_HIGH,
+	canEncode,
+	canEncodeVideo,
+	canEncodeAudio,
+	canEncodeSubtitles,
+	getEncodableCodecs,
+	getEncodableVideoCodecs,
+	getEncodableAudioCodecs,
+	getEncodableSubtitleCodecs,
+	getFirstEncodableVideoCodec,
+	getFirstEncodableAudioCodec,
+	getFirstEncodableSubtitleCodec,
+} from './codec';
+export { Target, BufferTarget, StreamTarget, StreamTargetChunk, StreamTargetOptions } from './target';
+export { Rotation, AnyIterable, SetRequired } from './misc';
+export {
+	Source,
+	BufferSource,
+	StreamSource,
+	StreamSourceOptions,
+	BlobSource,
+	UrlSource,
+	UrlSourceOptions,
+} from './source';
+export {
+	InputFormat,
+	IsobmffInputFormat,
+	Mp4InputFormat,
+	QuickTimeInputFormat,
+	MatroskaInputFormat,
+	WebMInputFormat,
+	Mp3InputFormat,
+	WaveInputFormat,
+	OggInputFormat,
+	ALL_FORMATS,
+	MP4,
+	QTFF,
+	MATROSKA,
+	WEBM,
+	MP3,
+	WAVE,
+	OGG,
+} from './input-format';
+export { Input, InputOptions } from './input';
+export { InputTrack, InputVideoTrack, InputAudioTrack, PacketStats } from './input-track';
+export { EncodedPacket, PacketType } from './packet';
+export {
+	VideoSample,
+	VideoSampleInit,
+	AudioSample,
+	AudioSampleInit,
+	AudioSampleCopyToOptions,
+} from './sample';
+export {
+	PacketRetrievalOptions,
+	EncodedPacketSink,
+	BaseMediaSampleSink,
+	VideoSampleSink,
+	CanvasSinkOptions,
+	CanvasSink,
+	WrappedCanvas,
+	AudioSampleSink,
+	AudioBufferSink,
+	WrappedAudioBuffer,
+} from './media-sink';
+export { ConversionOptions, Conversion } from './conversion';
+export {
+	CustomVideoDecoder,
+	CustomAudioDecoder,
+	CustomVideoEncoder,
+	CustomAudioEncoder,
+	registerDecoder,
+	registerEncoder,
+} from './custom-coder';
+
+// 🐡🦔

package/src/input-format.ts

@@ -0,0 +1,386 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { Demuxer } from './demuxer';
+import { Input } from './input';
+import { IsobmffDemuxer } from './isobmff/isobmff-demuxer';
+import { IsobmffReader } from './isobmff/isobmff-reader';
+import { EBMLId, EBMLReader } from './matroska/ebml';
+import { MatroskaDemuxer } from './matroska/matroska-demuxer';
+import { Mp3Demuxer } from './mp3/mp3-demuxer';
+import { Mp3Reader } from './mp3/mp3-reader';
+import { OggDemuxer } from './ogg/ogg-demuxer';
+import { OggReader } from './ogg/ogg-reader';
+import { RiffReader } from './wave/riff-reader';
+import { WaveDemuxer } from './wave/wave-demuxer';
+
+/**
+ * Base class representing an input media file format.
+ * @public
+ */
+export abstract class InputFormat {
+	/** @internal */
+	abstract _canReadInput(input: Input): Promise<boolean>;
+
+	/** @internal */
+	abstract _createDemuxer(input: Input): Demuxer;
+
+	/** Returns the name of the input format. */
+	abstract get name(): string;
+	/** Returns the typical base MIME type of the input format. */
+	abstract get mimeType(): string;
+}
+
+/**
+ * Format representing files compatible with the ISO base media file format (ISOBMFF), like MP4 or MOV files.
+ * @public
+ */
+export abstract class IsobmffInputFormat extends InputFormat {
+	/** @internal */
+	protected async _getMajorBrand(input: Input) {
+		const sourceSize = await input._mainReader.source.getSize();
+		if (sourceSize < 12) {
+			return null;
+		}
+
+		const isobmffReader = new IsobmffReader(input._mainReader);
+		isobmffReader.pos = 4;
+		const fourCc = isobmffReader.readAscii(4);
+
+		if (fourCc !== 'ftyp') {
+			return null;
+		}
+
+		return isobmffReader.readAscii(4);
+	}
+
+	/** @internal */
+	_createDemuxer(input: Input) {
+		return new IsobmffDemuxer(input);
+	}
+}
+
+/**
+ * MPEG-4 Part 14 (MP4) file format.
+ * @public
+ */
+export class Mp4InputFormat extends IsobmffInputFormat {
+	/** @internal */
+	async _canReadInput(input: Input) {
+		const majorBrand = await this._getMajorBrand(input);
+		return !!majorBrand && majorBrand !== 'qt  ';
+	}
+
+	get name() {
+		return 'MP4';
+	}
+
+	get mimeType() {
+		return 'video/mp4';
+	}
+}
+
+/**
+ * QuickTime File Format (QTFF), often called MOV.
+ * @public
+ */
+export class QuickTimeInputFormat extends IsobmffInputFormat {
+	/** @internal */
+	async _canReadInput(input: Input) {
+		const majorBrand = await this._getMajorBrand(input);
+		return majorBrand === 'qt  ';
+	}
+
+	get name() {
+		return 'QuickTime File Format';
+	}
+
+	get mimeType() {
+		return 'video/quicktime';
+	}
+}
+
+/**
+ * Matroska file format.
+ * @public
+ */
+export class MatroskaInputFormat extends InputFormat {
+	/** @internal */
+	protected async isSupportedEBMLOfDocType(input: Input, desiredDocType: string) {
+		const sourceSize = await input._mainReader.source.getSize();
+		if (sourceSize < 8) {
+			return false;
+		}
+
+		const ebmlReader = new EBMLReader(input._mainReader);
+		const varIntSize = ebmlReader.readVarIntSize();
+		if (varIntSize < 1 || varIntSize > 8) {
+			return false;
+		}
+
+		const id = ebmlReader.readUnsignedInt(varIntSize);
+		if (id !== EBMLId.EBML) {
+			return false;
+		}
+
+		const dataSize = ebmlReader.readElementSize();
+		if (dataSize === null) {
+			return false; // Miss me with that shit
+		}
+
+		const startPos = ebmlReader.pos;
+		while (ebmlReader.pos < startPos + dataSize) {
+			const { id, size } = ebmlReader.readElementHeader();
+			const dataStartPos = ebmlReader.pos;
+			if (size === null) return false;
+
+			switch (id) {
+				case EBMLId.EBMLVersion: {
+					const ebmlVersion = ebmlReader.readUnsignedInt(size);
+					if (ebmlVersion !== 1) {
+						return false;
+					}
+				}; break;
+				case EBMLId.EBMLReadVersion: {
+					const ebmlReadVersion = ebmlReader.readUnsignedInt(size);
+					if (ebmlReadVersion !== 1) {
+						return false;
+					}
+				}; break;
+				case EBMLId.DocType: {
+					const docType = ebmlReader.readString(size);
+					if (docType !== desiredDocType) {
+						return false;
+					}
+				}; break;
+				case EBMLId.DocTypeVersion: {
+					const docTypeVersion = ebmlReader.readUnsignedInt(size);
+					if (docTypeVersion > 4) { // Support up to Matroska v4
+						return false;
+					}
+				}; break;
+			}
+
+			ebmlReader.pos = dataStartPos + size;
+		}
+
+		return true;
+	}
+
+	/** @internal */
+	_canReadInput(input: Input) {
+		return this.isSupportedEBMLOfDocType(input, 'matroska');
+	}
+
+	/** @internal */
+	_createDemuxer(input: Input) {
+		return new MatroskaDemuxer(input);
+	}
+
+	get name() {
+		return 'Matroska';
+	}
+
+	get mimeType() {
+		return 'video/x-matroska';
+	}
+}
+
+/**
+ * WebM file format, based on Matroska.
+ * @public
+ */
+export class WebMInputFormat extends MatroskaInputFormat {
+	/** @internal */
+	override _canReadInput(input: Input) {
+		return this.isSupportedEBMLOfDocType(input, 'webm');
+	}
+
+	override get name() {
+		return 'WebM';
+	}
+
+	override get mimeType() {
+		return 'video/webm';
+	}
+}
+
+/**
+ * MP3 file format.
+ * @public
+ */
+export class Mp3InputFormat extends InputFormat {
+	/** @internal */
+	async _canReadInput(input: Input) {
+		const sourceSize = await input._mainReader.source.getSize();
+		if (sourceSize < 4) {
+			return false;
+		}
+
+		const mp3Reader = new Mp3Reader(input._mainReader);
+		mp3Reader.fileSize = sourceSize;
+
+		const id3Tag = mp3Reader.readId3();
+
+		if (id3Tag) {
+			mp3Reader.pos += id3Tag.size;
+		}
+
+		const framesStartPos = mp3Reader.pos;
+		await mp3Reader.reader.loadRange(mp3Reader.pos, mp3Reader.pos + 4096);
+
+		const firstHeader = mp3Reader.readNextFrameHeader(Math.min(framesStartPos + 4096, sourceSize));
+		if (!firstHeader) {
+			return false;
+		}
+
+		if (id3Tag) {
+			// If there was an ID3 tag at the start, we can be pretty sure this is MP3 by now
+			return true;
+		}
+
+		// Fine, we found one frame header, but we're still not entirely sure this is MP3. Let's check if we can find
+		// another header nearby:
+		mp3Reader.pos = firstHeader.startPos + firstHeader.totalSize;
+		const secondHeader = mp3Reader.readNextFrameHeader(Math.min(framesStartPos + 4096, sourceSize));
+		if (!secondHeader) {
+			return false;
+		}
+
+		// In a well-formed MP3 file, we'd expect these two frames to share some similarities:
+		if (firstHeader.channel !== secondHeader.channel || firstHeader.sampleRate !== secondHeader.sampleRate) {
+			return false;
+		}
+
+		// We have found two matching MP3 frames, a strong indicator that this is an MP3 file
+		return true;
+	}
+
+	/** @internal */
+	_createDemuxer(input: Input) {
+		return new Mp3Demuxer(input);
+	}
+
+	get name() {
+		return 'MP3';
+	}
+
+	get mimeType() {
+		return 'audio/mpeg';
+	}
+}
+
+/**
+ * WAVE file format, based on RIFF.
+ * @public
+ */
+export class WaveInputFormat extends InputFormat {
+	/** @internal */
+	async _canReadInput(input: Input) {
+		const sourceSize = await input._mainReader.source.getSize();
+		if (sourceSize < 12) {
+			return false;
+		}
+
+		const riffReader = new RiffReader(input._mainReader);
+		const riffType = riffReader.readAscii(4);
+		if (riffType !== 'RIFF' && riffType !== 'RIFX') {
+			return false;
+		}
+
+		riffReader.pos = 8;
+		const format = riffReader.readAscii(4);
+		return format === 'WAVE';
+	}
+
+	/** @internal */
+	_createDemuxer(input: Input) {
+		return new WaveDemuxer(input);
+	}
+
+	get name() {
+		return 'WAVE';
+	}
+
+	get mimeType() {
+		return 'audio/wav';
+	}
+}
+
+/**
+ * Ogg file format.
+ * @public
+ */
+export class OggInputFormat extends InputFormat {
+	/** @internal */
+	async _canReadInput(input: Input) {
+		const sourceSize = await input._mainReader.source.getSize();
+		if (sourceSize < 4) {
+			return false;
+		}
+
+		const oggReader = new OggReader(input._mainReader);
+		return oggReader.readAscii(4) === 'OggS';
+	}
+
+	/** @internal */
+	_createDemuxer(input: Input) {
+		return new OggDemuxer(input);
+	}
+
+	get name() {
+		return 'Ogg';
+	}
+
+	get mimeType() {
+		return 'application/ogg';
+	}
+}
+
+/**
+ * MP4 input format singleton.
+ * @public
+ */
+export const MP4 = new Mp4InputFormat();
+/**
+ * QuickTime File Format input format singleton.
+ * @public
+ */
+export const QTFF = new QuickTimeInputFormat();
+/**
+ * Matroska input format singleton.
+ * @public
+ */
+export const MATROSKA = new MatroskaInputFormat();
+/**
+ * WebM input format singleton.
+ * @public
+ */
+export const WEBM = new WebMInputFormat();
+/**
+ * MP3 input format singleton.
+ * @public
+ */
+export const MP3 = new Mp3InputFormat();
+/**
+ * WAVE input format singleton.
+ * @public
+ */
+export const WAVE = new WaveInputFormat();
+/**
+ * Ogg input format singleton.
+ * @public
+ */
+export const OGG = new OggInputFormat();
+
+/**
+ * List of all input format singletons. If you don't need to support all input formats, you should specify the
+ * formats individually for better tree shaking.
+ * @public
+ */
+export const ALL_FORMATS: InputFormat[] = [MP4, QTFF, MATROSKA, WEBM, WAVE, OGG, MP3];