Allow removing TextTracks created by hls.js (video-dev#7515)

* allow removing text tracks

* add unit tests for id3 track controller

* fix textTracks may loss existing cues on Safari

Author: xxoo

api-extractor/report/hls.js.api.md

@@ -4015,7 +4015,6 @@ export interface MediaKeySessionContext {
 export type MediaOverrides = {
     duration?: number;
     endOfStream?: boolean;
-    cueRemoval?: boolean;
 };
 
 // Warning: (ae-missing-release-tag) "MediaPlaylist" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -4057,6 +4056,8 @@ export interface MediaPlaylist {
     // (undocumented)
     textCodec?: string;
     // (undocumented)
+    trackNode?: HTMLTrackElement;
+    // (undocumented)
     type: MediaPlaylistType | 'main';
     // (undocumented)
     unknownCodecs?: string[];

demo/main.js

@@ -43,7 +43,7 @@ let stopOnStall = getDemoConfigPropOrDefault('stopOnStall', false);
 let bufferingIdx = -1;
 let selectedTestStream = null;
 
-let video = document.querySelector('#video');
+const video = document.querySelector('#video');
 const startTime = Date.now();
 
 let lastSeekingIdx;
@@ -222,6 +222,7 @@ $(document).ready(function () {
   $('#metricsButtonWindow').toggle(self.windowSliding);
   $('#metricsButtonFixed').toggle(!self.windowSliding);
 
+  addVideoEventListeners(video);
   loadSelectedStream();
 
   let tabIndexesCSV = localStorage.getItem(STORAGE_KEYS.demo_tabs);
@@ -353,32 +354,7 @@ function loadSelectedStream() {
 
   logStatus('Loading manifest and attaching video element...');
 
-  const expiredTracks = [].filter.call(
-    video.textTracks,
-    (track) => track.kind !== 'metadata'
-  );
-  if (expiredTracks.length) {
-    const kinds = expiredTracks
-      .map((track) => track.kind)
-      .filter((kind, index, self) => self.indexOf(kind) === index);
-    logStatus(
-      `Replacing video element to remove ${kinds.join(' and ')} text tracks`
-    );
-    const videoWithExpiredTextTracks = video;
-    video = videoWithExpiredTextTracks.cloneNode(false);
-    video.removeAttribute('src');
-    video.volume = videoWithExpiredTextTracks.volume;
-    video.muted = videoWithExpiredTextTracks.muted;
-    videoWithExpiredTextTracks.parentNode.insertBefore(
-      video,
-      videoWithExpiredTextTracks
-    );
-    videoWithExpiredTextTracks.parentNode.removeChild(
-      videoWithExpiredTextTracks
-    );
-  }
   addChartEventListeners(hls);
-  addVideoEventListeners(video);
 
   hls.loadSource(url);
   hls.autoLevelCapping = levelCapping;

src/controller/buffer-controller.ts

@@ -544,8 +544,6 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
       }
       this.media = null;
     }
-
-    this.hls.trigger(Events.MEDIA_DETACHED, data);
   }
 
   private onBufferReset() {

src/controller/id3-track-controller.ts

@@ -8,11 +8,7 @@ import {
 import { MetadataSchema } from '../types/demuxer';
 import { hexToArrayBuffer } from '../utils/hex';
 import { stringify } from '../utils/safe-json-stringify';
-import {
-  clearCurrentCues,
-  removeCuesInRange,
-  sendAddTrackEvent,
-} from '../utils/texttrack-utils';
+import { createTrackNode, removeCuesInRange } from '../utils/texttrack-utils';
 import type { MediaFragment } from '../hls';
 import type Hls from '../hls';
 import type { DateRange } from '../loader/date-range';
@@ -77,7 +73,7 @@ const MAX_CUE_ENDTIME = (() => {
 
 class ID3TrackController implements ComponentAPI {
   private hls: Hls | null;
-  private id3Track: TextTrack | null = null;
+  private id3Track: HTMLTrackElement | null = null;
   private media: HTMLMediaElement | null = null;
   private dateRangeCuesAppended: Record<
     string,
@@ -146,9 +142,6 @@ class ID3TrackController implements ComponentAPI {
     data: MediaAttachingData,
   ): void {
     this.media = data.media;
-    if (data.overrides?.cueRemoval === false) {
-      this.removeCues = false;
-    }
   }
 
   private onMediaAttached() {
@@ -168,9 +161,7 @@ class ID3TrackController implements ComponentAPI {
       return;
     }
     if (this.id3Track) {
-      if (this.removeCues) {
-        clearCurrentCues(this.id3Track, this.onEventCueEnter);
-      }
+      this.id3Track.remove();
       this.id3Track = null;
     }
     this.dateRangeCuesAppended = {};
@@ -180,27 +171,8 @@ class ID3TrackController implements ComponentAPI {
     this.dateRangeCuesAppended = {};
   }
 
-  private createTrack(media: HTMLMediaElement): TextTrack {
-    const track = this.getID3Track(media.textTracks) as TextTrack;
-    track.mode = 'hidden';
-    return track;
-  }
-
-  private getID3Track(textTracks: TextTrackList): TextTrack | void {
-    if (!this.media) {
-      return;
-    }
-    for (let i = 0; i < textTracks.length; i++) {
-      const textTrack: TextTrack = textTracks[i];
-      if (textTrack.kind === 'metadata' && textTrack.label === 'id3') {
-        // send 'addtrack' when reusing the textTrack for metadata,
-        // same as what we do for captions
-        sendAddTrackEvent(textTrack, this.media);
-
-        return textTrack;
-      }
-    }
-    return this.media.addTextTrack('metadata', 'id3');
+  private createTrack(media: HTMLMediaElement): HTMLTrackElement {
+    return createTrackNode(media, 'metadata', 'id3', '', 'hidden');
   }
 
   private onFragParsingMetadata(
@@ -264,15 +236,15 @@ class ID3TrackController implements ComponentAPI {
             type,
           );
           if (cue) {
-            this.id3Track.addCue(cue);
+            this.id3Track.track.addCue(cue);
           }
         }
       }
     }
   }
 
   private updateId3CueEnds(startTime: number, type: MetadataSchema) {
-    const cues = this.id3Track?.cues;
+    const cues = this.id3Track?.track.cues;
     if (cues) {
       for (let i = cues.length; i--; ) {
         const cue = cues[i] as any;
@@ -315,7 +287,7 @@ class ID3TrackController implements ComponentAPI {
             enableID3MetadataCues) ||
           ((cue as any).type === MetadataSchema.emsg && enableEmsgMetadataCues);
       }
-      removeCuesInRange(id3Track, startOffset, endOffset, predicate);
+      removeCuesInRange(id3Track.track, startOffset, endOffset, predicate);
     }
   }
 
@@ -372,7 +344,7 @@ class ID3TrackController implements ComponentAPI {
         if (cue) {
           cue.id = assetPlayerId;
           this.id3Track ||= this.createTrack(this.media);
-          this.id3Track.addCue(cue);
+          this.id3Track.track.addCue(cue);
           cue.addEventListener('enter', this.onEventCueEnter);
         }
       }
@@ -387,7 +359,7 @@ class ID3TrackController implements ComponentAPI {
     let dateRangeCuesAppended = this.dateRangeCuesAppended;
     // Remove cues from track not found in details.dateRanges
     if (id3Track && removeOldCues) {
-      if (id3Track.cues?.length) {
+      if (id3Track.track.cues?.length) {
         const idsToRemove = Object.keys(dateRangeCuesAppended).filter(
           (id) => !ids.includes(id),
         );
@@ -401,7 +373,7 @@ class ID3TrackController implements ComponentAPI {
               if (cue) {
                 cue.removeEventListener('enter', this.onEventCueEnter);
                 try {
-                  id3Track.removeCue(cue);
+                  id3Track.track.removeCue(cue);
                 } catch (e) {
                   /* no-op */
                 }
@@ -492,7 +464,7 @@ class ID3TrackController implements ComponentAPI {
           );
           if (cue) {
             cue.id = id;
-            this.id3Track.addCue(cue);
+            this.id3Track.track.addCue(cue);
             cues[key] = cue;
             if (__USE_INTERSTITIALS__ && interstitialsController) {
               if (key === 'X-ASSET-LIST' || key === 'X-ASSET-URL') {

src/controller/interstitials-controller.ts

@@ -871,7 +871,6 @@ export default class InterstitialsController
       dataToAttach.overrides = {
         duration: schedule.duration,
         endOfStream: !isAssetPlayer || isAssetAtEndOfSchedule,
-        cueRemoval: !isAssetPlayer,
       };
     }
     player.attachMedia(dataToAttach);