SpeechSynthesisEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SpeechSynthesisEvent extends Event

Beschreibung

SpeechSynthesisEvent ist das Ereignisobjekt, das an die Handler einer SpeechSynthesisUtterance übergeben wird. Es wird bei den Ereignissen start, end, pause, resume, boundary und mark ausgelöst. Bei Fehlern kommt stattdessen das abgeleitete SpeechSynthesisErrorEvent (Ereignis error) zum Einsatz.

Neben den geerbten Eigenschaften von Event bietet es folgende schreibgeschützte Eigenschaften:

utterance: die SpeechSynthesisUtterance, die das Ereignis ausgelöst hat.
charIndex: Zeichenposition im Text von utterance.text, an der das Ereignis eintrat.
charLength: Länge des aktuell gesprochenen Wortes bzw. Satzes (nicht in allen Engines befüllt, sonst 0).
elapsedTime: vergangene Zeit seit Beginn der Ausgabe (laut Spezifikation in Sekunden, einige Browser liefern Millisekunden).
name: bei boundary "word" oder "sentence", bei mark der Name der SSML-Marke.

Typische Einsatzfälle sind Vorlese-Funktionen mit Wort-Hervorhebung („Karaoke-Effekt“), Fortschrittsanzeigen oder das Verketten mehrerer Ausgaben nach dem end-Ereignis. Ein eigenes Objekt erzeugt man per Konstruktor nur selten, etwa für Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor `new SpeechSynthesisEvent(type, options)`: Ereignisname, z. B. `"boundary"`.
$options Pflicht	SpeechSynthesisEventInit		Objekt mit `utterance` (Pflicht) sowie optional `charIndex`, `charLength`, `elapsedTime`, `name` und den `EventInit`-Feldern.

Rückgabewert

Typ

SpeechSynthesisEvent

Beschreibung

Beim Konstruktor-Aufruf ein neues Ereignisobjekt; im Normalfall erhält man es als Argument eines Event-Handlers.

Beispiele

Start, Ende und Dauer protokollieren

const utterance = new SpeechSynthesisUtterance('Hallo und willkommen bei programmierung.net!');
utterance.lang = 'de-DE';

utterance.addEventListener('start', (event) => {
  console.log('Start:', event.type, event.utterance.text);
});

utterance.onend = (event) => {
  console.log(`Fertig nach ${event.elapsedTime.toFixed(0)} (Einheit browserabhängig)`);
};

speechSynthesis.speak(utterance);

Start: start Hallo und willkommen bei programmierung.net! Fertig nach 2840 (Einheit browserabhängig)

Aktuelles Wort per boundary hervorheben

const text = 'Die Web Speech API liest diesen Satz Wort für Wort vor.';
const output = document.querySelector('#vorlesen');
const utterance = new SpeechSynthesisUtterance(text);
utterance.lang = 'de-DE';

utterance.addEventListener('boundary', (event) => {
  if (event.name !== 'word') return;
  const start = event.charIndex;
  // charLength fehlt teils -> Wortende selbst bestimmen
  const rest = text.slice(start);
  const length = event.charLength || (rest.search(/\s|$/));
  const word = text.slice(start, start + length);
  output.innerHTML = '';
  output.append(
    text.slice(0, start),
    Object.assign(document.createElement('mark'), { textContent: word }),
    text.slice(start + length)
  );
});

utterance.addEventListener('end', () => { output.textContent = text; });
speechSynthesis.speak(utterance);

Pause/Fortsetzen mit Zeichenposition

const utterance = new SpeechSynthesisUtterance('Ein längerer Text zum Pausieren und Fortsetzen.');

utterance.onpause = (e) => console.log('Pausiert bei Zeichen', e.charIndex);
utterance.onresume = (e) => console.log('Weiter bei Zeichen', e.charIndex);

speechSynthesis.speak(utterance);
setTimeout(() => speechSynthesis.pause(), 1000);
setTimeout(() => speechSynthesis.resume(), 2500);

Pausiert bei Zeichen 13 Weiter bei Zeichen 13

Ereignis manuell erzeugen (z. B. für Tests)

const utterance = new SpeechSynthesisUtterance('Testsatz');
utterance.addEventListener('boundary', (e) => {
  console.log(e.name, e.charIndex, e.charLength);
});

const event = new SpeechSynthesisEvent('boundary', {
  utterance,
  charIndex: 0,
  charLength: 8,
  name: 'word'
});
utterance.dispatchEvent(event);

word 0 8

// Wichtig · Fallstricke

Uneinheitliche Engines: boundary-Ereignisse hängen von der gewählten Stimme ab. Viele Netz-/Cloud-Stimmen (z. B. „Google Deutsch“ in Chrome) lösen gar keine boundary-Ereignisse aus. charLength ist oft 0 oder fehlt.
elapsedTime-Einheit: Die Spezifikation nennt Sekunden, Chrome und Safari liefern teils Millisekunden. Nicht blind in Berechnungen verwenden.
mark-Ereignisse setzen SSML voraus, das die meisten Browser nicht auswerten. In der Praxis kommen sie fast nie an.
Garbage Collection: In Chrome kann eine nur lokal referenzierte Utterance vorzeitig freigegeben werden, sodass end nie ausgelöst wird. Halte deshalb eine Referenz, z. B. in einer äußeren Variable.
Fehler kommen als SpeechSynthesisErrorEvent mit der Eigenschaft error an, z. B. "interrupted" nach speechSynthesis.cancel().
Kompatibilität: Chrome, Edge, Firefox und Safari werden unterstützt. Node.js hat keine native Unterstützung.

Siehe auch

Event SpeechSynthesisErrorEvent SpeechSynthesis SpeechSynthesisVoice SpeechSynthesisUtterance