EncodedAudioChunk.timestamp — Eigenschaft · JavaScript-Referenz

Signatur

EncodedAudioChunk.timestamp

Beschreibung

Die Eigenschaft timestamp eines EncodedAudioChunk gibt an, zu welchem Zeitpunkt die im Chunk enthaltenen Audiodaten abgespielt werden sollen. Der Wert ist eine ganze Zahl in Mikrosekunden (1 s = 1 000 000 µs) und kann auch negativ sein, etwa bei Encoder-Vorlauf (Priming).

Der Zeitstempel wird beim Erzeugen des Chunks festgelegt: entweder über das Feld timestamp im Init-Objekt des Konstruktors new EncodedAudioChunk(init) oder automatisch durch einen AudioEncoder, der ihn aus dem timestamp der zugehörigen AudioData übernimmt. Danach lässt er sich nicht mehr ändern.

Gebraucht wird der Wert vor allem beim Muxen (Verpacken in Container wie MP4 oder WebM), beim Synchronisieren von Audio und Video und beim Umsetzen von Suchfunktionen. Ein AudioDecoder reicht den Zeitstempel an die ausgegebenen AudioData-Objekte weiter, sodass die zeitliche Zuordnung durch die ganze Pipeline erhalten bleibt.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl (intern long long), die den Präsentationszeitstempel in Mikrosekunden angibt. Kann negativ sein.

Beispiele

Chunk erzeugen und Zeitstempel auslesen

// Rohdaten eines Opus-Pakets (hier nur Platzhalter-Bytes)
const data = new Uint8Array([0xfc, 0xff, 0xfe]);

const chunk = new EncodedAudioChunk({
  type: 'key',
  timestamp: 1_500_000, // 1,5 Sekunden
  duration: 20_000,     // 20 ms
  data
});

console.log(chunk.timestamp);
console.log(`${chunk.timestamp / 1e6} s`);

1500000 1.5 s

Zeitstempel der Encoder-Ausgabe protokollieren

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    const ms = (chunk.timestamp / 1000).toFixed(1);
    console.log(`Chunk @ ${ms} ms, ${chunk.byteLength} Bytes`);
  },
  error: (e) => console.error('Encoder-Fehler:', e)
});

encoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 1,
  bitrate: 64000
});

// 20 ms Stille als AudioData erzeugen
const frames = 960;
const audio = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: frames,
  numberOfChannels: 1,
  timestamp: 0,
  data: new Float32Array(frames)
});

encoder.encode(audio);
audio.close();
await encoder.flush();

Chunk @ 0.0 ms, 3 Bytes (Bytegröße variiert)

Chunks für einen Suchvorgang filtern

// Alle Chunks ab einer Zielzeit an den Decoder übergeben
const seekTo = (chunks, decoder, seconds) => {
  const target = Math.round(seconds * 1e6);
  const start = chunks.findLastIndex((c) => c.timestamp <= target);
  for (const chunk of chunks.slice(Math.max(start, 0))) {
    decoder.decode(chunk);
  }
};

// Beispielaufruf: seekTo(allChunks, audioDecoder, 12.3);

// Wichtig · Fallstricke

Einheit beachten: Der Wert ist in Mikrosekunden angegeben, nicht in Millisekunden oder Sekunden. HTMLMediaElement.currentTime und AudioContext.currentTime arbeiten in Sekunden – umrechnen mit / 1e6.
Schreibgeschützt: Eine Zuweisung wie chunk.timestamp = 0 wird ignoriert (im Strict Mode gibt es einen TypeError). Für einen anderen Zeitstempel musst du einen neuen Chunk anlegen und die Daten vorher mit copyTo() herauskopieren.
Container verwenden oft andere Zeitbasen (z. B. 1/48000 bei MP4-Audio-Tracks). Beim Muxen/Demuxen sorgfältig umrechnen und runden, damit sich Rundungsfehler nicht aufsummieren.
Negative Werte sind erlaubt (z. B. bei Codec-Vorlauf) und sollten nicht als Fehler behandelt werden.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Workern. Vor der Nutzung mit 'EncodedAudioChunk' in globalThis prüfen.

Siehe auch

EncodedAudioChunk EncodedAudioChunk.duration EncodedAudioChunk.type EncodedAudioChunk.byteLength EncodedAudioChunk.copyTo() AudioData.timestamp AudioEncoder AudioDecoder EncodedVideoChunk.timestamp