dasha 4.0.3 → 4.2.0

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, 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", "vtt", "ttml", "dfxp", "ssa", "ass", "stpp", "wvtt"];
 /**
  * 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$1 = VideoCodec$1 | AudioCodec$1 | SubtitleCodec;
+type MediaCodec = VideoCodec | AudioCodec | SubtitleCodec;
 //#endregion
 //#region src/role-type.d.ts
 declare const ROLE_TYPE: {
@@ -148,7 +135,7 @@ type DashParsedSegment = {
 };
 type DashTrackCommon = {
   type: DashTrackType;
-  codec?: MediaCodec$1;
+  codec?: MediaCodec;
   codecString: string | null;
   languageCode?: string;
   peakBitrate: number | null;
@@ -171,6 +158,7 @@ type DashParsedVideoTrack = DashTrackCommon & {
   width?: number;
   height?: number;
   frameRate?: number;
+  colorSpace?: VideoColorSpaceInit;
   dynamicRange?: VideoDynamicRange;
 };
 type DashParsedAudioTrack = DashTrackCommon & {
@@ -385,7 +373,7 @@ declare abstract class DashTrackBackingBase {
   delegate<T>(fn: (track: any) => T | Promise<T>): Promise<T>;
   getId(): number;
   getNumber(): number;
-  getCodec(): MediaCodec | null;
+  getCodec(): MediaCodec$1 | null;
   getInternalCodecId(): null;
   getName(): string | null;
   getLanguageCode(): string;
@@ -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>;
 }
@@ -446,9 +434,121 @@ declare class DashInputFormat extends InputFormat {
 declare const DASH: DashInputFormat;
 declare const DASH_FORMATS: InputFormat[];
 //#endregion
+//#region src/hls/hls-subtitles.d.ts
+type SourceWithRootPath = {
+  rootPath: string;
+  _options?: {
+    requestInit?: RequestInit;
+  };
+  _url?: string | URL | Request;
+};
+type HlsSubtitleMediaTag = {
+  autoselect: boolean;
+  codec: SubtitleCodec;
+  codecString: string;
+  default: boolean;
+  forced: boolean;
+  groupId: string;
+  hearingImpaired: boolean;
+  languageCode: string;
+  name: string | null;
+  uri: string;
+};
+declare class HlsSubtitlePlaylist implements HlsSegmentedInput {
+  #private;
+  segments: HlsSegment[];
+  constructor(source: SourceWithRootPath, playlistPath: string);
+  runUpdateSegments(): Promise<void>;
+  getDurationFromMetadata(_options: DurationMetadataRequestOptions): Promise<number | null>;
+  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: {
+    id: number;
+    number: number;
+    pairingMask: bigint;
+    source: SourceWithRootPath;
+    track: HlsSubtitleMediaTag;
+  });
+  getType(): "subtitle";
+  getId(): number;
+  getNumber(): number;
+  getCodec(): 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(): string;
+  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(): 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;
   }
@@ -457,19 +557,62 @@ 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 TrackBacking = 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;
+  getType(): string;
+  getCodec(): MediaCodec$1 | null | Promise<MediaCodec$1 | null>;
+  getInternalCodecId?(): string | number | Uint8Array | null | Promise<string | number | Uint8Array | null>;
+  getName?(): string | null | Promise<string | null>;
+  getLanguageCode?(): string | Promise<string>;
+  getTimeResolution?(): number | Promise<number>;
+  isRelativeToUnixEpoch?(): boolean | Promise<boolean>;
+  getDisposition?(): unknown | Promise<unknown>;
+  getPairingMask?(): bigint;
+  getBitrate?(): number | null | Promise<number | null>;
+  getAverageBitrate?(): number | null | Promise<number | null>;
+  getDurationFromMetadata?(options: unknown): Promise<number | null>;
+  getLiveRefreshInterval?(): Promise<number | null>;
+  getDecoderConfig?(): Promise<VideoDecoderConfig | AudioDecoderConfig | null>;
+  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";
+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;
-  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
@@ -478,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, 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 };