dasha 4.1.0 → 4.2.1

package/README.md

@@ -42,6 +42,7 @@ async function saveVideo() {
   });
 
   const bestVideoTrack = videoTracks[0];
+  console.log('Dynamic range:', await bestVideoTrack.getDynamicRange()); // sdr
 
   const segments = await bestVideoTrack.getSegments();
 
@@ -93,6 +94,43 @@ async function saveDashVideo() {
 }
 ```
 
+### Adding external subtitle tracks
+
+`addSubtitleTrack()` is useful when subtitle URLs are provided separately from the HLS/DASH manifest. Added subtitles become part of the same `Input`, so they can be queried, filtered and downloaded through the regular subtitle track API.
+
+```ts
+import { DASH_FORMATS, Input, UrlSource } from 'dasha';
+
+async function getEnglishSubtitles() {
+  const input = new Input({
+    source: new UrlSource('https://example.com/manifest.mpd'),
+    formats: DASH_FORMATS,
+  });
+
+  const primaryVideoTrack = await input.getPrimaryVideoTrack();
+  if (!primaryVideoTrack) {
+    throw new Error('No video tracks found');
+  }
+
+  input.addSubtitleTrack(new UrlSource('https://cdn.example.com/subtitles/en.vtt'), {
+    languageCode: 'en',
+    name: 'English',
+    pairWith: primaryVideoTrack,
+  });
+
+  const englishSubtitleTracks = await input.getSubtitleTracks({
+    filter: async (track) => (await track.getLanguageCode()) === 'en',
+  });
+
+  const englishSubtitleTrack = englishSubtitleTracks[0];
+  if (!englishSubtitleTrack) {
+    return [];
+  }
+
+  return await englishSubtitleTrack.getSegments();
+}
+```
+
 ### Mediabunny with DASH support
 
 > Only reading is supported

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _$mediabunny from "mediabunny";
-import { AudioCodec, DurationMetadataRequestOptions, EncodedPacket, FilePathSource, HLS_FORMATS, Input as Input$1, InputAudioTrack as InputAudioTrack$1, InputFormat, InputOptions, InputTrack as InputTrack$2, InputTrackQuery, InputTrackQuery as InputTrackQuery$1, InputVideoTrack as InputVideoTrack$1, MediaCodec as MediaCodec$1, MetadataTags, PacketRetrievalOptions, Source, TrackDisposition, UrlSource, VideoCodec, asc, desc, prefer } from "mediabunny";
+import { AudioCodec as AudioCodec$1, DurationMetadataRequestOptions, EncodedPacket, FilePathSource, HLS, HLS_FORMATS, Input as Input$1, InputAudioTrack as InputAudioTrack$1, InputFormat, InputOptions, InputTrack as InputTrack$2, InputTrackQuery, InputTrackQuery as InputTrackQuery$1, InputVideoTrack as InputVideoTrack$1, MP3, MP4, MaybePromise, MediaCodec as MediaCodec$1, MetadataTags, PacketRetrievalOptions, PathedSource, Source, SourceRef, SubtitleCodec as SubtitleCodec$1, TrackDisposition, UrlSource, VideoCodec as VideoCodec$1, asc, desc, prefer } from "mediabunny";
 import { Element } from "@xmldom/xmldom";
 
 //#region src/mediabunny.d.ts
@@ -46,60 +46,47 @@ type InputTrackWithBacking = InputTrack & {
 };
 //#endregion
 //#region src/codec.d.ts
-/**
- * List of known video codecs, ordered by encoding preference.
- * @group Codecs
- * @public
- */
-declare const VIDEO_CODECS: readonly ["avc", "hevc", "vp8", "vp9", "av1", "vc1"];
-/**
- * List of known video dynamic ranges.
- * @group Codecs
- * @public
- */
-declare const VIDEO_DYNAMIC_RANGES: readonly ["sdr", "hlg", "hdr10", "hdr10+", "dv"];
-/**
- * List of known audio codecs, ordered by encoding preference.
- * @group Codecs
- * @public
- */
-declare const AUDIO_CODECS: readonly ["aac", "opus", "mp3", "vorbis", "flac", "alac", "ac3", "eac3", "dts"];
-/**
- * List of known subtitle codecs, ordered by encoding preference.
- * @group Codecs
- * @public
- */
-declare const SUBTITLE_CODECS: readonly ["srt", "webvtt", "ttml", "dfxp", "ssa", "ass", "stpp"];
 /**
  * Union type of known video codecs.
  * @group Codecs
  * @public
  */
-type VideoCodec$1 = (typeof VIDEO_CODECS)[number];
+type VideoCodec = VideoCodec$1 | 'vc1';
 /**
  * Union type of known video dynamic ranges.
+ *
+ * `sdr`: Standard Dynamic Range
+ *
+ * `hlg`: High-Luminance Gamma
+ *
+ * `hdr10`: High-Dynamic Range 10
+ *
+ * `hdr10+`: High-Dynamic Range 10+
+ *
+ * `dv`: Dolby Vision
+ *
  * @group Codecs
  * @public
  */
-type VideoDynamicRange = (typeof VIDEO_DYNAMIC_RANGES)[number];
+type VideoDynamicRange = 'sdr' | 'hlg' | 'hdr10' | 'hdr10+' | 'dv';
 /**
  * Union type of known audio codecs.
  * @group Codecs
  * @public
  */
-type AudioCodec$1 = (typeof AUDIO_CODECS)[number];
+type AudioCodec = AudioCodec$1 | 'dts' | 'alac';
 /**
  * Union type of known subtitle codecs.
  * @group Codecs
  * @public
  */
-type SubtitleCodec = (typeof SUBTITLE_CODECS)[number];
+type SubtitleCodec = SubtitleCodec$1 | 'srt' | 'ttml' | 'dfxp' | 'ssa' | 'ass' | 'stpp';
 /**
  * Union type of known media codecs.
  * @group Codecs
  * @public
  */
-type MediaCodec = VideoCodec$1 | AudioCodec$1 | SubtitleCodec;
+type MediaCodec = VideoCodec | AudioCodec | SubtitleCodec;
 //#endregion
 //#region src/role-type.d.ts
 declare const ROLE_TYPE: {
@@ -171,6 +158,7 @@ type DashParsedVideoTrack = DashTrackCommon & {
   width?: number;
   height?: number;
   frameRate?: number;
+  colorSpace?: VideoColorSpaceInit;
   dynamicRange?: VideoDynamicRange;
 };
 type DashParsedAudioTrack = DashTrackCommon & {
@@ -412,7 +400,7 @@ declare class DashInputVideoTrackBacking extends DashTrackBackingBase {
   internalTrack: InternalVideoTrack;
   constructor(internalTrack: InternalVideoTrack);
   getType(): "video";
-  getCodec(): VideoCodec | null;
+  getCodec(): VideoCodec$1 | null;
   getCodedWidth(): number | Promise<any>;
   getCodedHeight(): number | Promise<any>;
   getSquarePixelWidth(): number | Promise<any>;
@@ -427,7 +415,7 @@ declare class DashInputAudioTrackBacking extends DashTrackBackingBase {
   internalTrack: InternalAudioTrack;
   constructor(internalTrack: InternalAudioTrack);
   getType(): "audio";
-  getCodec(): AudioCodec | null;
+  getCodec(): AudioCodec$1 | null;
   getNumberOfChannels(): number | Promise<any>;
   getSampleRate(): number | Promise<any>;
 }
@@ -475,6 +463,15 @@ declare class HlsSubtitlePlaylist implements HlsSegmentedInput {
   getLiveRefreshInterval(): Promise<number | null>;
   isRelativeToUnixEpoch(): Promise<boolean>;
 }
+declare class ExternalSubtitleSegmentedInput implements HlsSegmentedInput {
+  #private;
+  segments: HlsSegment[];
+  constructor(source: SourceWithRootPath, rootPath: string);
+  runUpdateSegments(): Promise<void>;
+  getDurationFromMetadata(options: DurationMetadataRequestOptions): Promise<number | null>;
+  getLiveRefreshInterval(): Promise<number | null>;
+  isRelativeToUnixEpoch(): Promise<boolean>;
+}
 declare class HlsSubtitleTrackBacking {
   #private;
   constructor(params: {
@@ -509,10 +506,49 @@ declare class HlsSubtitleTrackBacking {
   getNextKeyPacket(_packet: EncodedPacket, _options: unknown): Promise<EncodedPacket | null>;
   getSegmentedInput(): HlsSubtitlePlaylist;
 }
+declare class ExternalSubtitleTrackBacking {
+  #private;
+  constructor(params: {
+    id: number;
+    number: number;
+    pairingMask: bigint;
+    source: SourceWithRootPath;
+    codec?: SubtitleCodec | null;
+    codecString?: string | null;
+    languageCode?: string;
+    name?: string | null;
+    disposition?: Partial<TrackDisposition>;
+  });
+  getType(): "subtitle";
+  getId(): number;
+  getNumber(): number;
+  getCodec(): Promise<never>;
+  getInternalCodecId(): null;
+  getName(): string | null;
+  getLanguageCode(): string;
+  getTimeResolution(): number;
+  isRelativeToUnixEpoch(): Promise<boolean>;
+  getDisposition(): TrackDisposition;
+  getPairingMask(): bigint;
+  getBitrate(): null;
+  getAverageBitrate(): null;
+  getDurationFromMetadata(options: DurationMetadataRequestOptions): Promise<number | null>;
+  getLiveRefreshInterval(): Promise<number | null>;
+  getHasOnlyKeyPackets(): boolean;
+  getDecoderConfig(): Promise<null>;
+  getMetadataCodecParameterString(): Promise<string | null>;
+  getFirstPacket(_options: unknown): Promise<EncodedPacket | null>;
+  getPacket(_timestamp: number, _options: unknown): Promise<EncodedPacket | null>;
+  getNextPacket(_packet: EncodedPacket, _options: unknown): Promise<EncodedPacket | null>;
+  getKeyPacket(_timestamp: number, _options: unknown): Promise<EncodedPacket | null>;
+  getNextKeyPacket(_packet: EncodedPacket, _options: unknown): Promise<EncodedPacket | null>;
+  getSegmentedInput(): ExternalSubtitleSegmentedInput;
+}
 //#endregion
 //#region src/mediabunny-input.d.ts
 declare module 'mediabunny' {
   interface Input<S extends Source = Source> {
+    _getDemuxer(): Promise<unknown>;
     _getTrackBackings(): Promise<unknown[]>;
     _wrapBackingAsTrack(backing: unknown): InputTrack$2;
   }
@@ -521,10 +557,25 @@ type SegmentAccessMethods = {
   getSegmentedInput(): HlsSegmentedInput | DashSegmentedInput;
   getSegments(): Promise<(HlsSegment | DashSegment)[]>;
 };
-type MediabunnyTrackWithSegments = InputTrack$2 & SegmentAccessMethods;
-type MediabunnyVideoTrackWithSegments = InputVideoTrack$1 & SegmentAccessMethods;
-type MediabunnyAudioTrackWithSegments = InputAudioTrack$1 & SegmentAccessMethods;
-type NativeTrackBacking = Parameters<Input$1<Source>['_wrapBackingAsTrack']>[0];
+type VideoDynamicRangeMethods = {
+  getDynamicRange(): Promise<VideoDynamicRange>;
+};
+type MediabunnySubtitleTrackLike = InputTrack$2 & {
+  type: 'subtitle';
+};
+type InputTrack$1 = InputTrack$2 & SegmentAccessMethods;
+type InputVideoTrack = InputVideoTrack$1 & SegmentAccessMethods & VideoDynamicRangeMethods;
+type InputAudioTrack = InputAudioTrack$1 & SegmentAccessMethods;
+type InputSubtitleTrack = MediabunnySubtitleTrackLike & SegmentAccessMethods;
+type InputSubtitleSource = PathedSource | SourceRef<PathedSource>;
+type InputSubtitleTrackMetadata = {
+  codec?: SubtitleCodec | null;
+  codecString?: string | null;
+  disposition?: Partial<TrackDisposition>;
+  languageCode?: string;
+  name?: string | null;
+  pairWith?: InputVideoTrack | Iterable<InputVideoTrack>;
+};
 type SegmentableBacking = {
   getId(): number;
   getNumber(): number;
@@ -545,6 +596,7 @@ type SegmentableBacking = {
   getMetadataCodecParameterString?(): string | null | Promise<string | null>;
   getSegmentedInput?(): HlsSegmentedInput | DashSegmentedInput;
 };
+type NativeTrackBacking = SegmentableBacking;
 type TrackBacking = NativeTrackBacking | SegmentableBacking;
 declare const BACKING_TYPE_SUBTITLE = "subtitle";
 declare const BACKING_TYPE_AUDIO = "audio";
@@ -552,13 +604,15 @@ declare const BACKING_TYPE_VIDEO = "video";
 declare const preserveSubtitleBackingsOnInput: (input: Input$1) => Input$1<Source>;
 declare class SegmentedMediabunnyInput<S extends Source = Source> extends Input$1<S> {
   #private;
-  _wrapBackingAsTrack(backing: TrackBacking): MediabunnyTrackWithSegments;
-  _getSyntheticTrackBackings(type?: typeof BACKING_TYPE_VIDEO | typeof BACKING_TYPE_AUDIO | typeof BACKING_TYPE_SUBTITLE): Promise<HlsSubtitleTrackBacking[]>;
-  getTracks(query?: InputTrackQuery$1<MediabunnyTrackWithSegments>): Promise<MediabunnyTrackWithSegments[]>;
-  getVideoTracks(query?: InputTrackQuery$1<MediabunnyVideoTrackWithSegments>): Promise<MediabunnyVideoTrackWithSegments[]>;
-  getAudioTracks(query?: InputTrackQuery$1<MediabunnyAudioTrackWithSegments>): Promise<MediabunnyAudioTrackWithSegments[]>;
-  getPrimaryVideoTrack(query?: InputTrackQuery$1<MediabunnyVideoTrackWithSegments>): Promise<MediabunnyVideoTrackWithSegments | null>;
-  getPrimaryAudioTrack(query?: InputTrackQuery$1<MediabunnyAudioTrackWithSegments>): Promise<MediabunnyAudioTrackWithSegments | null>;
+  _wrapBackingAsTrack(backing: TrackBacking): InputTrack$1;
+  _getSyntheticTrackBackings(type?: typeof BACKING_TYPE_VIDEO | typeof BACKING_TYPE_AUDIO | typeof BACKING_TYPE_SUBTITLE): Promise<(ExternalSubtitleTrackBacking | HlsSubtitleTrackBacking)[]>;
+  getTracks(query?: InputTrackQuery$1<InputTrack$1>): Promise<InputTrack$1[]>;
+  getVideoTracks(query?: InputTrackQuery$1<InputVideoTrack>): Promise<InputVideoTrack[]>;
+  getAudioTracks(query?: InputTrackQuery$1<InputAudioTrack>): Promise<InputAudioTrack[]>;
+  getSubtitleTracks(query?: InputTrackQuery$1<InputSubtitleTrack>): Promise<InputSubtitleTrack[]>;
+  getPrimaryVideoTrack(query?: InputTrackQuery$1<InputVideoTrack>): Promise<InputVideoTrack | null>;
+  getPrimaryAudioTrack(query?: InputTrackQuery$1<InputAudioTrack>): Promise<InputAudioTrack | null>;
+  addSubtitleTrack(source: InputSubtitleSource, metadata?: InputSubtitleTrackMetadata): InputSubtitleTrack;
 }
 //#endregion
 //#region src/index.d.ts
@@ -567,14 +621,12 @@ type DashaInputOptions<S extends Source = Source> = Omit<InputOptions<S>, 'forma
 };
 type InputSegment = HlsSegment | DashSegment;
 type InputSegmentedInput = HlsSegmentedInput | DashSegmentedInput;
-type InputTrack$1 = MediabunnyTrackWithSegments;
-type InputVideoTrack = MediabunnyVideoTrackWithSegments;
-type InputAudioTrack = MediabunnyAudioTrackWithSegments;
 declare class Input<S extends Source = Source> extends SegmentedMediabunnyInput<S> {
   constructor(options: DashaInputOptions<S>);
 }
 declare const isInput: (value: unknown) => value is Input;
 declare const getSegmentedInput: (track: InputTrack$1) => InputSegmentedInput;
 declare const getSegments: (track: InputTrack$1) => Promise<InputSegment[]>;
+declare const ALL_FORMATS: InputFormat[];
 //#endregion
-export { DASH, DASH_FORMATS, type DashSegment, type DashSegmentedInput, FilePathSource, HLS_FORMATS, type HlsSegment, type HlsSegmentedInput, Input, InputAudioTrack, InputSegment, InputSegmentedInput, InputTrack$1 as InputTrack, type InputTrackQuery, type InputTrackWithBacking, InputVideoTrack, type MediaCodec, type SubtitleCodec, UrlSource, asc, desc, getSegmentedInput, getSegments, isInput, prefer, preserveSubtitleBackingsOnInput };
+export { ALL_FORMATS, type AudioCodec, DASH, DASH_FORMATS, type DashSegment, type DashSegmentedInput, FilePathSource, HLS, HLS_FORMATS, type HlsSegment, type HlsSegmentedInput, Input, type InputAudioTrack, InputSegment, InputSegmentedInput, type InputSubtitleSource, type InputSubtitleTrack, type InputSubtitleTrackMetadata, type InputTrack$1 as InputTrack, type InputTrackQuery, type InputTrackWithBacking, type InputVideoTrack, MP3, MP4, type MaybePromise, type MediaCodec, type SubtitleCodec, UrlSource, type VideoCodec, type VideoDynamicRange, asc, desc, getSegmentedInput, getSegments, isInput, prefer, preserveSubtitleBackingsOnInput };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { ADTS, CustomPathedSource, FilePathSource, HLS, HLS_FORMATS, Input as Input$1, InputFormat, InputTrack, MATROSKA, MP3, MP4, QTFF, UrlSource, WEBM, asc, desc, prefer } from "mediabunny";
+import { ADTS, ALL_FORMATS as ALL_FORMATS$1, CustomPathedSource, FilePathSource, HLS, HLS as HLS$1, HLS_FORMATS, Input as Input$1, InputFormat, InputTrack, InputVideoTrack, MATROSKA, MP3, MP3 as MP3$1, MP4, MP4 as MP4$1, QTFF, SourceRef, UrlSource, WEBM, asc, desc, prefer } from "mediabunny";
 import { DOMParser } from "@xmldom/xmldom";
 import { Temporal } from "temporal-polyfill";
 import { readFile } from "node:fs/promises";
@@ -158,6 +158,32 @@ const MATRIX = {
 	YCbCr_BT_2020_and_2100: 9,
 	ICtCp_BT_2100: 14
 };
+const DOLBY_VISION_CODECS = [
+	"dva1",
+	"dvav",
+	"dvhe",
+	"dvh1"
+];
+const COLOR_PRIMARIES_MAP = new Map([
+	[PRIMARIES.BT_709, "bt709"],
+	[PRIMARIES.BT_601_625, "bt470bg"],
+	[PRIMARIES.BT_601_525, "smpte170m"],
+	[PRIMARIES.BT_2020_and_2100, "bt2020"],
+	[PRIMARIES.SMPTE_ST_2113_and_EG_4321, "smpte432"]
+]);
+const TRANSFER_CHARACTERISTICS_MAP = new Map([
+	[TRANSFER.BT_709, "bt709"],
+	[TRANSFER.BT_601, "smpte170m"],
+	[TRANSFER.BT_2100_PQ, "pq"],
+	[TRANSFER.BT_2100_HLG, "hlg"]
+]);
+const MATRIX_COEFFICIENTS_MAP = new Map([
+	[MATRIX.RGB, "rgb"],
+	[MATRIX.YCbCr_BT_709, "bt709"],
+	[MATRIX.YCbCr_BT_601_625, "bt470bg"],
+	[MATRIX.YCbCr_BT_601_525, "smpte170m"],
+	[MATRIX.YCbCr_BT_2020_and_2100, "bt2020-ncl"]
+]);
 const parseVideoCodecFromMime = (mime) => {
 	const target = mime.toLowerCase().trim().split(".")[0];
 	const avc = [
@@ -199,6 +225,52 @@ const parseDynamicRangeFromCicp = (primaries, transfer, matrix) => {
 	else if (TRANSFER.BT_2100_HLG === transfer) return "hlg";
 	else return "sdr";
 };
+const parseColorSpaceFromCicp = (primaries, transfer, matrix) => {
+	const normalizedTransfer = transfer == 5 ? TRANSFER.BT_601 : transfer;
+	return {
+		primaries: COLOR_PRIMARIES_MAP.get(primaries),
+		transfer: TRANSFER_CHARACTERISTICS_MAP.get(normalizedTransfer),
+		matrix: MATRIX_COEFFICIENTS_MAP.get(matrix)
+	};
+};
+const parseDynamicRangeFromCodecString = (codecs) => {
+	const normalized = codecs?.trim().toLowerCase();
+	if (!normalized) return;
+	return DOLBY_VISION_CODECS.some((value) => normalized.startsWith(value)) ? "dv" : void 0;
+};
+const getCicpValues = (supplementalProps = [], essentialProps = []) => {
+	const primariesScheme = "urn:mpeg:mpegB:cicp:ColourPrimaries";
+	const transferScheme = "urn:mpeg:mpegB:cicp:TransferCharacteristics";
+	const matrixScheme = "urn:mpeg:mpegB:cicp:MatrixCoefficients";
+	const allProps = [...essentialProps, ...supplementalProps];
+	const getValues = (schemeIdUri) => allProps.filter((prop) => prop.schemeIdUri === schemeIdUri).flatMap((prop) => prop.value ? [Number.parseInt(prop.value, 10)] : []);
+	return {
+		primaries: getValues(primariesScheme)[0] ?? 0,
+		transfer: getValues(transferScheme)[0] ?? 0,
+		matrix: getValues(matrixScheme)[0] ?? 0
+	};
+};
+const parseColorSpace = (supplementalProps = [], essentialProps = []) => {
+	const { primaries, transfer, matrix } = getCicpValues(supplementalProps, essentialProps);
+	return parseColorSpaceFromCicp(primaries, transfer, matrix);
+};
+const parseDynamicRangeFromHlsVideoRange = (videoRange, codecs) => {
+	const normalized = videoRange?.replaceAll("\"", "").trim().toUpperCase();
+	if (!normalized) return;
+	const codecDynamicRange = parseDynamicRangeFromCodecString(codecs);
+	if (normalized === "PQ") return codecDynamicRange ?? "hdr10";
+	if (normalized === "HLG") return "hlg";
+	if (normalized === "SDR") return "sdr";
+};
+const parseDynamicRangeFromColorSpace = (colorSpace) => {
+	if (!colorSpace) return;
+	if (colorSpace.transfer === "pq") return "hdr10";
+	if (colorSpace.transfer === "hlg") return "hlg";
+	if (colorSpace.primaries != null || colorSpace.transfer != null || colorSpace.matrix != null || colorSpace.fullRange != null) return "sdr";
+};
+const inferDynamicRange = (params) => {
+	return parseDynamicRangeFromCodecString(params.codecs) ?? parseDynamicRangeFromHlsVideoRange(params.videoRange, params.codecs) ?? parseDynamicRangeFromColorSpace(params.colorSpace) ?? "sdr";
+};
 const parseVideoCodec = (codecs) => {
 	for (const codec of codecs.toLowerCase().split(",")) {
 		const mime = codec.trim().split(".")[0];
@@ -218,18 +290,10 @@ const tryParseVideoCodec = (codecs) => {
 	}
 };
 const parseDynamicRange = (codecs, supplementalProps = [], essentialProps = []) => {
-	if ([
-		"dva1",
-		"dvav",
-		"dvhe",
-		"dvh1"
-	].some((value) => codecs.startsWith(value))) return "dv";
-	const primariesScheme = "urn:mpeg:mpegB:cicp:ColourPrimaries";
-	const transferScheme = "urn:mpeg:mpegB:cicp:TransferCharacteristics";
-	const matrixScheme = "urn:mpeg:mpegB:cicp:MatrixCoefficients";
-	const allProps = [...essentialProps, ...supplementalProps];
-	const getValues = (schemeIdUri) => allProps.filter((prop) => prop.schemeIdUri === schemeIdUri).flatMap((prop) => prop.value ? [parseInt(prop.value)] : []);
-	return parseDynamicRangeFromCicp(getValues(primariesScheme).reduce((acc, current) => acc + current, 0), getValues(transferScheme).reduce((acc, current) => acc + current, 0), getValues(matrixScheme).reduce((acc, current) => acc + current, 0));
+	const codecDynamicRange = parseDynamicRangeFromCodecString(codecs);
+	if (codecDynamicRange) return codecDynamicRange;
+	const { primaries, transfer, matrix } = getCicpValues(supplementalProps, essentialProps);
+	return parseDynamicRangeFromCicp(primaries, transfer, matrix);
 };
 //#endregion
 //#region src/dash/dash-misc.ts
@@ -838,6 +902,74 @@ var HlsSubtitlePlaylist = class {
 		this.#streamHasEnded = streamHasEnded;
 	}
 };
+var ExternalSubtitleSegmentedInput = class {
+	segments = [];
+	#source;
+	#rootPath;
+	#delegate = null;
+	#loadPromise = null;
+	constructor(source, rootPath) {
+		this.#source = source;
+		this.#rootPath = rootPath;
+	}
+	runUpdateSegments() {
+		return this.#loadPromise ??= (async () => {
+			if (this.#delegate) {
+				await this.#delegate.runUpdateSegments();
+				this.segments = this.#delegate.segments;
+				return;
+			}
+			const loaded = await loadPlaylistText(this.#source, this.#rootPath);
+			if (splitPlaylistLines(loaded.text)[0] === "#EXTM3U") {
+				this.#delegate = new HlsSubtitlePlaylist(this.#source, loaded.path);
+				await this.#delegate.runUpdateSegments();
+				this.segments = this.#delegate.segments;
+				return;
+			}
+			const segment = {
+				timestamp: 0,
+				duration: 0,
+				relativeToUnixEpoch: false,
+				firstSegment: null,
+				sequenceNumber: 0,
+				location: {
+					path: toSegmentPath(loaded.path),
+					offset: 0,
+					length: null
+				},
+				encryption: null,
+				initSegment: null,
+				lastProgramDateTimeSeconds: null
+			};
+			segment.firstSegment = segment;
+			this.segments = [segment];
+			this.#delegate = {
+				segments: this.segments,
+				runUpdateSegments: async () => {},
+				getDurationFromMetadata: async (_options) => null,
+				getLiveRefreshInterval: async () => null,
+				isRelativeToUnixEpoch: async () => false
+			};
+		})().finally(() => {
+			this.#loadPromise = null;
+		});
+	}
+	async getDurationFromMetadata(options) {
+		await this.runUpdateSegments();
+		if (this.#delegate) return this.#delegate.getDurationFromMetadata(options);
+		return null;
+	}
+	async getLiveRefreshInterval() {
+		await this.runUpdateSegments();
+		if (this.#delegate) return this.#delegate.getLiveRefreshInterval();
+		return null;
+	}
+	async isRelativeToUnixEpoch() {
+		await this.runUpdateSegments();
+		if (this.#delegate) return this.#delegate.isRelativeToUnixEpoch();
+		return false;
+	}
+};
 var HlsSubtitleTrackBacking = class {
 	#id;
 	#number;
@@ -930,6 +1062,118 @@ var HlsSubtitleTrackBacking = class {
 		return this.#segmentedInput;
 	}
 };
+var ExternalSubtitleTrackBacking = class {
+	#id;
+	#number;
+	#pairingMask;
+	#source;
+	#segmentedInput;
+	#languageCode;
+	#name;
+	#disposition;
+	#codec;
+	#codecString;
+	#codecInfoPromise = null;
+	constructor(params) {
+		this.#id = params.id;
+		this.#number = params.number;
+		this.#pairingMask = params.pairingMask;
+		this.#source = params.source;
+		this.#segmentedInput = new ExternalSubtitleSegmentedInput(params.source, params.source.rootPath);
+		this.#languageCode = params.languageCode ?? "und";
+		this.#name = params.name ?? null;
+		this.#codec = params.codec ?? tryParseSubtitleCodec(params.codecString ?? "") ?? void 0;
+		this.#codecString = params.codecString ?? params.codec ?? void 0;
+		this.#disposition = {
+			...DEFAULT_TRACK_DISPOSITION$1,
+			...params.disposition
+		};
+	}
+	getType() {
+		return "subtitle";
+	}
+	getId() {
+		return this.#id;
+	}
+	getNumber() {
+		return this.#number;
+	}
+	async #getCodecInfo() {
+		if (this.#codec !== void 0 && this.#codecString !== void 0) return {
+			codec: this.#codec,
+			codecString: this.#codecString
+		};
+		const info = await (this.#codecInfoPromise ??= detectSubtitleCodecFromUri(this.#source, this.#source.rootPath));
+		this.#codec = info.codec;
+		this.#codecString = info.codecString;
+		return info;
+	}
+	getCodec() {
+		if (this.#codec !== void 0) return this.#codec;
+		return this.#getCodecInfo().then((info) => info.codec);
+	}
+	getInternalCodecId() {
+		return null;
+	}
+	getName() {
+		return this.#name;
+	}
+	getLanguageCode() {
+		return this.#languageCode;
+	}
+	getTimeResolution() {
+		return 1e3;
+	}
+	isRelativeToUnixEpoch() {
+		return this.#segmentedInput.isRelativeToUnixEpoch();
+	}
+	getDisposition() {
+		return this.#disposition;
+	}
+	getPairingMask() {
+		return this.#pairingMask;
+	}
+	getBitrate() {
+		return null;
+	}
+	getAverageBitrate() {
+		return null;
+	}
+	getDurationFromMetadata(options) {
+		return this.#segmentedInput.getDurationFromMetadata(options);
+	}
+	getLiveRefreshInterval() {
+		return this.#segmentedInput.getLiveRefreshInterval();
+	}
+	getHasOnlyKeyPackets() {
+		return true;
+	}
+	async getDecoderConfig() {
+		return null;
+	}
+	async getMetadataCodecParameterString() {
+		if (this.#codecString !== void 0) return this.#codecString;
+		return this.#getCodecInfo().then((info) => info.codecString);
+	}
+	async getFirstPacket(_options) {
+		return null;
+	}
+	async getPacket(_timestamp, _options) {
+		return null;
+	}
+	async getNextPacket(_packet, _options) {
+		return null;
+	}
+	async getKeyPacket(_timestamp, _options) {
+		return null;
+	}
+	async getNextKeyPacket(_packet, _options) {
+		return null;
+	}
+	getSegmentedInput() {
+		return this.#segmentedInput;
+	}
+};
 const parseMasterPlaylistSubtitles = async (input) => {
 	const source = input.source;
 	if (!("rootPath" in source) || typeof source.rootPath !== "string") return [];
@@ -992,6 +1236,116 @@ const getHlsSubtitleTrackBackings = (input) => {
 };
 //#endregion
 //#region src/mediabunny-input.ts
+const CUSTOM_SUBTITLE_TRACK_ID_OFFSET = 1e9;
+const CUSTOM_PAIRING_BIT_START = 1024n;
+const EXTRA_PAIRING_MASK = Symbol.for("dasha.extra-pairing-mask");
+const ORIGINAL_GET_PAIRING_MASK = Symbol.for("dasha.original-get-pairing-mask");
+const HLS_VARIANT_INF_LINE = "#EXT-X-STREAM-INF:";
+const HLS_DEMUXER_PATCHED = Symbol.for("dasha.hls-demuxer-patched");
+const HLS_DEMUXER_METADATA_PATCH = Symbol.for("dasha.hls-demuxer-metadata-patch");
+const HLS_VIDEO_RANGE_APPLIED = Symbol.for("dasha.hls-video-range-applied");
+var HlsAttributeList = class {
+	#attributes = {};
+	constructor(str) {
+		let key = "";
+		let value = "";
+		let inValue = false;
+		let inQuotes = false;
+		for (const char of str) if (char === "\"") inQuotes = !inQuotes;
+		else if (char === "=" && !inValue && !inQuotes) inValue = true;
+		else if (char === "," && !inQuotes) {
+			if (key) this.#attributes[key.trim().toLowerCase()] = value;
+			key = "";
+			value = "";
+			inValue = false;
+		} else if (inValue) value += char;
+		else key += char;
+		if (key) this.#attributes[key.trim().toLowerCase()] = value;
+	}
+	get(name) {
+		return this.#attributes[name.toLowerCase()] ?? null;
+	}
+};
+const extractHlsVideoRanges = (text) => {
+	const lines = text.split(/\r?\n/);
+	const videoRanges = [];
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (!line.startsWith(HLS_VARIANT_INF_LINE)) continue;
+		const attributes = new HlsAttributeList(line.slice(18));
+		videoRanges.push(attributes.get("video-range"));
+	}
+	return videoRanges;
+};
+const getPairingMaskIndexes = (pairingMask) => {
+	const indexes = [];
+	let value = pairingMask;
+	let index = 0;
+	while (value > 0n) {
+		if ((value & 1n) === 1n) indexes.push(index);
+		value >>= 1n;
+		index++;
+	}
+	return indexes;
+};
+const applyHlsVideoRangeMetadata = async (demuxer) => {
+	if (demuxer[HLS_VIDEO_RANGE_APPLIED] || !demuxer.hasMasterPlaylist || !demuxer.internalTracks?.length) {
+		demuxer[HLS_VIDEO_RANGE_APPLIED] = true;
+		return;
+	}
+	const slice = await demuxer.input?._reader?.requestEntireFile();
+	if (!slice) {
+		demuxer[HLS_VIDEO_RANGE_APPLIED] = true;
+		return;
+	}
+	const bytes = slice instanceof Uint8Array ? slice : "bytes" in slice ? slice.bytes : slice.data;
+	const videoRanges = extractHlsVideoRanges(new TextDecoder().decode(bytes));
+	if (!videoRanges.length) {
+		demuxer[HLS_VIDEO_RANGE_APPLIED] = true;
+		return;
+	}
+	for (const track of demuxer.internalTracks) {
+		if (track.info.type !== "video") continue;
+		const matchedRanges = getPairingMaskIndexes(track.pairingMask).map((index) => videoRanges[index] ?? null).filter((value) => value != null);
+		const uniqueRanges = [...new Set(matchedRanges)];
+		track.videoRange = uniqueRanges.length === 1 ? uniqueRanges[0] : null;
+	}
+	demuxer[HLS_VIDEO_RANGE_APPLIED] = true;
+};
+const patchHlsDemuxer = (demuxer) => {
+	if (!(demuxer instanceof Object) || !("readMetadata" in demuxer) || typeof demuxer.readMetadata !== "function" || !("input" in demuxer) || demuxer[HLS_DEMUXER_PATCHED]) return demuxer;
+	const candidate = demuxer;
+	if (candidate.constructor?.name !== "HlsDemuxer") return demuxer;
+	const originalReadMetadata = candidate.readMetadata.bind(candidate);
+	candidate.readMetadata = () => {
+		if (candidate[HLS_DEMUXER_METADATA_PATCH]) return candidate[HLS_DEMUXER_METADATA_PATCH];
+		const promise = Promise.resolve(originalReadMetadata()).then(() => applyHlsVideoRangeMetadata(candidate));
+		candidate[HLS_DEMUXER_METADATA_PATCH] = promise.catch((error) => {
+			if (candidate[HLS_DEMUXER_METADATA_PATCH] === promise) candidate[HLS_DEMUXER_METADATA_PATCH] = void 0;
+			throw error;
+		});
+		return candidate[HLS_DEMUXER_METADATA_PATCH];
+	};
+	candidate[HLS_DEMUXER_PATCHED] = true;
+	return demuxer;
+};
+const getDynamicRangeForTrack = async (track) => {
+	const backing = track._backing;
+	const manifestDynamicRange = backing?.internalTrack?.track?.dynamicRange;
+	if (manifestDynamicRange) return manifestDynamicRange;
+	const codecString = await track.getCodecParameterString().catch(() => null);
+	const videoRange = backing?.internalTrack?.videoRange ?? null;
+	const fromMetadata = inferDynamicRange({
+		codecs: codecString,
+		videoRange
+	});
+	if (fromMetadata !== "sdr" || videoRange != null) return fromMetadata;
+	return inferDynamicRange({
+		codecs: codecString,
+		colorSpace: await track.getColorSpace().catch(() => null),
+		videoRange
+	});
+};
 const requireSync = (value, getterName, asyncName) => {
 	if (value instanceof Promise) throw new Error(`'${getterName}' is not available synchronously for this track. Use '${asyncName}()' instead.`);
 	return value;
@@ -1045,6 +1399,10 @@ const patchBaseMediabunnyInput = () => {
 	prototype.getAudioTracks = function(query) {
 		return getTrackBackingsByType(this, BACKING_TYPE_AUDIO).then((backings) => queryWrappedTracks(this, backings, query));
 	};
+	const originalGetDemuxer = prototype._getDemuxer;
+	prototype._getDemuxer = function() {
+		return originalGetDemuxer.call(this).then((demuxer) => patchHlsDemuxer(demuxer));
+	};
 	prototype[BASE_INPUT_PATCHED] = true;
 };
 const getSegmentedInputForTrack = (track) => {
@@ -1054,6 +1412,7 @@ const getSegmentedInputForTrack = (track) => {
 	return internalTrack.demuxer.getSegmentedInputForPath(internalTrack.fullPath);
 };
 const addSegmentAccess = (track) => new Proxy(track, { get(target, prop) {
+	if (prop === "getDynamicRange" && target instanceof InputVideoTrack) return () => getDynamicRangeForTrack(target);
 	if (prop === "getSegmentedInput") return () => getSegmentedInputForTrack(target);
 	if (prop === "getSegments") return async () => {
 		const segmentedInput = getSegmentedInputForTrack(target);
@@ -1104,9 +1463,13 @@ var SegmentedMediabunnyInput = class extends Input$1 {
 	#trackCache = /* @__PURE__ */ new WeakMap();
 	#subtitleTrackCache = /* @__PURE__ */ new WeakMap();
 	#hlsSubtitleBackingsPromise = null;
+	#customSubtitleBackings = [];
+	#nextCustomSubtitleTrackId = CUSTOM_SUBTITLE_TRACK_ID_OFFSET;
+	#nextCustomSubtitleTrackNumber = CUSTOM_SUBTITLE_TRACK_ID_OFFSET;
+	#nextPairingBitIndex = null;
 	async #queryTracks(query, type) {
-		const backings = await getTrackBackingsByType(this, type);
-		return queryWrappedTracks(this, backings, query);
+		const internalInput = this;
+		return queryWrappedTracks(internalInput, await getTrackBackingsByType(internalInput, type), query);
 	}
 	_wrapBackingAsTrack(backing) {
 		const track = backing.getType?.() === "subtitle" ? this.#wrapSubtitleBacking(backing) : super._wrapBackingAsTrack(backing);
@@ -1118,7 +1481,8 @@ var SegmentedMediabunnyInput = class extends Input$1 {
 	}
 	async _getSyntheticTrackBackings(type) {
 		if (type && type !== BACKING_TYPE_SUBTITLE) return [];
-		if (await this.getFormat() !== HLS) return [];
+		const backings = [...this.#customSubtitleBackings];
+		if (await this.getFormat() !== HLS$1) return backings;
 		if (!this.#hlsSubtitleBackingsPromise) {
 			const promise = getHlsSubtitleTrackBackings(this).catch((error) => {
 				if (this.#hlsSubtitleBackingsPromise === promise) this.#hlsSubtitleBackingsPromise = null;
@@ -1126,7 +1490,7 @@ var SegmentedMediabunnyInput = class extends Input$1 {
 			});
 			this.#hlsSubtitleBackingsPromise = promise;
 		}
-		return this.#hlsSubtitleBackingsPromise;
+		return [...backings, ...await this.#hlsSubtitleBackingsPromise];
 	}
 	#wrapSubtitleBacking(backing) {
 		const existing = this.#subtitleTrackCache.get(backing);
@@ -1144,12 +1508,83 @@ var SegmentedMediabunnyInput = class extends Input$1 {
 	async getAudioTracks(query) {
 		return await this.#queryTracks(query, BACKING_TYPE_AUDIO);
 	}
+	async getSubtitleTracks(query) {
+		return await this.#queryTracks(query, BACKING_TYPE_SUBTITLE);
+	}
 	async getPrimaryVideoTrack(query) {
 		return await super.getPrimaryVideoTrack(query);
 	}
 	async getPrimaryAudioTrack(query) {
 		return await super.getPrimaryAudioTrack(query);
 	}
+	addSubtitleTrack(source, metadata = {}) {
+		const sourceWithRootPath = this.#takeSubtitleSourceRef(source).source;
+		if (typeof sourceWithRootPath.rootPath !== "string") throw new TypeError("source must provide a string rootPath.");
+		const pairWith = this.#toPairableVideoTracks(metadata.pairWith);
+		const backing = new ExternalSubtitleTrackBacking({
+			id: this.#nextCustomSubtitleTrackId++,
+			number: this.#nextCustomSubtitleTrackNumber++,
+			pairingMask: 0n,
+			source: sourceWithRootPath,
+			codec: metadata.codec,
+			codecString: metadata.codecString,
+			disposition: metadata.disposition,
+			languageCode: metadata.languageCode,
+			name: metadata.name
+		});
+		this.#pairSubtitleBacking(backing, pairWith);
+		this.#customSubtitleBackings.push(backing);
+		return this._wrapBackingAsTrack(backing);
+	}
+	#takeSubtitleSourceRef(source) {
+		const rawSource = source instanceof SourceRef ? source.source : source;
+		if (!(rawSource instanceof Object) || !("rootPath" in rawSource) || !("ref" in rawSource) || typeof rawSource.ref !== "function") throw new TypeError("source must be a pathed source such as UrlSource or FilePathSource.");
+		const ref = rawSource.ref();
+		this._sourceRefs.push(ref);
+		return ref;
+	}
+	#toPairableVideoTracks(pairWith) {
+		if (!pairWith) return [];
+		const tracks = this.#isIterable(pairWith) ? [...pairWith] : [pairWith];
+		for (const track of tracks) {
+			if (track.input !== this) throw new TypeError("pairWith tracks must belong to the same input instance.");
+			if (track.type !== "video") throw new TypeError("pairWith only accepts video tracks.");
+		}
+		return tracks;
+	}
+	#isIterable(value) {
+		return typeof value === "object" && value !== null && Symbol.iterator in value;
+	}
+	#pairSubtitleBacking(subtitleBacking, videoTracks) {
+		for (const track of videoTracks) {
+			const bit = this.#allocatePairingBit();
+			this.#appendPairingMask(subtitleBacking, bit);
+			this.#appendPairingMask(track._backing, bit);
+		}
+	}
+	#allocatePairingBit() {
+		const nextIndex = this.#nextPairingBitIndex ?? this.#getInitialPairingBitIndex();
+		this.#nextPairingBitIndex = nextIndex + 1n;
+		return 1n << nextIndex;
+	}
+	#getInitialPairingBitIndex() {
+		const loadedBackings = [...this._trackBackingsCache ?? []];
+		let maxBitIndex = -1n;
+		for (const backing of [...loadedBackings, ...this.#customSubtitleBackings]) {
+			const mask = backing.getPairingMask?.() ?? 0n;
+			if (mask === 0n) continue;
+			const bitIndex = BigInt(mask.toString(2).length - 1);
+			if (bitIndex > maxBitIndex) maxBitIndex = bitIndex;
+		}
+		return maxBitIndex >= 0n ? maxBitIndex + 1n : CUSTOM_PAIRING_BIT_START;
+	}
+	#appendPairingMask(backing, mask) {
+		const patchedBacking = backing;
+		patchedBacking[EXTRA_PAIRING_MASK] = (patchedBacking[EXTRA_PAIRING_MASK] ?? 0n) | mask;
+		if (patchedBacking[ORIGINAL_GET_PAIRING_MASK]) return;
+		patchedBacking[ORIGINAL_GET_PAIRING_MASK] = backing.getPairingMask?.bind(backing) ?? (() => 0n);
+		Object.assign(backing, { getPairingMask: () => (patchedBacking[ORIGINAL_GET_PAIRING_MASK]?.() ?? 0n) | (patchedBacking[EXTRA_PAIRING_MASK] ?? 0n) });
+	}
 };
 //#endregion
 //#region src/dash/dash-segmented-input.ts
@@ -1660,7 +2095,8 @@ const createDashTrack = (params) => {
 		if (width) track.width = Number(width);
 		if (height) track.height = Number(height);
 		track.frameRate = frameRate ?? getDashFrameRate(representation);
-		if (track.codecString && supplementalProps && essentialProps) track.dynamicRange = parseDynamicRange(track.codecString, supplementalProps, essentialProps);
+		if (supplementalProps.length > 0 || essentialProps.length > 0) track.colorSpace = parseColorSpace(supplementalProps, essentialProps);
+		if (track.codecString && (supplementalProps.length > 0 || essentialProps.length > 0)) track.dynamicRange = parseDynamicRange(track.codecString, supplementalProps, essentialProps);
 	} else if (track.type === "audio") {
 		if (accessibilities) track.descriptive = checkIsDescriptive(accessibilities);
 		if (supplementalProps) track.joc = getDolbyDigitalPlusComplexityIndex(supplementalProps);
@@ -2258,7 +2694,7 @@ var DashInputVideoTrackBacking = class extends DashTrackBackingBase {
 		return 0;
 	}
 	async getColorSpace() {
-		return this.delegate((track) => track.getColorSpace());
+		return this.internalTrack.track.colorSpace ?? this.delegate((track) => track.getColorSpace());
 	}
 	async canBeTransparent() {
 		return this.delegate((track) => track.canBeTransparent());
@@ -2321,11 +2757,11 @@ var DashInputFormat = class extends InputFormat {
 const DASH = new DashInputFormat();
 const DASH_FORMATS = [
 	DASH,
-	MP4,
+	MP4$1,
 	QTFF,
 	WEBM,
 	MATROSKA,
-	MP3,
+	MP3$1,
 	ADTS
 ];
 //#endregion
@@ -2338,5 +2774,6 @@ var Input = class extends SegmentedMediabunnyInput {
 const isInput = (value) => value instanceof Input;
 const getSegmentedInput = (track) => track.getSegmentedInput();
 const getSegments = async (track) => track.getSegments();
+const ALL_FORMATS = [...ALL_FORMATS$1, DASH];
 //#endregion
-export { DASH, DASH_FORMATS, FilePathSource, HLS_FORMATS, Input, UrlSource, asc, desc, getSegmentedInput, getSegments, isInput, prefer, preserveSubtitleBackingsOnInput };
+export { ALL_FORMATS, DASH, DASH_FORMATS, FilePathSource, HLS, HLS_FORMATS, Input, MP3, MP4, UrlSource, asc, desc, getSegmentedInput, getSegments, isInput, prefer, preserveSubtitleBackingsOnInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dasha",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Streaming manifest parser",
   "files": [
     "dist"