@zenvor/hls.js 1.0.0

package/src/types/level.ts

@@ -0,0 +1,268 @@
+import type { MediaPlaylist } from './media-playlist';
+import type { LevelDetails } from '../loader/level-details';
+import type { AttrList } from '../utils/attr-list';
+import type { MediaDecodingInfo } from '../utils/mediacapabilities-helper';
+
+export interface LevelParsed extends CodecsParsed {
+  attrs: LevelAttributes;
+  bitrate: number;
+  details?: LevelDetails;
+  height?: number;
+  id?: number;
+  name: string;
+  supplemental?: CodecsParsed;
+  url: string;
+  width?: number;
+}
+
+export interface CodecsParsed {
+  audioCodec?: string;
+  videoCodec?: string;
+  textCodec?: string;
+  unknownCodecs?: string[];
+}
+
+export interface LevelAttributes extends AttrList {
+  'ALLOWED-CPC'?: string;
+  AUDIO?: string;
+  'AVERAGE-BANDWIDTH'?: string;
+  BANDWIDTH?: string;
+  'CLOSED-CAPTIONS'?: string;
+  CODECS?: string;
+  'FRAME-RATE'?: string;
+  'HDCP-LEVEL'?: 'TYPE-0' | 'TYPE-1' | 'NONE';
+  'PATHWAY-ID'?: string;
+  RESOLUTION?: string;
+  SCORE?: string;
+  'STABLE-VARIANT-ID'?: string;
+  SUBTITLES?: string;
+  'SUPPLEMENTAL-CODECS'?: string;
+  VIDEO?: string;
+  'VIDEO-RANGE'?: VideoRange;
+}
+
+export const HdcpLevels = ['NONE', 'TYPE-0', 'TYPE-1', null] as const;
+export type HdcpLevel = (typeof HdcpLevels)[number];
+
+export function isHdcpLevel(value: any): value is HdcpLevel {
+  return HdcpLevels.indexOf(value) > -1;
+}
+
+export const VideoRangeValues = ['SDR', 'PQ', 'HLG'] as const;
+export type VideoRange = (typeof VideoRangeValues)[number];
+
+export function isVideoRange(value: any): value is VideoRange {
+  return !!value && VideoRangeValues.indexOf(value) > -1;
+}
+
+export type VariableMap = Record<string, string>;
+
+export const enum HlsSkip {
+  No = '',
+  Yes = 'YES',
+  v2 = 'v2',
+}
+
+export function getSkipValue(details: LevelDetails): HlsSkip {
+  const { canSkipUntil, canSkipDateRanges, age } = details;
+  // A Client SHOULD NOT request a Playlist Delta Update unless it already
+  // has a version of the Playlist that is no older than one-half of the Skip Boundary.
+  // @see: https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis#section-6.3.7
+  const playlistRecentEnough = age < canSkipUntil / 2;
+  if (canSkipUntil && playlistRecentEnough) {
+    if (canSkipDateRanges) {
+      return HlsSkip.v2;
+    }
+    return HlsSkip.Yes;
+  }
+  return HlsSkip.No;
+}
+
+export class HlsUrlParameters {
+  msn?: number;
+  part?: number;
+  skip?: HlsSkip;
+
+  constructor(msn?: number, part?: number, skip?: HlsSkip) {
+    this.msn = msn;
+    this.part = part;
+    this.skip = skip;
+  }
+
+  addDirectives(uri: string): string | never {
+    const url: URL = new self.URL(uri);
+    if (this.msn !== undefined) {
+      url.searchParams.set('_HLS_msn', this.msn.toString());
+    }
+    if (this.part !== undefined) {
+      url.searchParams.set('_HLS_part', this.part.toString());
+    }
+    if (this.skip) {
+      url.searchParams.set('_HLS_skip', this.skip);
+    }
+    return url.href;
+  }
+}
+
+export class Level {
+  public readonly _attrs: LevelAttributes[];
+  public readonly audioCodec: string | undefined;
+  public readonly bitrate: number;
+  public readonly codecSet: string;
+  public readonly url: string[];
+  public readonly frameRate: number;
+  public readonly height: number;
+  public readonly id: number;
+  public readonly name: string;
+  public readonly supplemental: CodecsParsed | undefined;
+  public readonly videoCodec: string | undefined;
+  public readonly width: number;
+  public details?: LevelDetails;
+  public fragmentError: number = 0;
+  public loadError: number = 0;
+  public loaded?: { bytes: number; duration: number };
+  public realBitrate: number = 0;
+  public supportedPromise?: Promise<MediaDecodingInfo>;
+  public supportedResult?: MediaDecodingInfo;
+  private _avgBitrate: number = 0;
+  private _audioGroups?: (string | undefined)[];
+  private _subtitleGroups?: (string | undefined)[];
+  // Deprecated (retained for backwards compatibility)
+  private readonly _urlId: number = 0;
+
+  constructor(data: LevelParsed | MediaPlaylist) {
+    this.url = [data.url];
+    this._attrs = [data.attrs];
+    this.bitrate = data.bitrate;
+    if (data.details) {
+      this.details = data.details;
+    }
+    this.id = data.id || 0;
+    this.name = data.name;
+    this.width = data.width || 0;
+    this.height = data.height || 0;
+    this.frameRate = data.attrs.optionalFloat('FRAME-RATE', 0);
+    this._avgBitrate = data.attrs.decimalInteger('AVERAGE-BANDWIDTH');
+    this.audioCodec = data.audioCodec;
+    this.videoCodec = data.videoCodec;
+    this.codecSet = [data.videoCodec, data.audioCodec]
+      .filter((c) => !!c)
+      .map((s: string) => s.substring(0, 4))
+      .join(',');
+    if ('supplemental' in data) {
+      this.supplemental = data.supplemental;
+      const supplementalVideo = data.supplemental?.videoCodec;
+      if (supplementalVideo && supplementalVideo !== data.videoCodec) {
+        this.codecSet += `,${supplementalVideo.substring(0, 4)}`;
+      }
+    }
+    this.addGroupId('audio', data.attrs.AUDIO);
+    this.addGroupId('text', data.attrs.SUBTITLES);
+  }
+
+  get maxBitrate(): number {
+    return Math.max(this.realBitrate, this.bitrate);
+  }
+
+  get averageBitrate(): number {
+    return this._avgBitrate || this.realBitrate || this.bitrate;
+  }
+
+  get attrs(): LevelAttributes {
+    return this._attrs[0];
+  }
+
+  get codecs(): string {
+    return this.attrs.CODECS || '';
+  }
+
+  get pathwayId(): string {
+    return this.attrs['PATHWAY-ID'] || '.';
+  }
+
+  get videoRange(): VideoRange {
+    return this.attrs['VIDEO-RANGE'] || 'SDR';
+  }
+
+  get score(): number {
+    return this.attrs.optionalFloat('SCORE', 0);
+  }
+
+  get uri(): string {
+    return this.url[0] || '';
+  }
+
+  hasAudioGroup(groupId: string | undefined): boolean {
+    return hasGroup(this._audioGroups, groupId);
+  }
+
+  hasSubtitleGroup(groupId: string | undefined): boolean {
+    return hasGroup(this._subtitleGroups, groupId);
+  }
+
+  get audioGroups(): (string | undefined)[] | undefined {
+    return this._audioGroups;
+  }
+
+  get subtitleGroups(): (string | undefined)[] | undefined {
+    return this._subtitleGroups;
+  }
+
+  addGroupId(type: string, groupId: string | undefined) {
+    if (!groupId) {
+      return;
+    }
+    if (type === 'audio') {
+      let audioGroups = this._audioGroups;
+      if (!audioGroups) {
+        audioGroups = this._audioGroups = [];
+      }
+      if (audioGroups.indexOf(groupId) === -1) {
+        audioGroups.push(groupId);
+      }
+    } else if (type === 'text') {
+      let subtitleGroups = this._subtitleGroups;
+      if (!subtitleGroups) {
+        subtitleGroups = this._subtitleGroups = [];
+      }
+      if (subtitleGroups.indexOf(groupId) === -1) {
+        subtitleGroups.push(groupId);
+      }
+    }
+  }
+
+  // Deprecated methods (retained for backwards compatibility)
+  get urlId(): number {
+    return 0;
+  }
+
+  set urlId(value: number) {}
+
+  get audioGroupIds(): (string | undefined)[] | undefined {
+    return this.audioGroups ? [this.audioGroupId] : undefined;
+  }
+
+  get textGroupIds(): (string | undefined)[] | undefined {
+    return this.subtitleGroups ? [this.textGroupId] : undefined;
+  }
+
+  get audioGroupId(): string | undefined {
+    return this.audioGroups?.[0];
+  }
+
+  get textGroupId(): string | undefined {
+    return this.subtitleGroups?.[0];
+  }
+
+  addFallback() {}
+}
+
+function hasGroup(
+  groups: (string | undefined)[] | undefined,
+  groupId: string | undefined,
+): boolean {
+  if (!groupId || !groups) {
+    return false;
+  }
+  return groups.indexOf(groupId) !== -1;
+}

package/src/types/loader.ts

@@ -0,0 +1,198 @@
+import type { LoaderConfig } from '../config';
+import type { HlsUrlParameters, Level } from './level';
+import type { MediaPlaylist } from './media-playlist';
+import type { NullableNetworkDetails } from './network-details';
+import type { Fragment } from '../loader/fragment';
+import type { Part } from '../loader/fragment';
+import type { KeyLoaderInfo } from '../loader/key-loader';
+import type { LevelDetails } from '../loader/level-details';
+
+export interface LoaderContext {
+  // target URL
+  url: string;
+  // loader response type (arraybuffer or default response type for playlist)
+  responseType: string;
+  // headers
+  headers?: Record<string, string>;
+  // start byte range offset
+  rangeStart?: number;
+  // end byte range offset
+  rangeEnd?: number;
+  // true if onProgress should report partial chunk of loaded content
+  progressData?: boolean;
+}
+
+export interface FragmentLoaderContext extends LoaderContext {
+  frag: Fragment;
+  part: Part | null;
+  resetIV?: boolean;
+}
+
+export interface KeyLoaderContext extends LoaderContext {
+  keyInfo: KeyLoaderInfo;
+  frag: Fragment;
+}
+
+export interface LoaderConfiguration {
+  // LoaderConfig policy that overrides required settings
+  loadPolicy: LoaderConfig;
+  /**
+   * @deprecated use LoaderConfig timeoutRetry and errorRetry maxNumRetry
+   */
+  // Max number of load retries
+  maxRetry: number;
+  /**
+   * @deprecated use LoaderConfig maxTimeToFirstByteMs and maxLoadTimeMs
+   */
+  // Timeout after which `onTimeOut` callback will be triggered
+  //  when loading has not finished after that delay
+  timeout: number;
+  /**
+   * @deprecated use LoaderConfig timeoutRetry and errorRetry retryDelayMs
+   */
+  // Delay between an I/O error and following connection retry (ms).
+  // This to avoid spamming the server
+  retryDelay: number;
+  /**
+   * @deprecated use LoaderConfig timeoutRetry and errorRetry maxRetryDelayMs
+   */
+  // max connection retry delay (ms)
+  maxRetryDelay: number;
+  // When streaming progressively, this is the minimum chunk size required to emit a PROGRESS event
+  highWaterMark?: number;
+}
+
+export interface LoaderResponse {
+  url: string;
+  data?: string | ArrayBuffer | Object;
+  // Errors can include HTTP status code and error message
+  // Successful responses should include status code 200
+  code?: number;
+  text?: string;
+}
+
+export interface LoaderStats {
+  aborted: boolean;
+  loaded: number;
+  retry: number;
+  total: number;
+  chunkCount: number;
+  bwEstimate: number;
+  loading: HlsProgressivePerformanceTiming;
+  parsing: HlsPerformanceTiming;
+  buffering: HlsProgressivePerformanceTiming;
+}
+
+export interface HlsPerformanceTiming {
+  start: number;
+  end: number;
+}
+
+export interface HlsChunkPerformanceTiming extends HlsPerformanceTiming {
+  executeStart: number;
+  executeEnd: number;
+}
+
+export interface HlsProgressivePerformanceTiming extends HlsPerformanceTiming {
+  first: number;
+}
+
+export type LoaderOnSuccess<T extends LoaderContext> = (
+  response: LoaderResponse,
+  stats: LoaderStats,
+  context: T,
+  networkDetails: NullableNetworkDetails,
+) => void;
+
+export type LoaderOnProgress<T extends LoaderContext> = (
+  stats: LoaderStats,
+  context: T,
+  data: string | ArrayBuffer,
+  networkDetails: NullableNetworkDetails,
+) => void;
+
+export type LoaderOnError<T extends LoaderContext> = (
+  error: {
+    // error status code
+    code: number;
+    // error description
+    text: string;
+  },
+  context: T,
+  networkDetails: NullableNetworkDetails,
+  stats: LoaderStats,
+) => void;
+
+export type LoaderOnTimeout<T extends LoaderContext> = (
+  stats: LoaderStats,
+  context: T,
+  networkDetails: NullableNetworkDetails,
+) => void;
+
+export type LoaderOnAbort<T extends LoaderContext> = (
+  stats: LoaderStats,
+  context: T,
+  networkDetails: NullableNetworkDetails,
+) => void;
+
+export interface LoaderCallbacks<T extends LoaderContext> {
+  onSuccess: LoaderOnSuccess<T>;
+  onError: LoaderOnError<T>;
+  onTimeout: LoaderOnTimeout<T>;
+  onAbort?: LoaderOnAbort<T>;
+  onProgress?: LoaderOnProgress<T>;
+}
+
+export interface Loader<T extends LoaderContext> {
+  destroy(): void;
+  abort(): void;
+  load(
+    context: T,
+    config: LoaderConfiguration,
+    callbacks: LoaderCallbacks<T>,
+  ): void;
+  /**
+   * `getCacheAge()` is called by hls.js to get the duration that a given object
+   * has been sitting in a cache proxy when playing live.  If implemented,
+   * this should return a value in seconds.
+   *
+   * For HTTP based loaders, this should return the contents of the "age" header.
+   *
+   * @returns time object being lodaded
+   */
+  getCacheAge?: () => number | null;
+  getResponseHeader?: (name: string) => string | null;
+  context: T | null;
+  stats: LoaderStats;
+}
+
+export const enum PlaylistContextType {
+  MANIFEST = 'manifest',
+  LEVEL = 'level',
+  AUDIO_TRACK = 'audioTrack',
+  SUBTITLE_TRACK = 'subtitleTrack',
+}
+
+export const enum PlaylistLevelType {
+  MAIN = 'main',
+  AUDIO = 'audio',
+  SUBTITLE = 'subtitle',
+}
+
+export interface PlaylistLoaderContext extends LoaderContext {
+  type: PlaylistContextType;
+  // the level index to load
+  level: number | null;
+  // level or track id from LevelLoadingData / TrackLoadingData
+  id: number | null;
+  // Media Playlist Group ID
+  groupId?: string;
+  // Content Steering Pathway ID (or undefined for default Pathway ".")
+  pathwayId?: string;
+  // internal representation of a parsed m3u8 level playlist
+  levelDetails?: LevelDetails;
+  // Blocking playlist request delivery directives (or null id none were added to playlist url
+  deliveryDirectives: HlsUrlParameters | null;
+  // Reference to level or track object in hls.levels, hls.allAudioTracks, or hls.allSubtitleTracks (null when loading MVP)
+  levelOrTrack: Level | MediaPlaylist | null;
+}

package/src/types/media-playlist.ts

@@ -0,0 +1,92 @@
+import type { Level, VideoRange } from './level';
+import type { PlaylistLevelType } from './loader';
+import type { LevelDetails } from '../loader/level-details';
+import type { AttrList } from '../utils/attr-list';
+
+export type AudioPlaylistType = 'AUDIO';
+
+export type MainPlaylistType = AudioPlaylistType | 'VIDEO';
+
+export type SubtitlePlaylistType = 'SUBTITLES' | 'CLOSED-CAPTIONS';
+
+export type MediaPlaylistType = MainPlaylistType | SubtitlePlaylistType;
+
+export type MediaSelection = {
+  [PlaylistLevelType.MAIN]: Level;
+  [PlaylistLevelType.AUDIO]?: MediaPlaylist;
+  [PlaylistLevelType.SUBTITLE]?: MediaPlaylist;
+};
+
+export type VideoSelectionOption = {
+  preferHDR?: boolean;
+  allowedVideoRanges?: Array<VideoRange>;
+  videoCodec?: string;
+};
+
+export type AudioSelectionOption = {
+  lang?: string;
+  assocLang?: string;
+  characteristics?: string;
+  channels?: string;
+  name?: string;
+  audioCodec?: string;
+  groupId?: string;
+  default?: boolean;
+};
+
+export type SubtitleSelectionOption = {
+  id?: number;
+  lang?: string;
+  assocLang?: string;
+  characteristics?: string;
+  name?: string;
+  groupId?: string;
+  default?: boolean;
+  forced?: boolean;
+};
+
+// audioTracks, captions and subtitles returned by `M3U8Parser.parseMasterPlaylistMedia`
+export interface MediaPlaylist {
+  attrs: MediaAttributes;
+  audioCodec?: string;
+  autoselect: boolean; // implicit false if not present
+  bitrate: number;
+  channels?: string;
+  characteristics?: string;
+  details?: LevelDetails;
+  height?: number;
+  default: boolean; // implicit false if not present
+  forced: boolean; // implicit false if not present
+  groupId: string; // required in HLS playlists
+  id: number; // incrementing number to track media playlists
+  instreamId?: string;
+  lang?: string;
+  assocLang?: string;
+  name: string;
+  textCodec?: string;
+  unknownCodecs?: string[];
+  // 'main' is a custom type added to signal a audioCodec in main track?; see playlist-loader~L310
+  type: MediaPlaylistType | 'main';
+  url: string;
+  videoCodec?: string;
+  width?: number;
+  // keep a reference to the track node that is associated with this MediaPlaylist
+  trackNode?: HTMLTrackElement;
+}
+
+export interface MediaAttributes extends AttrList {
+  'ASSOC-LANGUAGE'?: string;
+  AUTOSELECT?: 'YES' | 'NO';
+  CHANNELS?: string;
+  CHARACTERISTICS?: string;
+  DEFAULT?: 'YES' | 'NO';
+  FORCED?: 'YES' | 'NO';
+  'GROUP-ID': string;
+  'INSTREAM-ID'?: string;
+  LANGUAGE?: string;
+  NAME: string;
+  'PATHWAY-ID'?: string;
+  'STABLE-RENDITION-ID'?: string;
+  TYPE?: 'AUDIO' | 'VIDEO' | 'SUBTITLES' | 'CLOSED-CAPTIONS';
+  URI?: string;
+}

package/src/types/network-details.ts

@@ -0,0 +1,3 @@
+export type NetworkDetails = Response | XMLHttpRequest;
+
+export type NullableNetworkDetails = NetworkDetails | null;

package/src/types/remuxer.ts

@@ -0,0 +1,104 @@
+import type { SourceBufferName } from './buffer';
+import type {
+  DemuxedAudioTrack,
+  DemuxedMetadataTrack,
+  DemuxedUserdataTrack,
+  DemuxedVideoTrack,
+  DemuxedVideoTrackBase,
+  MetadataSample,
+  UserdataSample,
+} from './demuxer';
+import type { PlaylistLevelType } from './loader';
+import type { TrackSet } from './track';
+import type { DecryptData } from '../loader/level-key';
+import type { TimestampOffset } from '../utils/timescale-conversion';
+
+export interface Remuxer {
+  remux(
+    audioTrack: DemuxedAudioTrack,
+    videoTrack: DemuxedVideoTrackBase,
+    id3Track: DemuxedMetadataTrack,
+    textTrack: DemuxedUserdataTrack,
+    timeOffset: number,
+    accurateTimeOffset: boolean,
+    flush: boolean,
+    playlistType: PlaylistLevelType,
+  ): RemuxerResult;
+  resetInitSegment(
+    initSegment: Uint8Array | undefined,
+    audioCodec: string | undefined,
+    videoCodec: string | undefined,
+    decryptdata: DecryptData | null,
+  ): void;
+  resetTimeStamp(defaultInitPTS: TimestampOffset | null): void;
+  resetNextTimestamp(): void;
+  destroy(): void;
+}
+
+export interface RemuxedTrack {
+  data1: Uint8Array<ArrayBuffer>;
+  data2?: Uint8Array<ArrayBuffer>;
+  startPTS: number;
+  endPTS: number;
+  startDTS: number;
+  endDTS: number;
+  type: SourceBufferName;
+  hasAudio: boolean;
+  hasVideo: boolean;
+  independent?: boolean;
+  firstKeyFrame?: number;
+  firstKeyFramePTS?: number;
+  nb: number;
+  transferredData1?: ArrayBuffer;
+  transferredData2?: ArrayBuffer;
+  dropped?: number;
+  encrypted?: boolean;
+}
+
+export interface RemuxedMetadata {
+  samples: MetadataSample[];
+}
+
+export interface RemuxedUserdata {
+  samples: UserdataSample[];
+}
+
+export type Mp4SampleFlags = {
+  isLeading: 0;
+  isDependedOn: 0;
+  hasRedundancy: 0;
+  degradPrio: 0;
+  dependsOn: 1 | 2;
+  isNonSync: 0 | 1;
+};
+
+export type Mp4Sample = {
+  size: number;
+  duration: number;
+  cts: number;
+  flags: Mp4SampleFlags;
+};
+
+export type RemuxedAudioTrackSamples = DemuxedAudioTrack & {
+  samples: Mp4Sample[];
+};
+
+export type RemuxedVideoTrackSamples = DemuxedVideoTrack & {
+  samples: Mp4Sample[];
+};
+
+export interface RemuxerResult {
+  audio?: RemuxedTrack;
+  video?: RemuxedTrack;
+  text?: RemuxedUserdata;
+  id3?: RemuxedMetadata;
+  initSegment?: InitSegmentData;
+  independent?: boolean;
+}
+
+export interface InitSegmentData {
+  tracks?: TrackSet;
+  initPTS: number | undefined;
+  timescale: number | undefined;
+  trackId: number | undefined;
+}

package/src/types/track.ts

@@ -0,0 +1,12 @@
+import type { BaseTrack } from './buffer';
+
+export interface TrackSet {
+  audio?: Track;
+  video?: Track;
+  audiovideo?: Track;
+}
+
+export interface Track extends BaseTrack {
+  buffer?: SourceBuffer; // eslint-disable-line no-restricted-globals
+  initSegment?: Uint8Array<ArrayBuffer>;
+}