TextTrack

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Das TextTrack-Interface der WebVTT API repräsentiert eine Textspur, die mit einem Medienelement verknüpft ist.

Ein Objekt dieses Typs enthält die Liste von VTTCue-Objekten, die zu verschiedenen Zeitpunkten über dem Video angezeigt werden.

TextTrack-Objekte können einem HTMLVideoElement oder HTMLAudioElement Element mithilfe der Methode HTMLMediaElement.addTextTrack() hinzugefügt werden, was den gleichen Effekt hat wie das deklarative Hinzufügen von Textspuren durch Verwendung von <track>-Elementen innerhalb eines <video>- oder <audio>-Elements. Die TextTrack-Objekte werden in einer TextTrackList gespeichert, die über die Eigenschaft HTMLMediaElement.textTracks abgerufen werden kann.

Instanz-Eigenschaften

Dieses Interface erbt auch Eigenschaften von EventTarget.

TextTrack.activeCues Schreibgeschützt: Ein TextTrackCueList-Objekt, das die aktuell aktiven Textspurkriterien auflistet. Spur-Kriterien sind aktiv, wenn die aktuelle Wiedergabeposition des Mediums zwischen den Start- und Endzeiten der Kriterien liegt. Für angezeigte Kriterien wie Untertitel oder Untertitelungen werden die aktiven Kriterien derzeit angezeigt.
TextTrack.cues Schreibgeschützt: Eine TextTrackCueList, die alle Kriterien der Spur enthält.
TextTrack.id Schreibgeschützt: Eine Zeichenkette, die die Spur identifiziert, falls sie eine besitzt. Wenn sie keine ID besitzt, ist dieser Wert eine leere Zeichenkette (""). Wenn das TextTrack mit einem <track>-Element verknüpft ist, stimmt die Spur-ID mit der ID des Elements überein.
TextTrack.inBandMetadataTrackDispatchType Schreibgeschützt: Gibt eine Zeichenkette zurück, die den In-Band-Metadaten-Spurdispatch-Typ der Spur angibt.
TextTrack.kind Schreibgeschützt: Gibt eine Zeichenkette zurück, die die Art der Textspur beschreibt, die das TextTrack darstellt. Es muss einer der zulässigen Werte sein.
TextTrack.label Schreibgeschützt: Eine menschenlesbare Zeichenkette, die das Label der Textspur enthält, falls vorhanden; ansonsten ist dies eine leere Zeichenkette (""), in welchem Fall möglicherweise ein benutzerdefiniertes Label von Ihrem Code unter Verwendung anderer Attribute der Spur generiert werden muss, falls das Label der Spur dem Benutzer angezeigt werden muss.
TextTrack.language Schreibgeschützt: Eine Zeichenkette, die die Sprache angibt, in der der Inhalt der Textspur verfasst ist. Der Wert muss dem in RFC 5646: Tags for Identifying Languages (also known as BCP 47) spezifizierten Format entsprechen, genauso wie das HTML-lang-Attribut. Zum Beispiel kann dies "en-US" für US-Englisch oder "pt-BR" für brasilianisches Portugiesisch sein.
TextTrack.mode: Eine Zeichenkette, die den aktuellen Modus der Spur angibt, der einer der zulässigen Werte sein muss. Die Änderung des Wertes dieser Eigenschaft ändert den aktuellen Modus der Spur entsprechend. Der Standardwert ist disabled, es sei denn, das default-Boolean-Attribut des <track>-Elements ist auf true gesetzt — in diesem Fall ist der Standardmodus showing.
sourceBuffer Schreibgeschützt: Der SourceBuffer, der die Spur erstellt hat. Gibt null zurück, wenn die Spur nicht von einem SourceBuffer erstellt wurde oder wenn der SourceBuffer aus dem MediaSource.sourceBuffers-Attribut seiner übergeordneten Medienquelle entfernt wurde.

Instanz-Methoden

Dieses Interface erbt auch Methoden von EventTarget.

Hinweis: Das Interface TextTrackCue ist eine abstrakte Klasse, die als Elternteil für andere Kriterien-Interfaces wie VTTCue dient. Daher werden bei der Hinzufügung oder Entfernung eines Kriteriums eine der Kriterienarten übergeben, die von TextTrackCue erben.

TextTrack.addCue(): Fügt ein Kriterium (als TextTrackCue-Objekt angegeben) zur Liste der Kriterien der Spur hinzu.
TextTrack.removeCue(): Entfernt ein Kriterium (als TextTrackCue-Objekt angegeben) aus der Liste der Kriterien der Spur.

Ereignisse

cuechange: Wird ausgelöst, wenn Kriterien betreten und verlassen werden. Ein bestimmtes Text-Kriterium erscheint, wenn das Kriterium betreten wird, und verschwindet, wenn das Kriterium verlassen wird. Auch über die oncuechange-Eigenschaft verfügbar.

Beispiel

Das folgende Beispiel fügt einem Video eine neue TextTrack-Spur hinzu und stellt sie dann zur Anzeige über TextTrack.mode ein.

let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

Spezifikationen

Specification
HTML # texttrack