SpeechSynthesis.cancel() — Methode · JavaScript-Referenz

Signatur

SpeechSynthesis.prototype.cancel()

Beschreibung

Die Methode cancel() der Schnittstelle SpeechSynthesis (erreichbar über window.speechSynthesis) leert die komplette Warteschlange der Sprachausgabe. Wird gerade eine Äußerung gesprochen, bricht sie sofort ab. Alle Äußerungen, die noch warten, werden verworfen und nicht mehr gesprochen.

Typische Einsatzfälle sind ein „Stopp“-Knopf in Vorlese-Funktionen, das Abbrechen einer alten Ausgabe, bevor ein neuer Text gesprochen wird, und das Aufräumen, wenn der Nutzer die Seite oder Ansicht wechselt. Im Gegensatz zu pause() lässt sich eine abgebrochene Ausgabe nicht mit resume() fortsetzen.

Für die abgebrochene, gerade laufende Äußerung löst der Browser ein error-Ereignis mit event.error === "interrupted" oder "canceled" aus. Je nach Browser kann stattdessen auch ein end-Ereignis kommen. Ereignisbehandler sollten beide Fälle abdecken.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Vorlesen starten und per Knopf stoppen

const speakBtn = document.querySelector('#speak');
const stopBtn = document.querySelector('#stop');

speakBtn.addEventListener('click', () => {
  const text = document.querySelector('#text').value;
  const utterance = new SpeechSynthesisUtterance(text);
  utterance.lang = 'de-DE';
  speechSynthesis.speak(utterance);
});

stopBtn.addEventListener('click', () => {
  // Bricht die laufende Ausgabe ab und leert die Warteschlange
  speechSynthesis.cancel();
  console.log('Sprechend:', speechSynthesis.speaking);
});

Sprechend: false

Alte Ausgabe ersetzen statt anhängen

const say = (text) => {
  // Ohne cancel() würde der neue Text hinten in die Warteschlange gestellt
  speechSynthesis.cancel();
  const u = new SpeechSynthesisUtterance(text);
  u.lang = 'de-DE';
  speechSynthesis.speak(u);
};

say('Erste Meldung, die ziemlich lang ist ...');
setTimeout(() => say('Neue, wichtigere Meldung!'), 1000);

Abbruch im Fehler-Handler erkennen

const u = new SpeechSynthesisUtterance('Dieser Satz wird gleich unterbrochen.');

u.addEventListener('error', (event) => {
  if (event.error === 'interrupted' || event.error === 'canceled') {
    console.log('Ausgabe wurde abgebrochen');
  } else {
    console.error('Fehler bei der Sprachausgabe:', event.error);
  }
});
u.addEventListener('end', () => console.log('end-Ereignis'));

speechSynthesis.speak(u);
setTimeout(() => speechSynthesis.cancel(), 500);

Ausgabe wurde abgebrochen

Aufräumen beim Verlassen der Seite

window.addEventListener('pagehide', () => {
  if (speechSynthesis.speaking || speechSynthesis.pending) {
    speechSynthesis.cancel();
  }
});

// Wichtig · Fallstricke

Nicht fortsetzbar: Nach cancel() hat resume() keine Wirkung. Zum vorübergehenden Anhalten ist pause() gedacht.
Uneinheitliche Ereignisse: Chrome meldet einen Abbruch meist mit error ("interrupted"), andere Browser teilweise mit end. Logik wie „nächsten Satz sprechen“ im end-Handler sollte ein eigenes Abbruch-Flag prüfen, sonst läuft die Ausgabe ungewollt weiter.
Chrome-Eigenheit: Wenn speak() direkt nach cancel() aufgerufen wird, wurde die neue Äußerung in einigen Versionen verschluckt. Abhilfe schafft ein kurzes setTimeout zwischen beiden Aufrufen.
Global: cancel() wirkt auf die gesamte Warteschlange der Seite, nicht nur auf eine einzelne Äußerung. Einzelne Äußerungen lassen sich nicht gezielt entfernen.
Feature-Erkennung: Vor der Nutzung mit 'speechSynthesis' in window prüfen. Die Web Speech API gibt es in Browsern, aber nicht in Node.js.

Siehe auch

new SpeechRecognitionEvent() SpeechSynthesis.pause() SpeechSynthesis.resume() SpeechSynthesis.speak() SpeechSynthesis.getVoices()