TextTrack.removeCue() — Methode · JavaScript-Referenz

Signatur

TextTrack.prototype.removeCue(cue)

Beschreibung

Mit removeCue() nehmen Sie einen einzelnen Cue wieder aus einer TextTrack heraus. Ein Cue ist ein Textabschnitt mit Start- und Endzeit. Die Methode ist das Gegenstück zu TextTrack.addCue(). Sie brauchen sie vor allem bei Textspuren, die per JavaScript erzeugt werden, etwa über HTMLMediaElement.addTextTrack() oder bei Untertiteln, die live nachgeladen werden.

Typische Einsatzfälle sind:

ein falscher Untertitel soll korrigiert werden: alten Cue entfernen, neuen einfügen,
abgelaufene Cues bei einem Live-Stream aufräumen, damit der Speicher nicht vollläuft,
eine Spur komplett leeren, bevor Untertiteln in einer anderen Sprache geladen werden.

Übergeben wird das Cue-Objekt selbst, nicht seine ID und nicht sein Index. Passende Objekte finden Sie über track.cues, zum Beispiel mit track.cues.getCueById(id). Ist der Cue gerade sichtbar, blendet der Browser ihn nach dem Entfernen sofort aus. Außerdem werden track.cues und track.activeCues automatisch aktualisiert.

Parameter

Name	Typ	Default	Beschreibung
$cue Pflicht	TextTrackCue \| VTTCue		Das Cue-Objekt, das aus der Spur entfernt werden soll. Es muss zur Cue-Liste dieser Spur gehören.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Gehört der Cue nicht zu dieser Spur, wird eine DOMException vom Typ NotFoundError ausgelöst.

Beispiele

Einzelnen Untertitel über seine ID entfernen

const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

const cue = new VTTCue(0, 4, 'Hallo und willkommen!');
cue.id = 'intro';
track.addCue(cue);
track.addCue(new VTTCue(4, 8, 'Heute geht es um TextTracks.'));

// Cue anhand der ID suchen und entfernen
const intro = track.cues.getCueById('intro');
if (intro) {
  track.removeCue(intro);
}
console.log(track.cues.length);

1

Alle Cues einer Spur entfernen

const clearTrack = (track) => {
  // cues ist eine Live-Liste: rückwärts durchlaufen,
  // sonst werden beim Entfernen Einträge übersprungen
  const { cues } = track;
  if (!cues) return; // Spur ist deaktiviert (mode = 'disabled')
  for (let i = cues.length - 1; i >= 0; i--) {
    track.removeCue(cues[i]);
  }
};

const video = document.querySelector('video');
const track = video.textTracks[0];
clearTrack(track);
console.log(track.cues.length);

Abgelaufene Live-Untertitel aufräumen

const video = document.querySelector('video');
const liveTrack = video.addTextTrack('captions', 'Live', 'de');
liveTrack.mode = 'showing';

// Cues, die länger als 60 Sekunden vorbei sind, entfernen
video.addEventListener('timeupdate', () => {
  const limit = video.currentTime - 60;
  const expired = Array.from(liveTrack.cues ?? [])
    .filter((cue) => cue.endTime < limit);
  expired.forEach((cue) => liveTrack.removeCue(cue));
});

NotFoundError sicher abfangen

const video = document.querySelector('video');
const trackA = video.addTextTrack('subtitles', 'A', 'de');
const trackB = video.addTextTrack('subtitles', 'B', 'en');

const cue = new VTTCue(0, 2, 'Nur in Spur A');
trackA.addCue(cue);

try {
  trackB.removeCue(cue); // gehört nicht zu trackB
} catch (err) {
  console.log(err.name);
}

NotFoundError

// Wichtig · Fallstricke

NotFoundError: Gehört der Cue nicht zu dieser Spur, weil er schon entfernt wurde oder zu einer anderen Spur gehört, löst die Methode eine DOMException vom Typ NotFoundError aus. Prüfen Sie vorher mit cue.track === track oder fangen Sie den Fehler mit try/catch ab.
Live-Liste: track.cues ist eine TextTrackCueList, die sich sofort ändert. Wenn Sie die Liste vorwärts durchlaufen und dabei Cues entfernen, werden Einträge übersprungen. Durchlaufen Sie die Liste deshalb rückwärts oder kopieren Sie sie vorher mit Array.from().
Deaktivierte Spuren: Bei mode = 'disabled' ist track.cues gleich null. Um Cues zu finden, muss die Spur mindestens auf 'hidden' stehen.
Cues aus <track>-Elementen: Cues, die aus einer WebVTT-Datei geladen wurden, können Sie ebenfalls entfernen. Die Änderung gilt aber nur im Arbeitsspeicher; lädt der Browser die Datei neu, sind die Cues wieder da.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Sehr alte Browser (vor IE 10) kennen die Methode nicht.

Siehe auch

TextTrack.addCue() Storage.removeItem() new TrackEvent() Element.remove() TextDecoder.decode()