CanvasCaptureMediaStreamTrack.canvas — Eigenschaft · JavaScript-Referenz

Signatur

CanvasCaptureMediaStreamTrack.canvas

Beschreibung

Ruft man HTMLCanvasElement.captureStream() auf, entsteht ein MediaStream mit einem Video-Track vom Typ CanvasCaptureMediaStreamTrack. Über dessen Eigenschaft canvas kommt man jederzeit wieder an das Canvas-Element, das den Track mit Bildern versorgt.

Das ist vor allem dann nützlich, wenn nur der Track oder der Stream an andere Programmteile weitergegeben wird, z. B. an einen MediaRecorder, eine RTCPeerConnection oder eine Hilfsfunktion. Diese Stellen brauchen keinen eigenen Verweis auf das Canvas, um weiter darauf zu zeichnen, seine Größe abzufragen oder über requestFrame() gezielt einzelne Frames anzufordern.

Die Eigenschaft ist schreibgeschützt: Einen Track kann man nicht nachträglich an ein anderes Canvas hängen. Für eine andere Quelle ruft man captureStream() auf dem neuen Canvas auf.

Rückgabewert

Typ

HTMLCanvasElement

Beschreibung

Das Canvas-Element, dessen Inhalt der Track als Videobilder liefert. Es ist dasselbe Objekt, auf dem captureStream() aufgerufen wurde.

Beispiele

Canvas über den Track wiederfinden

const canvas = document.createElement('canvas');
canvas.width = 640;
canvas.height = 360;

const stream = canvas.captureStream(30);
const [track] = stream.getVideoTracks();

console.log(track.canvas === canvas);
console.log(`${track.canvas.width}x${track.canvas.height}`);

true 640x360

Hilfsfunktion zeichnet nur mit Hilfe des Tracks

// Die Funktion bekommt nur den Track, nicht das Canvas
const drawTimestamp = (track) => {
  const ctx = track.canvas.getContext('2d');
  ctx.fillStyle = '#000';
  ctx.fillRect(0, 0, track.canvas.width, track.canvas.height);
  ctx.fillStyle = '#0f0';
  ctx.font = '24px monospace';
  ctx.fillText(new Date().toLocaleTimeString('de-DE'), 20, 40);
};

const canvas = document.querySelector('#stage');
const [track] = canvas.captureStream(25).getVideoTracks();

setInterval(() => drawTimestamp(track), 1000);

Manuelle Frames bei captureStream(0) anfordern

const canvas = document.querySelector('#stage');
// Framerate 0: ein Frame wird nur auf Anforderung erfasst
const stream = canvas.captureStream(0);
const [track] = stream.getVideoTracks();

const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
const chunks = [];
recorder.ondataavailable = (e) => chunks.push(e.data);
recorder.start();

const renderFrame = (i) => {
  const ctx = track.canvas.getContext('2d');
  ctx.fillStyle = `hsl(${i * 10}, 80%, 50%)`;
  ctx.fillRect(0, 0, track.canvas.width, track.canvas.height);
  track.requestFrame(); // aktuellen Inhalt als Frame übernehmen
};

let i = 0;
const timer = setInterval(() => {
  renderFrame(i++);
  if (i === 36) {
    clearInterval(timer);
    recorder.stop();
  }
}, 100);

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an track.canvas wird ohne Fehler ignoriert, im Strict Mode wirft sie einen TypeError.
Typprüfung: Nur Tracks aus captureStream() haben diese Eigenschaft. Bei Kamera- oder Bildschirm-Tracks (getUserMedia, getDisplayMedia) ist track.canvas undefined. Deshalb vorher z. B. mit 'canvas' in track prüfen.
Firefox: Dort heißt die Schnittstelle CanvasCaptureMediaStream, und die Eigenschaft canvas hängt am Stream, nicht am Track. Wer mehrere Browser unterstützt, sollte beide Fälle abfangen.
Tainted Canvas: Enthält das Canvas Bilder von fremden Ursprüngen ohne CORS-Freigabe, gibt der Stream keine brauchbaren Frames aus. Der Zugriff auf canvas selbst klappt trotzdem.
OffscreenCanvas wird nicht unterstützt: captureStream() gibt es nur auf HTMLCanvasElement.

Siehe auch

MediaStreamTrack.kind MediaStreamTrack.label CanvasRenderingContext2D.canvas MediaStreamTrack.enabled MediaStreamTrack.id