Refactor HLS API: Get rid of specialized Manifest* classes, use Input instead. Add unhydrated InputTracks, InputTrack compatibility, InputTrack queries

2026-10-02 05:13:50 +02:00 · 2026-03-03 15:28:26 +01:00
parent b0604150c1
commit cfb5418fa0
29 changed files with 1841 additions and 904 deletions
@@ -11,11 +11,10 @@ import { determineVideoPacketType } from './codec-data';
 import { customAudioDecoders, customVideoDecoders } from './custom-coder';
 import { Input } from './input';
 import { EncodedPacketSink, PacketRetrievalOptions } from './media-sink';
-import { assert, Rational, Rotation, simplifyRational } from './misc';
+import { assert, MaybePromise, NonFunctionKeys, Rational, Rotation, simplifyRational } from './misc';
 import { TrackType } from './output';
 import { EncodedPacket, PacketType } from './packet';
 import { TrackDisposition } from './metadata';
-import { ManifestInputVariant } from './manifest-input-variant';

 /**
 * Contains aggregate statistics about the encoded packets of a track.
@@ -40,13 +39,19 @@ export interface InputTrackBacking {
 	getLanguageCode(): string;
 	getTimeResolution(): number;
 	getDisposition(): TrackDisposition;
-	getVariant(): ManifestInputVariant | null;
+	getGroupId(): number;
+	getPairingMask(): bigint;
+	getBitrate(): number | null;
+	getAverageBitrate(): number | null;

 	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>;
+
+	isHydrated?(): boolean;
+	hydrate?(): Promise<void>;
 }

 /**
@@ -59,6 +64,8 @@ export abstract class InputTrack {
 	readonly input: Input;
 	/** @internal */
 	_backing: InputTrackBacking;
+	/** @internal */
+	_hydrationPromise: Promise<void> | null = null;

 	/** @internal */
 	constructor(input: Input, backing: InputTrackBacking) {
@@ -104,6 +111,14 @@ export abstract class InputTrack {
 		return this._backing.getNumber();
 	}

+	get groupId() {
+		return this._backing.getGroupId();
+	}
+
+	get pairingMask() {
+		return this._backing.getPairingMask();
+	}
+
 	/**
 	 * The identifier of the codec used internally by the container. It is not homogenized by Mediabunny
 	 * and depends entirely on the container format.
@@ -146,8 +161,12 @@ export abstract class InputTrack {
 		return this._backing.getDisposition();
 	}

-	get variant() {
-		return this._backing.getVariant();
+	get bitrate() {
+		return this._backing.getBitrate();
+	}
+
+	get averageBitrate() {
+		return this._backing.getAverageBitrate();
 	}

 	/**
@@ -208,6 +227,113 @@ export abstract class InputTrack {
 				: 0,
 		};
 	}
+
+	get isHydrated() {
+		return this._backing.isHydrated?.() ?? true;
+	}
+
+	hydrate(): Promise<void> {
+		if (this.isHydrated || !this._backing.hydrate) {
+			return Promise.resolve();
+		}
+
+		return this._hydrationPromise ??= this._backing.hydrate();
+	}
+
+	canBePairedWith(otherTrack: InputTrack | null) {
+		if (!otherTrack) {
+			return true;
+		}
+
+		return this.input === otherTrack.input
+			&& this.groupId !== otherTrack.groupId // This also prevents the track from being paired with itself
+			&& (this.pairingMask & otherTrack.pairingMask) !== 0n;
+	}
+
+	async getPairableTracks(query?: TrackQuery<InputTrack>) {
+		const tracks = await this.input.getTracks();
+		return queryTracks(tracks.filter(x => this.canBePairedWith(x)), query);
+	}
+
+	async pluckPairableTrack(query?: TrackQuery<InputTrack>) {
+		return (await this.getPairableTracks(query))[0];
+	}
+
+	async getPairableVideoTracks(query?: TrackQuery<InputVideoTrack>) {
+		const tracks = await this.getPairableTracks({
+			filter: track => track.isVideoTrack(),
+		});
+		return queryTracks(tracks as InputVideoTrack[], query);
+	}
+
+	async pluckPairableVideoTrack(query?: TrackQuery<InputVideoTrack>) {
+		return (await this.getPairableVideoTracks(query))[0] ?? null;
+	}
+
+	async getPairableAudioTracks(query?: TrackQuery<InputAudioTrack>) {
+		const tracks = await this.getPairableTracks({
+			filter: track => track.isAudioTrack(),
+		});
+		return queryTracks(tracks as InputAudioTrack[], query);
+	}
+
+	async pluckPairableAudioTrack(query?: TrackQuery<InputAudioTrack>) {
+		return (await this.getPairableAudioTracks(query))[0] ?? null;
+	}
+
+	async getPrimaryPairableVideoTrack(query?: TrackQuery<InputVideoTrack>) {
+		return this.input.getPrimaryVideoTrack(mergeTrackQueries({
+			filter: track => track.canBePairedWith(this),
+		}, query));
+	}
+
+	async getPrimaryPairableAudioTrack(query?: TrackQuery<InputAudioTrack>) {
+		return this.input.getPrimaryAudioTrack(mergeTrackQueries({
+			filter: track => track.canBePairedWith(this),
+		}, query));
+	}
+
+	hasPairableTrack(predicate?: (track: InputTrack) => boolean) {
+		assert(this.input._tracksCache);
+		return this.input._tracksCache.some(x => this.canBePairedWith(x) && (!predicate || predicate(x)));
+	}
+
+	hasPairableVideoTrack(predictate?: (track: InputVideoTrack) => boolean): boolean {
+		return this.hasPairableTrack(x =>
+			x.isVideoTrack() && (!predictate || predictate(x)),
+		);
+	}
+
+	hasPairableAudioTrack(predictate?: (track: InputAudioTrack) => boolean): boolean {
+		return this.hasPairableTrack(x =>
+			x.isAudioTrack() && (!predictate || predictate(x)),
+		);
+	}
+
+	getUnhydrated<K extends NonFunctionKeys<this>>(key: K): this[K] | null {
+		try {
+			return this[key];
+		} catch (error) {
+			if (error instanceof TrackNotHydratedError) {
+				return null;
+			}
+
+			throw error;
+		}
+	}
+
+	resolve<K extends NonFunctionKeys<this>>(key: K): MaybePromise<this[K]> {
+		try {
+			return this[key];
+		} catch (error) {
+			if (error instanceof TrackNotHydratedError) {
+				return this.hydrate()
+					.then(() => this[key]);
+			}
+
+			throw error;
+		}
+	}
 }

 export interface InputVideoTrackBacking extends InputTrackBacking {
@@ -216,6 +342,8 @@ export interface InputVideoTrackBacking extends InputTrackBacking {
 	getCodedHeight(): number;
 	getSquarePixelWidth(): number;
 	getSquarePixelHeight(): number;
+	getDisplayWidth?(): number | null;
+	getDisplayHeight?(): number | null;
 	getRotation(): Rotation;
 	getColorSpace(): Promise<VideoColorSpaceInit>;
 	canBeTransparent(): Promise<boolean>;
@@ -230,22 +358,14 @@ export interface InputVideoTrackBacking extends InputTrackBacking {
 export class InputVideoTrack extends InputTrack {
 	/** @internal */
 	override _backing: InputVideoTrackBacking;
-
-	/**
-	 * The pixel aspect ratio of the track's frames, as a rational number in its reduced form. Most videos use
-	 * square pixels (1:1).
-	 */
-	readonly pixelAspectRatio: Rational;
+	/** @internal */
+	_pixelAspectRatioCache: Rational | null = null;

 	/** @internal */
 	constructor(input: Input, backing: InputVideoTrackBacking) {
 		super(input, backing);

 		this._backing = backing;
-		this.pixelAspectRatio = simplifyRational({
-			num: this._backing.getSquarePixelWidth() * this._backing.getCodedHeight(),
-			den: this._backing.getSquarePixelHeight() * this._backing.getCodedWidth(),
-		});
 	}

 	get type(): TrackType {
@@ -281,14 +401,35 @@ export class InputVideoTrack extends InputTrack {
 		return this._backing.getSquarePixelHeight();
 	}

+	/**
+	 * The pixel aspect ratio of the track's frames, as a rational number in its reduced form. Most videos use
+	 * square pixels (1:1).
+	 */
+	get pixelAspectRatio() {
+		return this._pixelAspectRatioCache ??= simplifyRational({
+			num: this._backing.getSquarePixelWidth() * this._backing.getCodedHeight(),
+			den: this._backing.getSquarePixelHeight() * this._backing.getCodedWidth(),
+		});
+	}
+
 	/** The display width of the track's frames in pixels, after aspect ratio adjustment and rotation. */
 	get displayWidth() {
+		const customValue = this._backing.getDisplayWidth?.() ?? null;
+		if (customValue !== null) {
+			return customValue;
+		}
+
 		const rotation = this._backing.getRotation();
 		return rotation % 180 === 0 ? this.squarePixelWidth : this.squarePixelHeight;
 	}

 	/** The display height of the track's frames in pixels, after aspect ratio adjustment and rotation. */
 	get displayHeight() {
+		const customValue = this._backing.getDisplayHeight?.() ?? null;
+		if (customValue !== null) {
+			return customValue;
+		}
+
 		const rotation = this._backing.getRotation();
 		return rotation % 180 === 0 ? this.squarePixelHeight : this.squarePixelWidth;
 	}
@@ -468,3 +609,113 @@ export class InputAudioTrack extends InputTrack {
 		return 'key'; // No audio codec with delta packets
 	}
 }
+
+export class TrackNotHydratedError extends Error {
+	/** Creates a new {@link InputDisposedError}. */
+	constructor(
+		message = 'InputTrack is not hydrated; please call hydrate() first, or use the resolve() or getUnhydrated()'
+			+ ' method.',
+	) {
+		super(message);
+		this.name = 'TrackNotHydratedError';
+	}
+}
+
+export type TrackQuery<T extends InputTrack> = {
+	filter?: (track: T) => MaybePromise<boolean>;
+	sortBy?: (track: T) => MaybePromise<number | number[]>;
+};
+
+export const mergeTrackQueries = <T extends InputTrack>(
+	queryA: TrackQuery<T> | undefined,
+	queryB: TrackQuery<T> | undefined,
+): TrackQuery<T> => {
+	return {
+		filter: queryA?.filter || queryB?.filter
+			? (track) => {
+					const resultA = queryA?.filter?.(track) ?? true;
+					const handleResultA = (resultA: boolean) => {
+						if (resultA === false) {
+							return false;
+						}
+
+						return queryB?.filter?.(track) ?? true;
+					};
+
+					if (resultA instanceof Promise) {
+						return resultA.then(handleResultA);
+					} else {
+						return handleResultA(resultA);
+					}
+				}
+			: undefined,
+		sortBy: queryA?.sortBy || queryB?.sortBy
+			? (track) => {
+					const resultA = queryA?.sortBy?.(track) ?? [];
+					const resultB = queryB?.sortBy?.(track) ?? [];
+
+					type Result = Awaited<typeof resultA>;
+					const join = (resultA: Result, resultB: Result) => {
+						return [
+							...(Array.isArray(resultA) ? resultA : [resultA]),
+							...(Array.isArray(resultB) ? resultB : [resultB]),
+						];
+					};
+
+					if (resultA instanceof Promise || resultB instanceof Promise) {
+						return Promise.all([resultA, resultB]).then(([resultA, resultB]) => {
+							return join(resultA, resultB);
+						});
+					} else {
+						return join(resultA, resultB);
+					}
+				}
+			: undefined,
+	};
+};
+
+export const queryTracks = async <T extends InputTrack>(tracks: T[], query?: TrackQuery<T>): Promise<T[]> => {
+	let matchedTracks = tracks;
+	if (query?.filter) {
+		const filterMatches = tracks.map(track => query.filter!(track));
+		const hasAsyncFilter = filterMatches.some(x => x instanceof Promise);
+		if (hasAsyncFilter) {
+			// eslint-disable-next-line @typescript-eslint/await-thenable
+			const resolvedFilterMatches = await Promise.all(filterMatches);
+			matchedTracks = tracks.filter((_, i) => resolvedFilterMatches[i]);
+		} else {
+			matchedTracks = tracks.filter((_, i) => filterMatches[i] as boolean);
+		}
+	}
+
+	if (!query?.sortBy) {
+		return matchedTracks;
+	}
+
+	const sortValues = matchedTracks.map(track => query.sortBy!(track));
+	const hasAsyncSort = sortValues.some(x => x instanceof Promise);
+	const resolvedSortValues = hasAsyncSort
+		// eslint-disable-next-line @typescript-eslint/await-thenable
+		? await Promise.all(sortValues)
+		: sortValues as (number | number[])[];
+
+	return matchedTracks
+		.map((track, i) => ({ track, sortValue: resolvedSortValues[i] }))
+		.sort((a, b) => {
+			const aValues = Array.isArray(a.sortValue) ? a.sortValue : [a.sortValue];
+			const bValues = Array.isArray(b.sortValue) ? b.sortValue : [b.sortValue];
+			const maxLength = Math.max(aValues.length, bValues.length);
+
+			for (let i = 0; i < maxLength; i++) {
+				const aValue = aValues[i] ?? 0;
+				const bValue = bValues[i] ?? 0;
+				if (aValue === bValue) {
+					continue;
+				}
+				return aValue - bValue;
+			}
+
+			return 0;
+		})
+		.map(x => x.track);
+};