AudioData.timestamp — Eigenschaft · JavaScript-Referenz

Signatur

AudioData.timestamp

Beschreibung

Die Eigenschaft timestamp gehört zum AudioData-Interface der WebCodecs-API und ist schreibgeschützt. Sie gibt an, zu welchem Zeitpunkt das erste Sample dieses Audioblocks abgespielt werden soll. Der Wert ist eine ganze Zahl in Mikrosekunden, nicht in Sekunden und nicht in Samples.

Den Zeitstempel legst du beim Erzeugen über new AudioData({ ..., timestamp }) fest. Er kann auch von einem AudioDecoder stammen, der ihn aus dem zugehörigen EncodedAudioChunk übernimmt. Brauchst du ihn, um Audio- und Videoströme zu synchronisieren, Blöcke in der richtigen Reihenfolge zu verarbeiten oder die Zeitachse beim Muxen in einen Container (z. B. MP4 oder WebM) aufzubauen.

Zusammen mit AudioData.duration (ebenfalls in Mikrosekunden) ergibt sich das Zeitfenster eines Blocks: timestamp bis timestamp + duration. Einen lückenlosen Strom erzeugst du, indem du den Zeitstempel des nächsten Blocks aus dem Ende des vorherigen berechnest.

Beispiele

AudioData erzeugen und Zeitstempel auslesen

const sampleRate = 48000;
const numberOfFrames = 480; // 10 ms
const data = new Float32Array(numberOfFrames); // Stille, Mono

const audio = new AudioData({
  format: 'f32',
  sampleRate,
  numberOfFrames,
  numberOfChannels: 1,
  timestamp: 1_000_000, // 1 Sekunde in µs
  data
});

console.log(audio.timestamp);          // Mikrosekunden
console.log(audio.timestamp / 1e6);    // Sekunden
console.log(audio.duration);           // Dauer in µs
audio.close();

1000000 1 10000

Lückenlose Zeitstempel für aufeinanderfolgende Blöcke berechnen

const sampleRate = 44100;
const framesPerChunk = 1024;
let nextTimestamp = 0;

const createChunk = (samples) => {
  const audio = new AudioData({
    format: 'f32',
    sampleRate,
    numberOfFrames: framesPerChunk,
    numberOfChannels: 1,
    timestamp: Math.round(nextTimestamp),
    data: samples
  });
  // Ende dieses Blocks = Start des nächsten
  nextTimestamp += (framesPerChunk / sampleRate) * 1e6;
  return audio;
};

const a = createChunk(new Float32Array(framesPerChunk));
const b = createChunk(new Float32Array(framesPerChunk));
console.log(a.timestamp, b.timestamp);
a.close();
b.close();

0 23220

Ausgabe eines AudioDecoder nach Zeitstempel protokollieren

const decoder = new AudioDecoder({
  output: (audioData) => {
    const seconds = (audioData.timestamp / 1e6).toFixed(3);
    console.log(`Block bei ${seconds} s, ${audioData.numberOfFrames} Frames`);
    // ... weiterverarbeiten, danach Speicher freigeben
    audioData.close();
  },
  error: (err) => console.error('Dekodierfehler:', err)
});

decoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2
});

// encodedChunks: EncodedAudioChunk[] aus einem Demuxer
// for (const chunk of encodedChunks) decoder.decode(chunk);

Block bei 0.000 s, 960 Frames Block bei 0.020 s, 960 Frames

// Wichtig · Fallstricke

Einheit Mikrosekunden: Häufiger Fehler ist die Verwechslung mit Sekunden (wie bei AudioContext.currentTime) oder Millisekunden (wie bei performance.now()). Rechne immer mit / 1e6 bzw. * 1e6 um.
Ganzzahl: Beim Konstruktor wird der Wert in eine Ganzzahl umgewandelt. Summierst du Blockdauern auf, entstehen Rundungsfehler. Führe deshalb besser einen Sample-Zähler und rechne daraus jeweils neu: Math.round(samples / sampleRate * 1e6).
Schreibgeschützt: Eine Zuweisung an audio.timestamp wird ignoriert (im Strict Mode gibt es einen TypeError). Einen neuen Zeitstempel bekommst du nur, wenn du ein neues AudioData-Objekt erzeugst.
Rufe nach der Verarbeitung immer close() auf. Danach sind die Audiodaten freigegeben, und du solltest das Objekt nicht mehr verwenden.
Kompatibilität: WebCodecs funktioniert nur in sicheren Kontexten (HTTPS) und steht in Fenstern sowie in Dedicated Workern zur Verfügung. Chromium-Browser unterstützen es ab Version 94, Firefox ab 130. In Safari ist die Unterstützung für Audio begrenzt. Prüfe die Verfügbarkeit mit 'AudioData' in globalThis.

Siehe auch

AudioData AudioData.duration AudioData.sampleRate AudioData.numberOfFrames AudioData.close() AudioDecoder EncodedAudioChunk.timestamp VideoFrame.timestamp