TextTrack.sourceBuffer — Eigenschaft · JavaScript-Referenz

Signatur

get TextTrack.sourceBuffer

Beschreibung

Die schreibgeschützte Eigenschaft sourceBuffer des TextTrack-Interfaces gehört zu den Media Source Extensions (MSE). Sie verweist auf den SourceBuffer, aus dessen Mediendaten der Browser den Text-Track (z. B. eingebettete Untertitel oder Captions in einem fMP4- oder WebM-Segment) erzeugt hat.

Wenn der Track auf anderem Weg entstanden ist, z. B. durch ein <track>-Element im HTML oder über HTMLMediaElement.addTextTrack(), ist der Wert null. Ebenfalls null ist er, sobald der zugehörige SourceBuffer mit MediaSource.removeSourceBuffer() aus MediaSource.sourceBuffers entfernt wurde.

Nützlich ist die Eigenschaft vor allem in adaptiven Streaming-Playern, die mehrere SourceBuffer verwalten. Damit lässt sich herausfinden, welche In-Band-Untertitel zu welchem Datenstrom gehören, und man kann Tracks gezielt ein- oder ausblenden oder beim Wechsel der Qualitätsstufe aufräumen.

Rückgabewert

Typ

SourceBuffer | null

Beschreibung

Der SourceBuffer, der den Track erzeugt hat, oder null, wenn der Track nicht aus einem SourceBuffer stammt oder dieser aus der MediaSource entfernt wurde.

Beispiele

Herkunft aller Text-Tracks prüfen

const video = document.querySelector('video');

for (const track of video.textTracks) {
  // Feature-Erkennung: Eigenschaft wird nicht überall unterstützt
  if (!('sourceBuffer' in track)) {
    console.log(`${track.label}: sourceBuffer nicht unterstützt`);
    continue;
  }
  const origin = track.sourceBuffer ? 'MSE-SourceBuffer' : 'kein SourceBuffer (z. B. <track>)';
  console.log(`${track.kind} "${track.label}" (${track.language}): ${origin}`);
}

subtitles "Deutsch" (de): MSE-SourceBuffer captions "Extern" (en): kein SourceBuffer (z. B. <track>)

In-Band-Untertitel eines bestimmten SourceBuffers anzeigen

const video = document.querySelector('video');
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);

mediaSource.addEventListener('sourceopen', async () => {
  const videoBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.64001f"');
  const data = await (await fetch('/media/init-und-segment1.mp4')).arrayBuffer();
  videoBuffer.appendBuffer(data);

  // Neue Tracks werden über das addtrack-Event gemeldet
  video.textTracks.addEventListener('addtrack', ({ track }) => {
    if (track.sourceBuffer === videoBuffer) {
      track.mode = 'showing';
      console.log('Untertitel aus videoBuffer aktiviert:', track.language);
    }
  });
});

Untertitel aus videoBuffer aktiviert: de

Nach dem Entfernen des SourceBuffers wird der Wert null

const cleanupBuffer = (mediaSource, buffer, video) => {
  const tracks = [...video.textTracks].filter((t) => t.sourceBuffer === buffer);
  mediaSource.removeSourceBuffer(buffer);

  for (const track of tracks) {
    console.log(track.label, '→', track.sourceBuffer); // jetzt null
  }
};

Deutsch → null

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Eigenschaft ist nicht Baseline. Unterstützt wird sie vor allem von Safari. Chromium-basierte Browser und Firefox bieten sie derzeit nicht an, dort ist sie undefined. Prüfe deshalb immer mit 'sourceBuffer' in track, ob sie vorhanden ist.
undefined (nicht unterstützt) und null (kein oder entfernter SourceBuffer) sind zwei verschiedene Fälle. Vergleiche nicht locker mit == null, wenn du die beiden Fälle unterscheiden musst.
Nach MediaSource.removeSourceBuffer() wird der Wert null. Speichere Verweise auf Tracks daher nicht dauerhaft in der Annahme, die Verknüpfung bleibe bestehen.
Ob In-Band-Text-Tracks überhaupt als TextTrack erscheinen, hängt vom Container und vom Browser ab (z. B. CEA-608/708 oder WebVTT in fMP4).
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert bzw. löst im Strict Mode einen TypeError aus.

Siehe auch

TextTrack SourceBuffer MediaSource SourceBuffer.textTracks AudioTrack.sourceBuffer VideoTrack.sourceBuffer MediaSource.removeSourceBuffer()