HTMLMediaElement.crossOrigin — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.crossOrigin

Beschreibung

Die Eigenschaft crossOrigin legt fest, ob und wie ein Medienelement (<video> oder <audio>) seine Ressource per CORS (Cross-Origin Resource Sharing) anfordert. Sie spiegelt das HTML-Attribut crossorigin wider. Gültige Werte sind "anonymous" (CORS-Anfrage ohne Anmeldedaten wie Cookies) und "use-credentials" (CORS-Anfrage mit Anmeldedaten). Ist das Attribut nicht gesetzt, liefert die Eigenschaft null, und die Ressource wird ohne CORS geladen.

Wichtig wird die Einstellung vor allem, wenn Medien von einer fremden Origin weiterverarbeitet werden sollen: etwa wenn ein Videobild mit drawImage() in ein <canvas> gezeichnet und danach mit getImageData() oder toDataURL() ausgelesen wird, wenn es als WebGL-Textur dient oder wenn der Ton über die Web Audio API (createMediaElementSource()) analysiert wird. Ohne CORS gilt die Ressource als „tainted“ (verunreinigt). Das Canvas wird dann gesperrt bzw. der Audioknoten liefert nur Stille.

Damit das Laden mit CORS klappt, muss der Server zusätzlich passende Header senden, z. B. Access-Control-Allow-Origin. Bei "use-credentials" muss der Header die konkrete Origin enthalten (kein *), und zusätzlich muss Access-Control-Allow-Credentials: true gesetzt sein. Die Eigenschaft sollte vor dem Setzen von src zugewiesen werden, damit sie schon für die erste Anfrage gilt.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"anonymous"`, `"use-credentials"` oder `null` (entfernt das Attribut). Ungültige Werte und der leere String werden als `"anonymous"` behandelt.

Rückgabewert

Typ

string | null

Beschreibung

"anonymous", "use-credentials" oder null, wenn kein crossorigin-Attribut gesetzt ist.

Beispiele

CORS-Einstellung lesen und setzen

const video = document.createElement('video');
console.log(video.crossOrigin); // noch kein Attribut gesetzt

video.crossOrigin = 'anonymous';
console.log(video.crossOrigin);
console.log(video.getAttribute('crossorigin'));

// Ungültiger Wert wird zu "anonymous" normalisiert
video.crossOrigin = 'irgendwas';
console.log(video.crossOrigin);

// null entfernt das Attribut
video.crossOrigin = null;
console.log(video.hasAttribute('crossorigin'));

null anonymous anonymous anonymous false

Videobild von einem CDN in ein Canvas kopieren

const video = document.createElement('video');
video.crossOrigin = 'anonymous'; // VOR src setzen!
video.src = 'https://cdn.example.com/clip.mp4';
video.muted = true;

video.addEventListener('loadeddata', () => {
  const canvas = document.createElement('canvas');
  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(video, 0, 0);

  // Klappt nur, wenn der Server Access-Control-Allow-Origin sendet
  const thumbnail = canvas.toDataURL('image/jpeg', 0.8);
  console.log('Vorschaubild erzeugt:', thumbnail.slice(0, 30));
});

Vorschaubild erzeugt: data:image/jpeg;base64,/9j/4AAQ

Audio einer fremden Origin mit der Web Audio API analysieren

const audio = new Audio();
audio.crossOrigin = 'anonymous';
audio.src = 'https://media.example.org/podcast.mp3';

const startAnalyse = async () => {
  const ctx = new AudioContext();
  const source = ctx.createMediaElementSource(audio);
  const analyser = ctx.createAnalyser();
  source.connect(analyser).connect(ctx.destination);

  await audio.play();
  const daten = new Uint8Array(analyser.frequencyBinCount);
  setTimeout(() => {
    analyser.getByteFrequencyData(daten);
    console.log('Maximaler Pegel:', Math.max(...daten));
  }, 1000);
};

document.querySelector('#play').addEventListener('click', startAnalyse);

Maximaler Pegel: 212

Geschützte Medien mit Cookies laden

const video = document.querySelector('video');
// Session-Cookie soll mitgeschickt werden
video.crossOrigin = 'use-credentials';
video.src = 'https://api.example.com/private/video.mp4';

video.addEventListener('error', () => {
  console.error('Laden fehlgeschlagen – CORS-Header am Server prüfen:', video.error?.code);
});

// Wichtig · Fallstricke

Reihenfolge beachten: crossOrigin vor src setzen. Wird es erst später geändert, gilt die Einstellung erst beim nächsten Ladevorgang (z. B. nach load()).
Serverseitige Header nötig: Setzt man crossOrigin, ohne dass der Server Access-Control-Allow-Origin sendet, wird das Medium gar nicht geladen (Fehler statt „tainted“). Ohne das Attribut wird es zwar abgespielt, lässt sich aber nicht auslesen.
use-credentials: Hier ist Access-Control-Allow-Origin: * nicht erlaubt. Nötig sind die konkrete Origin und Access-Control-Allow-Credentials: true.
Caching-Falle: Wurde dieselbe URL schon ohne CORS geladen und ohne Vary: Origin zwischengespeichert, kann die Antwort aus dem Cache ohne CORS-Header kommen, und die CORS-Anfrage scheitert.
Der leere String (crossorigin="") und unbekannte Werte entsprechen "anonymous".
Sicherheit: "use-credentials" nur für vertrauenswürdige Origins verwenden, weil dabei Cookies und HTTP-Authentifizierung mitgesendet werden.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. In sehr alten Safari- und Android-Versionen wurde CORS für Medien nur lückenhaft umgesetzt.

Siehe auch

HTMLMediaElement.controlsList HTMLMediaElement.controls HTMLMediaElement.error HTMLMediaElement.controller HTMLMediaElement.currentTime