HTMLMediaElement.preservesPitch — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.preservesPitch

Beschreibung

Mit preservesPitch bestimmen Sie, wie sich ein <audio>- oder <video>-Element verhält, wenn Sie die Wiedergabegeschwindigkeit über playbackRate ändern. Beim Standardwert true gleicht der Browser die Tonhöhe per Time-Stretching aus: Die Wiedergabe wird schneller oder langsamer, klingt aber in derselben Tonlage. Bei false ändert sich die Tonhöhe proportional zur Geschwindigkeit. Das klingt dann wie ein zu schnell oder zu langsam abgespielter Plattenspieler, also bei 2× höher („Micky-Maus-Effekt“) und bei 0,5× tiefer.

In der Praxis ist true ideal für Podcasts, Vorlesungen, Hörbücher und Lernvideos, bei denen Nutzer schneller oder langsamer hören wollen, ohne dass die Stimmen verzerrt klingen. false eignet sich für kreative Anwendungen wie DJ-Tools, Sampler, Spieleffekte (z. B. „Zeitlupe“ mit tiefem Klang) oder wenn Sie das Verhalten klassischer Bandmaschinen nachbilden wollen.

Die Eigenschaft kann jederzeit gelesen und gesetzt werden, auch während der Wiedergabe. Die Änderung gilt sofort. Bei playbackRate = 1 hat sie keine hörbare Wirkung.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	true	Beim Setzen: `true` behält die Tonhöhe bei Geschwindigkeitsänderungen bei, `false` lässt sie mit der Geschwindigkeit steigen oder sinken.

Beispiele

Podcast schneller abspielen ohne Stimmverzerrung

const player = document.querySelector('audio');

// Standard ist true, hier zur Verdeutlichung explizit gesetzt
player.preservesPitch = true;
player.playbackRate = 1.5;

console.log(player.preservesPitch, player.playbackRate);

true 1.5

Plattenspieler-Effekt: Tonhöhe folgt der Geschwindigkeit

const video = document.querySelector('video');

const slowMotion = () => {
  video.preservesPitch = false; // Ton wird tiefer
  video.playbackRate = 0.5;
};

const normal = () => {
  video.preservesPitch = true;
  video.playbackRate = 1;
};

document.querySelector('#slowmo').addEventListener('click', slowMotion);
document.querySelector('#normal').addEventListener('click', normal);

Browserübergreifend setzen, inklusive älterer Präfix-Varianten

const setPreservesPitch = (media, value) => {
  if ('preservesPitch' in media) {
    media.preservesPitch = value;
  } else if ('mozPreservesPitch' in media) {
    media.mozPreservesPitch = value;     // ältere Firefox-Versionen
  } else if ('webkitPreservesPitch' in media) {
    media.webkitPreservesPitch = value;  // ältere Safari-Versionen
  } else {
    console.warn('preservesPitch wird nicht unterstützt');
  }
};

const audio = new Audio('beat.mp3');
setPreservesPitch(audio, false);
audio.playbackRate = 1.25;
await audio.play();

Umschalter für Tonhöhenkorrektur in einer Benutzeroberfläche

const audio = document.querySelector('audio');
const toggle = document.querySelector('#pitch-toggle'); // <input type="checkbox">

toggle.checked = audio.preservesPitch;
toggle.addEventListener('change', () => {
  audio.preservesPitch = toggle.checked;
  console.log(`Tonhöhenkorrektur: ${audio.preservesPitch ? 'an' : 'aus'}`);
});

Tonhöhenkorrektur: aus

// Wichtig · Fallstricke

Kompatibilität: Ohne Präfix verfügbar ab Chrome/Edge 86, Firefox 101 und Safari 17. Ältere Firefox-Versionen kennen nur mozPreservesPitch, ältere Safari-Versionen nur webkitPreservesPitch. Prüfen Sie daher vor dem Setzen mit 'preservesPitch' in element, ob die Eigenschaft vorhanden ist.
Wenn Sie eine nicht unterstützte Eigenschaft setzen, wird kein Fehler geworfen. Das Element bekommt nur eine gewöhnliche JS-Eigenschaft, die nichts bewirkt.
Die Qualität der Tonhöhenkorrektur hängt vom Browser ab. Bei extremen Werten für playbackRate (etwa unter 0,5 oder über 2) können Artefakte hörbar werden. Außerdem schalten manche Browser den Ton außerhalb eines bestimmten Bereichs ganz stumm.
Die Eigenschaft gibt es nur im DOM, nicht als HTML-Attribut. Sie müssen sie also per Skript setzen.
Für eine präzise Tonhöhenverschiebung unabhängig von der Geschwindigkeit brauchen Sie die Web Audio API (z. B. AudioBufferSourceNode.detune).

Siehe auch

HTMLMediaElement.playbackRate HTMLMediaElement.defaultPlaybackRate HTMLMediaElement AudioBufferSourceNode.detune HTMLMediaElement.controlsList HTMLTextAreaElement.textLength