mediabunny 1.0.2 → 1.0.4

package/src/input-track.ts

@@ -0,0 +1,341 @@
+/*!
+ * 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, MediaCodec, VideoCodec } from './codec';
+import { customAudioDecoders, customVideoDecoders } from './custom-coder';
+import { EncodedPacketSink, PacketRetrievalOptions } from './media-sink';
+import { assert, Rotation } from './misc';
+import { TrackType } from './output';
+import { EncodedPacket } from './packet';
+
+/**
+ * Contains aggregate statistics about the encoded packets of a track.
+ * @public
+ */
+export type PacketStats = {
+	/** The total number of packets. */
+	packetCount: number;
+	/** The average number of packets per second. For video tracks, this will equal the average frame rate (FPS). */
+	averagePacketRate: number;
+	/** The average number of bits per second. */
+	averageBitrate: number;
+};
+
+export interface InputTrackBacking {
+	getId(): number;
+	getCodec(): MediaCodec | null;
+	getLanguageCode(): string;
+	getTimeResolution(): number;
+	getFirstTimestamp(): Promise<number>;
+	computeDuration(): Promise<number>;
+
+	getFirstPacket(options: PacketRetrievalOptions): Promise<EncodedPacket | null>;
+	getPacket(timestamp: number, options: PacketRetrievalOptions): Promise<EncodedPacket | null>;
+	getNextPacket(packet: EncodedPacket, options: PacketRetrievalOptions): Promise<EncodedPacket | null>;
+	getKeyPacket(timestamp: number, options: PacketRetrievalOptions): Promise<EncodedPacket | null>;
+	getNextKeyPacket(packet: EncodedPacket, options: PacketRetrievalOptions): Promise<EncodedPacket | null>;
+}
+
+/**
+ * Represents a media track in an input file.
+ * @public
+ */
+export abstract class InputTrack {
+	/** @internal */
+	_backing: InputTrackBacking;
+
+	/** @internal */
+	constructor(backing: InputTrackBacking) {
+		this._backing = backing;
+	}
+
+	/** The type of the track. */
+	abstract get type(): TrackType;
+	/** The codec of the track's packets. */
+	abstract get codec(): MediaCodec | null;
+	/** Returns the full codec parameter string for this track. */
+	abstract getCodecParameterString(): Promise<string | null>;
+	/** Checks if this track's packets can be decoded by the browser. */
+	abstract canDecode(): Promise<boolean>;
+
+	/** Returns true iff this track is a video track. */
+	isVideoTrack(): this is InputVideoTrack {
+		return this instanceof InputVideoTrack;
+	}
+
+	/** Returns true iff this track is an audio track. */
+	isAudioTrack(): this is InputAudioTrack {
+		return this instanceof InputAudioTrack;
+	}
+
+	/** The unique ID of this track in the input file. */
+	get id() {
+		return this._backing.getId();
+	}
+
+	/** The ISO 639-2/T language code for this track. If the language is unknown, this field is 'und' (undetermined). */
+	get languageCode() {
+		return this._backing.getLanguageCode();
+	}
+
+	/**
+	 * A positive number x such that all timestamps and durations of all packets of this track are
+	 * integer multiples of 1/x.
+	 */
+	get timeResolution() {
+		return this._backing.getTimeResolution();
+	}
+
+	/**
+	 * Returns the start timestamp of the first packet of this track, in seconds. While often near zero, this value
+	 * may be positive or even negative. A negative starting timestamp means the track's timing has been offset. Samples
+	 * with a negative timestamp should not be presented.
+	 */
+	getFirstTimestamp() {
+		return this._backing.getFirstTimestamp();
+	}
+
+	/** Returns the end timestamp of the last packet of this track, in seconds. */
+	computeDuration() {
+		return this._backing.computeDuration();
+	}
+
+	/**
+	 * Computes aggregate packet statistics for this track, such as average packet rate or bitrate.
+	 *
+	 * @param targetPacketCount - This optional parameter sets a target for how many packets this method must have
+	 * looked at before it can return early; this means, you can use it to aggregate only a subset (prefix) of all
+	 * packets. This is very useful for getting a great estimate of video frame rate without having to scan through the
+	 * entire file.
+	 */
+	async computePacketStats(targetPacketCount = Infinity): Promise<PacketStats> {
+		const sink = new EncodedPacketSink(this);
+
+		let startTimestamp = Infinity;
+		let endTimestamp = -Infinity;
+		let packetCount = 0;
+		let totalPacketBytes = 0;
+
+		for await (const packet of sink.packets(undefined, undefined, { metadataOnly: true })) {
+			if (
+				packetCount >= targetPacketCount
+				// This additional condition is needed to produce correct results with out-of-presentation-order packets
+				&& packet.timestamp >= endTimestamp
+			) {
+				break;
+			}
+
+			startTimestamp = Math.min(startTimestamp, packet.timestamp);
+			endTimestamp = Math.max(endTimestamp, packet.timestamp + packet.duration);
+
+			packetCount++;
+			totalPacketBytes += packet.byteLength;
+		}
+
+		return {
+			packetCount,
+			averagePacketRate: packetCount
+				? Number((packetCount / (endTimestamp - startTimestamp)).toPrecision(16))
+				: 0,
+			averageBitrate: packetCount
+				? Number((8 * totalPacketBytes / (endTimestamp - startTimestamp)).toPrecision(16))
+				: 0,
+		};
+	}
+}
+
+export interface InputVideoTrackBacking extends InputTrackBacking {
+	getCodec(): VideoCodec | null;
+	getCodedWidth(): number;
+	getCodedHeight(): number;
+	getRotation(): Rotation;
+	getColorSpace(): Promise<VideoColorSpaceInit>;
+	getDecoderConfig(): Promise<VideoDecoderConfig | null>;
+}
+
+/**
+ * Represents a video track in an input file.
+ * @public
+ */
+export class InputVideoTrack extends InputTrack {
+	/** @internal */
+	override _backing: InputVideoTrackBacking;
+
+	/** @internal */
+	constructor(backing: InputVideoTrackBacking) {
+		super(backing);
+
+		this._backing = backing;
+	}
+
+	get type(): TrackType {
+		return 'video';
+	}
+
+	get codec() {
+		return this._backing.getCodec();
+	}
+
+	/** The width in pixels of the track's coded samples, before any transformations or rotations. */
+	get codedWidth() {
+		return this._backing.getCodedWidth();
+	}
+
+	/** The height in pixels of the track's coded samples, before any transformations or rotations. */
+	get codedHeight() {
+		return this._backing.getCodedHeight();
+	}
+
+	/** The angle in degrees by which the track's frames should be rotated (clockwise). */
+	get rotation() {
+		return this._backing.getRotation();
+	}
+
+	/** The width in pixels of the track's frames after rotation. */
+	get displayWidth() {
+		const rotation = this._backing.getRotation();
+		return rotation % 180 === 0 ? this._backing.getCodedWidth() : this._backing.getCodedHeight();
+	}
+
+	/** The height in pixels of the track's frames after rotation. */
+	get displayHeight() {
+		const rotation = this._backing.getRotation();
+		return rotation % 180 === 0 ? this._backing.getCodedHeight() : this._backing.getCodedWidth();
+	}
+
+	/** Returns the color space of the track's samples. */
+	getColorSpace() {
+		return this._backing.getColorSpace();
+	}
+
+	/** If this method returns true, the track's samples use a high dynamic range (HDR). */
+	async hasHighDynamicRange() {
+		const colorSpace = await this._backing.getColorSpace();
+
+		return (colorSpace.primaries as string) === 'bt2020' || (colorSpace.primaries as string) === 'smpte432'
+			|| (colorSpace.transfer as string) === 'pg' || (colorSpace.transfer as string) === 'hlg'
+			|| (colorSpace.matrix as string) === 'bt2020-ncl';
+	}
+
+	/** Returns the decoder configuration for decoding the track's packets using a VideoDecoder. */
+	getDecoderConfig() {
+		return this._backing.getDecoderConfig();
+	}
+
+	async getCodecParameterString() {
+		const decoderConfig = await this._backing.getDecoderConfig();
+		return decoderConfig?.codec ?? null;
+	}
+
+	async canDecode() {
+		try {
+			const decoderConfig = await this._backing.getDecoderConfig();
+			if (!decoderConfig) {
+				return false;
+			}
+
+			const codec = this._backing.getCodec();
+			assert(codec !== null);
+
+			if (customVideoDecoders.some(x => x.supports(codec, decoderConfig))) {
+				return true;
+			}
+
+			if (typeof VideoDecoder === 'undefined') {
+				return false;
+			}
+
+			const support = await VideoDecoder.isConfigSupported(decoderConfig);
+			return support.supported === true;
+		} catch (error) {
+			console.error('Error during decodability check:', error);
+			return false;
+		}
+	}
+}
+
+export interface InputAudioTrackBacking extends InputTrackBacking {
+	getCodec(): AudioCodec | null;
+	getNumberOfChannels(): number;
+	getSampleRate(): number;
+	getDecoderConfig(): Promise<AudioDecoderConfig | null>;
+}
+
+/**
+ * Represents an audio track in an input file.
+ * @public
+ */
+export class InputAudioTrack extends InputTrack {
+	/** @internal */
+	override _backing: InputAudioTrackBacking;
+
+	/** @internal */
+	constructor(backing: InputAudioTrackBacking) {
+		super(backing);
+
+		this._backing = backing;
+	}
+
+	get type(): TrackType {
+		return 'audio';
+	}
+
+	get codec(): AudioCodec | null {
+		return this._backing.getCodec();
+	}
+
+	/** The number of audio channels in the track. */
+	get numberOfChannels() {
+		return this._backing.getNumberOfChannels();
+	}
+
+	/** The track's audio sample rate in hertz. */
+	get sampleRate() {
+		return this._backing.getSampleRate();
+	}
+
+	/** Returns the decoder configuration for decoding the track's packets using an AudioDecoder. */
+	getDecoderConfig() {
+		return this._backing.getDecoderConfig();
+	}
+
+	async getCodecParameterString() {
+		const decoderConfig = await this._backing.getDecoderConfig();
+		return decoderConfig?.codec ?? null;
+	}
+
+	async canDecode() {
+		try {
+			const decoderConfig = await this._backing.getDecoderConfig();
+			if (!decoderConfig) {
+				return false;
+			}
+
+			const codec = this._backing.getCodec();
+			assert(codec !== null);
+
+			if (customAudioDecoders.some(x => x.supports(codec, decoderConfig))) {
+				return true;
+			}
+
+			if (decoderConfig.codec.startsWith('pcm-')) {
+				return true; // Since we decode it ourselves
+			} else {
+				if (typeof AudioDecoder === 'undefined') {
+					return false;
+				}
+
+				const support = await AudioDecoder.isConfigSupported(decoderConfig);
+				return support.supported === true;
+			}
+		} catch (error) {
+			console.error('Error during decodability check:', error);
+			return false;
+		}
+	}
+}

package/src/input.ts

@@ -0,0 +1,138 @@
+/*!
+ * 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 { InputFormat } from './input-format';
+import { assert } from './misc';
+import { Reader } from './reader';
+import { Source } from './source';
+
+/**
+ * The options for creating an Input object.
+ * @public
+ */
+export type InputOptions<S extends Source = Source> = {
+	/** A list of supported formats. If the source file is not of one of these formats, then it cannot be read. */
+	formats: InputFormat[];
+	/** The source from which data will be read. */
+	source: S;
+};
+
+/**
+ * Represents an input media file. This is the root object from which all media read operations start.
+ * @public
+ */
+export class Input<S extends Source = Source> {
+	/** @internal */
+	_source: S;
+	/** @internal */
+	_formats: InputFormat[];
+	/** @internal */
+	_mainReader: Reader;
+	/** @internal */
+	_demuxerPromise: Promise<Demuxer> | null = null;
+	/** @internal */
+	_format: InputFormat | null = null;
+
+	constructor(options: InputOptions<S>) {
+		if (!options || typeof options !== 'object') {
+			throw new TypeError('options must be an object.');
+		}
+		if (!Array.isArray(options.formats) || options.formats.some(x => !(x instanceof InputFormat))) {
+			throw new TypeError('options.formats must be an array of InputFormat.');
+		}
+		if (!(options.source instanceof Source)) {
+			throw new TypeError('options.source must be a Source.');
+		}
+
+		this._formats = options.formats;
+		this._source = options.source;
+		this._mainReader = new Reader(options.source);
+	}
+
+	/** @internal */
+	_getDemuxer() {
+		return this._demuxerPromise ??= (async () => {
+			await this._mainReader.loadRange(0, 4096); // Load the first 4 kiB so we can determine the format
+
+			for (const format of this._formats) {
+				const canRead = await format._canReadInput(this);
+				if (canRead) {
+					this._format = format;
+					return format._createDemuxer(this);
+				}
+			}
+
+			throw new Error('Input has an unsupported or unrecognizable format.');
+		})();
+	}
+
+	/**
+	 * Returns the source from which this input file reads its data. This is the same source that was passed to the
+	 * constructor.
+	 */
+	get source() {
+		return this._source;
+	}
+
+	/**
+	 * Returns the format of the input file. You can compare this result directly to the InputFormat singletons or use
+	 * `instanceof` checks for subset-aware logic (for example, `format instanceof MatroskaInputFormat` is true for
+	 * both MKV and WebM).
+	 */
+	async getFormat() {
+		await this._getDemuxer();
+		assert(this._format!);
+		return this._format;
+	}
+
+	/**
+	 * Computes the duration of the input file, in seconds. More precisely, returns the largest end timestamp among
+	 * all tracks.
+	 */
+	async computeDuration() {
+		const demuxer = await this._getDemuxer();
+		return demuxer.computeDuration();
+	}
+
+	/** Returns the list of all tracks of this input file. */
+	async getTracks() {
+		const demuxer = await this._getDemuxer();
+		return demuxer.getTracks();
+	}
+
+	/** Returns the list of all video tracks of this input file. */
+	async getVideoTracks() {
+		const tracks = await this.getTracks();
+		return tracks.filter(x => x.isVideoTrack());
+	}
+
+	/** Returns the primary video track of this input file, or null if there are no video tracks. */
+	async getPrimaryVideoTrack() {
+		const tracks = await this.getTracks();
+		return tracks.find(x => x.isVideoTrack()) ?? null;
+	}
+
+	/** Returns the list of all audio tracks of this input file. */
+	async getAudioTracks() {
+		const tracks = await this.getTracks();
+		return tracks.filter(x => x.isAudioTrack());
+	}
+
+	/** Returns the primary audio track of this input file, or null if there are no audio tracks. */
+	async getPrimaryAudioTrack() {
+		const tracks = await this.getTracks();
+		return tracks.find(x => x.isAudioTrack()) ?? null;
+	}
+
+	/** Returns the full MIME type of this input file, including track codecs. */
+	async getMimeType() {
+		const demuxer = await this._getDemuxer();
+		return demuxer.getMimeType();
+	}
+}