new SpeechSynthesisEvent() — Methode · JavaScript-Referenz

Signatur

new SpeechSynthesisEvent(type, options)

Beschreibung

Der Konstruktor SpeechSynthesisEvent() erzeugt ein Ereignisobjekt der Web Speech API. Solche Ereignisse löst der Browser normalerweise selbst auf einer SpeechSynthesisUtterance aus, etwa start, end, pause, resume, mark und boundary. Das Ereignis enthält Angaben dazu, welche Äußerung betroffen ist, an welcher Zeichenposition die Ausgabe gerade steht und wie viel Zeit seit Beginn vergangen ist.

Im Alltag braucht man den Konstruktor kaum, weil die Sprachsynthese ihre Ereignisse selbst erzeugt. Nützlich ist er aber, wenn man Ereignisbehandler testen will, ohne wirklich Sprache auszugeben (etwa in Unit-Tests oder beim Debuggen einer Wort-Hervorhebung). Man kann damit auch eine Wiedergabe simulieren, wenn keine Stimmen verfügbar sind.

Das Optionsobjekt utterance ist Pflicht. Alle anderen Felder haben Standardwerte. Zusätzlich gelten die üblichen Event-Optionen bubbles, cancelable und composed. Ein selbst erzeugtes Ereignis steuert die Sprachausgabe nicht: Es wird nur an die registrierten Behandler verteilt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"start"`, `"end"`, `"pause"`, `"resume"`, `"mark"` oder `"boundary"`.
$options Pflicht	object		Objekt zur Konfiguration des Ereignisses. Zusätzlich zu den unten genannten Feldern sind die `Event`-Optionen `bubbles`, `cancelable` und `composed` erlaubt.
$options.utterance Pflicht	SpeechSynthesisUtterance		Die Äußerung, auf die sich das Ereignis bezieht. Fehlt sie, wird ein `TypeError` geworfen.
$options.charIndex	number	0	Position des Zeichens im Text der Äußerung, an der das Ereignis eintritt.
$options.charLength	number	0	Anzahl der Zeichen, die ab `charIndex` gesprochen werden (z. B. Länge des aktuellen Wortes).
$options.elapsedTime	number	0	Vergangene Zeit seit Beginn der Äußerung, angegeben in Sekunden (float).
$options.name	string	""	Bei `mark` der Name der SSML-Marke, bei `boundary` die Art der Grenze (`"word"` oder `"sentence"`).

Rückgabewert

Typ

SpeechSynthesisEvent

Beschreibung

Ein neues SpeechSynthesisEvent-Objekt mit den übergebenen Werten. Seine Eigenschaft isTrusted ist false.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

const utterance = new SpeechSynthesisUtterance('Hallo Welt');

const event = new SpeechSynthesisEvent('boundary', {
  utterance,
  charIndex: 6,
  charLength: 4,
  elapsedTime: 0.42,
  name: 'word'
});

console.log(event.type, event.charIndex, event.charLength, event.name);
console.log(event.utterance.text.substr(event.charIndex, event.charLength));
console.log(event.isTrusted);

boundary 6 4 word Welt false

Wort-Hervorhebung ohne echte Sprachausgabe testen

const text = 'Guten Morgen liebe Leser';
const utterance = new SpeechSynthesisUtterance(text);

const highlight = (e) => {
  const word = text.slice(e.charIndex, e.charIndex + e.charLength);
  console.log(`Aktuelles Wort: ${word}`);
};

utterance.addEventListener('boundary', highlight);

// Browser-Ereignisse nachbilden
const words = [...text.matchAll(/\S+/g)];
for (const m of words) {
  utterance.dispatchEvent(new SpeechSynthesisEvent('boundary', {
    utterance,
    charIndex: m.index,
    charLength: m[0].length,
    name: 'word'
  }));
}

utterance.removeEventListener('boundary', highlight);

Aktuelles Wort: Guten Aktuelles Wort: Morgen Aktuelles Wort: liebe Aktuelles Wort: Leser

Ende einer Äußerung simulieren (onend-Property)

const utterance = new SpeechSynthesisUtterance('Fertig.');

utterance.onend = (e) => {
  console.log(`Ende nach ${e.elapsedTime.toFixed(1)} s`);
};

// z. B. als Ersatz, wenn keine Stimme verfügbar ist
if (speechSynthesis.getVoices().length === 0) {
  utterance.dispatchEvent(
    new SpeechSynthesisEvent('end', { utterance, elapsedTime: 1.2 })
  );
}

Ende nach 1.2 s

// Wichtig · Fallstricke

Pflichtfeld utterance: Ohne dieses Feld wirft der Konstruktor einen TypeError. Auch das Optionsobjekt selbst darf nicht fehlen.
Keine Wirkung auf die Sprachausgabe: dispatchEvent() ruft nur die Behandler auf. Die Wiedergabe wird dadurch weder gestartet noch angehalten oder beendet. Dafür sind speechSynthesis.speak(), pause() und cancel() zuständig.
isTrusted ist false: Code, der nur echte Browser-Ereignisse zulässt, ignoriert selbst erzeugte Ereignisse.
Fehlerereignisse: Für error gibt es die Unterklasse SpeechSynthesisErrorEvent mit der zusätzlichen Eigenschaft error.
elapsedTime: Die Einheit war früher je nach Browser unterschiedlich (manche Browser nutzten Millisekunden). Laut Spezifikation sind es Sekunden.
Kompatibilität: Der Konstruktor funktioniert in aktuellen Versionen von Chrome, Edge, Firefox und Safari. In Node.js gibt es die Web Speech API nicht. Für Tests in jsdom braucht man eigene Polyfills oder Mocks.

Siehe auch

new ExtendableEvent() new SpeechSynthesisErrorEvent() new SpeechSynthesisUtterance() new SpeechRecognitionEvent() new HashChangeEvent()