MediaStream Recording API

Konzepte und Verwendung

Die MediaStream Recording API besteht im Wesentlichen aus einer Schnittstelle, MediaRecorder. Sie übernimmt die Daten aus einem MediaStream und stellt sie Ihnen zur Verarbeitung bereit. Die Daten werden über eine Reihe von dataavailable-Ereignissen geliefert, bereits in dem Format, das Sie beim Erstellen des MediaRecorder festlegen. Anschließend können Sie die Daten nach Bedarf weiterverarbeiten oder in eine Datei schreiben.

Überblick über den Aufnahmevorgang

Die Aufnahme eines Streams ist einfach:

1. Richten Sie einen MediaStream oder ein HTMLMediaElement (als <audio>- oder <video>-Element) als Quelle der Mediendaten ein.
2. Erstellen Sie ein MediaRecorder-Objekt und geben Sie den Quell-Stream sowie die gewünschten Optionen an, etwa den MIME-Typ des Containers oder die gewünschten Bitraten seiner Tracks.
3. Richten Sie mit ondataavailable einen Event-Handler für das dataavailable-Ereignis ein. Er wird aufgerufen, sobald Daten verfügbar sind.
4. Wenn das Quellmedium abgespielt wird und Sie mit der Videoaufnahme beginnen möchten, rufen Sie MediaRecorder.start() auf.
5. Ihr Event-Handler für dataavailable wird jedes Mal aufgerufen, wenn Daten zur Verarbeitung bereitstehen. Das Ereignis besitzt ein data-Attribut, dessen Wert ein Blob mit den Mediendaten ist. Sie können ein dataavailable-Ereignis auch gezielt auslösen, um die neuesten Audiodaten zu erhalten und sie beispielsweise zu filtern oder zu speichern.
6. Die Aufnahme endet automatisch, wenn die Wiedergabe des Quellmediums endet.
7. Sie können die Aufnahme jederzeit durch Aufrufen von MediaRecorder.stop() beenden.

Falls während der Aufnahme ein Fehler auftritt, wird ein error-Ereignis an den MediaRecorder gesendet. Sie können auf error-Ereignisse reagieren, indem Sie einen Event-Handler über onerror einrichten.

Im folgenden Beispiel verwenden wir ein HTML-Canvas als Quelle des MediaStream und beenden die Aufnahme nach 9 Sekunden.

const canvas = document.querySelector("canvas");

// Optional frames per second argument.
const stream = canvas.captureStream(25);
const recordedChunks = [];

console.log(stream);
const options = { mimeType: "video/webm; codecs=vp9" };
const mediaRecorder = new MediaRecorder(stream, options);

mediaRecorder.ondataavailable = handleDataAvailable;
mediaRecorder.start();

function handleDataAvailable(event) {
  console.log("data-available");
  if (event.data.size > 0) {
    recordedChunks.push(event.data);
    console.log(recordedChunks);
    download();
  } else {
    // …
  }
}
function download() {
  const blob = new Blob(recordedChunks, {
    type: "video/webm",
  });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  document.body.appendChild(a);
  a.style = "display: none";
  a.href = url;
  a.download = "test.webm";
  a.click();
  URL.revokeObjectURL(url);
}

// demo: to download after 9sec
setTimeout((event) => {
  console.log("stopping");
  mediaRecorder.stop();
}, 9000);

Status des Recorders prüfen und steuern

Sie können auch die Eigenschaften des MediaRecorder-Objekts verwenden, um den Status des Aufnahmevorgangs zu bestimmen. Mit den Methoden pause() und resume() können Sie die Aufnahme des Quellmediums pausieren und fortsetzen.

Sie können außerdem prüfen, ob ein bestimmter MIME-Typ unterstützt wird. Rufen Sie dazu MediaRecorder.isTypeSupported() auf.

Mögliche Eingabequellen prüfen

Wenn Sie Kamera- und/oder Mikrofoneingaben aufnehmen möchten, sollten Sie die verfügbaren Eingabegeräte prüfen, bevor Sie den MediaRecorder erstellen. Rufen Sie dazu navigator.mediaDevices.enumerateDevices() auf, um eine Liste der verfügbaren Mediengeräte zu erhalten. Anschließend können Sie die Liste durchsehen, mögliche Eingabequellen identifizieren und sie nach gewünschten Kriterien filtern.

Im folgenden Codeausschnitt wird enumerateDevices() verwendet, um die verfügbaren Eingabegeräte zu prüfen, Audioeingabegeräte zu finden und <option>-Elemente zu erstellen. Diese werden dann einem <select>-Element hinzugefügt, mit dem sich eine Eingabequelle auswählen lässt.

navigator.mediaDevices.enumerateDevices().then((devices) => {
  devices.forEach((device) => {
    const menu = document.getElementById("input-devices");
    if (device.kind === "audioinput") {
      const item = document.createElement("option");
      item.textContent = device.label;
      item.value = device.deviceId;
      menu.appendChild(item);
    }
  });
});

Mit ähnlichem Code können Sie Benutzerinnen und Benutzern ermöglichen, die Auswahl der Geräte einzuschränken, die sie verwenden möchten.

Weitere Informationen

Weitere Informationen zur Verwendung der MediaStream Recording API finden Sie unter Die MediaStream Recording API verwenden. Der Artikel zeigt, wie Sie mit der API Audioclips aufnehmen. Ein zweiter Artikel, Ein Medienelement aufnehmen, beschreibt, wie Sie einen Stream von einem <audio>- oder <video>-Element erhalten und den erfassten Stream verwenden – in diesem Fall, indem Sie ihn aufnehmen und auf einem lokalen Datenträger speichern.

Schnittstellen

BlobEvent

Sobald die Aufnahme eines Mediendatenabschnitts abgeschlossen ist, wird er über ein BlobEvent vom Typ dataavailable als Blob an die Empfänger übermittelt.

MediaRecorder

Die zentrale Schnittstelle, die die MediaStream Recording API implementiert.

MediaRecorderErrorEvent

Die Schnittstelle zur Darstellung von Fehlern, die von der MediaStream Recording API ausgelöst werden. Ihre error-Eigenschaft ist eine DOMException, die den aufgetretenen Fehler beschreibt.

Beispiele

Einfache Videoaufnahme

<button id="record-btn">Start</button>
<video id="player" src="" autoplay controls></video>

const recordBtn = document.getElementById("record-btn");
const video = document.getElementById("player");

let chunks = [];
let isRecording = false;
let mediaRecorder = null;

const constraints = { video: true };

recordBtn.addEventListener("click", async () => {
  if (!isRecording) {
    // Acquire a recorder on load
    if (!mediaRecorder) {
      const stream = await navigator.mediaDevices.getUserMedia(constraints);
      mediaRecorder = new MediaRecorder(stream);
      mediaRecorder.addEventListener("dataavailable", (e) => {
        console.log("data available");
        chunks.push(e.data);
      });
      mediaRecorder.addEventListener("stop", (e) => {
        console.log("onstop fired");
        const blob = new Blob(chunks, { type: "video/ogv; codecs=opus" });
        video.src = window.URL.createObjectURL(blob);
      });
      mediaRecorder.addEventListener("error", (e) => {
        console.error("An error occurred:", e);
      });
    }
    isRecording = true;
    recordBtn.textContent = "Stop";
    chunks = [];
    mediaRecorder.start();
    console.log("recorder started");
  } else {
    isRecording = false;
    recordBtn.textContent = "Start";
    mediaRecorder.stop();
    console.log("recorder stopped");
  }
});

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Übersichtsseite zur Media Capture and Streams API
• MediaDevices.getUserMedia()
• simpl.info-Demo zur MediaStream-Aufnahme von Sam Dutton
• Die Media Recorder API von HTML5 im Einsatz in Chrome und Firefox
• TutorRoom: Aufnehmen, Abspielen und Herunterladen von HTML-Videos mit getUserMedia und der MediaStream Recording API (Quellcode auf GitHub)
• Fortgeschrittenes Beispiel für die Aufnahme von Medienstreams
• OpenLang: Webanwendung für ein Videosprachlabor, die MediaDevices und die MediaStream Recording API zur Videoaufnahme verwendet (Quellcode auf GitHub)
• MediaStream Recorder API jetzt in Safari Technology Preview 73 verfügbar