HTMLMediaElement.canPlayType() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.canPlayType(type)

Beschreibung

Mit canPlayType() prüft man vor dem Laden einer Datei, ob ein <audio>- oder <video>-Element ein bestimmtes Format voraussichtlich abspielen kann. So kann man per Skript die passende Quelle auswählen (z. B. AV1/WebM mit Rückfall auf H.264/MP4), ohne unnötig Daten herunterzuladen.

Die Methode liefert keine verbindliche Zusage, sondern eine Einschätzung in drei Stufen:

"probably" – Das Format wird sehr wahrscheinlich unterstützt. Diesen Wert gibt es meist nur, wenn im MIME-Typ auch der Parameter codecs angegeben ist.
"maybe" – Der Container ist bekannt, ob die Datei tatsächlich abspielbar ist, zeigt sich erst beim Laden.
"" (leerer String) – Das Format wird sicher nicht unterstützt.

Das Element muss nicht im DOM hängen. Ein mit document.createElement("video") erzeugtes Element reicht für eine Formatprüfung. Für Streaming mit Media Source Extensions sowie für genauere Angaben zu Leistung und Energieverbrauch gibt es besser geeignete APIs: MediaSource.isTypeSupported() und navigator.mediaCapabilities.decodingInfo().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		MIME-Typ des Mediums, optional mit `codecs`-Parameter, z. B. `'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'` oder `"audio/ogg"`.

Rückgabewert

Typ

"probably" | "maybe" | ""

Beschreibung

Ein String mit der geschätzten Wahrscheinlichkeit der Unterstützung. Ein leerer String bedeutet: nicht abspielbar.

Beispiele

Einfache Formatprüfung

const video = document.createElement("video");

console.log(video.canPlayType("video/mp4"));
console.log(video.canPlayType('video/mp4; codecs="avc1.42E01E, mp4a.40.2"'));
console.log(video.canPlayType("video/x-unbekannt"));

maybe probably (leerer String)

Beste Videoquelle automatisch auswählen

const quellen = [
  { src: "/media/film.av1.webm", type: 'video/webm; codecs="av01.0.05M.08, opus"' },
  { src: "/media/film.vp9.webm", type: 'video/webm; codecs="vp9, opus"' },
  { src: "/media/film.h264.mp4", type: 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' }
];

const player = document.querySelector("#player");

const waehleQuelle = (el, liste) =>
  liste.find(q => el.canPlayType(q.type) === "probably") ??
  liste.find(q => el.canPlayType(q.type) === "maybe");

const quelle = waehleQuelle(player, quellen);
if (quelle) {
  player.src = quelle.src;
  console.log("Gewählt:", quelle.src);
} else {
  console.warn("Kein unterstütztes Format gefunden.");
}

Gewählt: /media/film.av1.webm (je nach Browser)

Audio-Unterstützung als Tabelle ausgeben

const audio = new Audio();
const formate = {
  MP3: "audio/mpeg",
  AAC: 'audio/mp4; codecs="mp4a.40.2"',
  Opus: 'audio/ogg; codecs="opus"',
  FLAC: "audio/flac",
  WAV: 'audio/wav; codecs="1"'
};

const ergebnis = Object.fromEntries(
  Object.entries(formate).map(([name, typ]) => [name, audio.canPlayType(typ) || "nein"])
);
console.table(ergebnis);

MP3: maybe, AAC: probably, Opus: probably, FLAC: maybe, WAV: probably (browserabhängig)

// Wichtig · Fallstricke

Kein Boolean: Der Rückgabewert ist ein String. Weil "maybe" und "probably" truthy sind, funktioniert if (el.canPlayType(t)) zwar, unterscheidet aber nicht zwischen den beiden Stufen. Vergleiche nie mit true.
Nur eine Schätzung: Auch bei "probably" kann die Wiedergabe scheitern, etwa bei einem nicht unterstützten Profil, einer zu hohen Auflösung oder einer defekten Datei. Behandle deshalb immer auch das error-Event.
Codecs angeben: Ohne codecs-Parameter liefern Browser meist höchstens "maybe". Die Codec-Strings müssen exakt sein, z. B. avc1.42E01E statt nur h264.
Unterschiede zwischen Browsern: Die Ergebnisse hängen von Browser, Betriebssystem und installierten Decodern ab (z. B. HEVC in Safari). Manche Browser geben aus Datenschutzgründen (Fingerprinting) bewusst ungenaue Werte zurück.
Alternativen: Für MSE-Streaming verwende MediaSource.isTypeSupported(). Ob eine Wiedergabe flüssig und energiesparend läuft, zeigt navigator.mediaCapabilities.decodingInfo().
Oft reicht deklaratives HTML: Bei mehreren <source type="…">-Elementen wählt der Browser selbst die erste passende Quelle.

Siehe auch

HTMLMediaElement.play() HTMLMediaElement.pause() HTMLMediaElement.fastSeek() HTMLMediaElement.getStartDate() HTMLMediaElement.captureStream()