MediaTrackSupportedConstraints.deviceId — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.deviceId

Beschreibung

Die Eigenschaft deviceId des Wörterbuchs MediaTrackSupportedConstraints gibt an, ob der Browser die Einschränkung (Constraint) deviceId kennt. Über diese Einschränkung wählt man bei getUserMedia() oder MediaStreamTrack.applyConstraints() ein bestimmtes Eingabegerät aus, etwa eine bestimmte Kamera oder ein bestimmtes Mikrofon.

Das Objekt bekommt man über navigator.mediaDevices.getSupportedConstraints(). Nicht unterstützte Einschränkungen fehlen darin einfach, deshalb ist der Wert entweder true oder undefined. false kommt in der Praxis nicht vor.

Prüfe die Eigenschaft, bevor du eine Geräteauswahl anbietest, zum Beispiel eine Kameraauswahl in einer Videokonferenz-App. Die passenden IDs liefert navigator.mediaDevices.enumerateDevices().

Der Wert sagt nur, ob der Browser die Einschränkung versteht. Er sagt nichts darüber, ob ein bestimmtes Gerät vorhanden oder verfügbar ist.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die Einschränkung deviceId unterstützt wird. Sonst fehlt die Eigenschaft (undefined).

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.deviceId) {
  console.log('deviceId wird unterstützt');
} else {
  console.log('Keine Geräteauswahl per deviceId möglich');
}

deviceId wird unterstützt

Bestimmte Kamera auswählen

const startCamera = async () => {
  const { deviceId: canSelect } = navigator.mediaDevices.getSupportedConstraints();

  // Berechtigung holen, damit Gerätenamen und IDs sichtbar werden
  const probe = await navigator.mediaDevices.getUserMedia({ video: true });
  probe.getTracks().forEach((t) => t.stop());

  const cams = (await navigator.mediaDevices.enumerateDevices())
    .filter((d) => d.kind === 'videoinput');

  const constraints = canSelect && cams.length > 1
    ? { video: { deviceId: { exact: cams[1].deviceId } } }
    : { video: true };

  const stream = await navigator.mediaDevices.getUserMedia(constraints);
  document.querySelector('video').srcObject = stream;
  console.log('Aktive Kamera:', stream.getVideoTracks()[0].label);
};

startCamera().catch(console.error);

Aktive Kamera: Externe USB-Kamera

Mikrofon wechseln mit applyConstraints

const switchMic = async (track, newDeviceId) => {
  if (!navigator.mediaDevices.getSupportedConstraints().deviceId) {
    throw new Error('deviceId nicht unterstützt');
  }
  try {
    await track.applyConstraints({ deviceId: { exact: newDeviceId } });
  } catch (err) {
    // Viele Browser wechseln das Gerät nicht über applyConstraints -> neuen Stream holen
    track.stop();
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: { deviceId: { exact: newDeviceId } }
    });
    return stream.getAudioTracks()[0];
  }
  return track;
};

// Wichtig · Fallstricke

Nicht unterstützte Einschränkungen fehlen im Objekt. Prüfe deshalb auf truthy (if (supported.deviceId)) und nicht mit === false.
getUserMedia() funktioniert nur in einem sicheren Kontext (HTTPS oder localhost). Ohne sicheren Kontext ist navigator.mediaDevices undefined.
deviceId ohne exact ist nur ein Wunsch (ideal): Der Browser kann dann trotzdem ein anderes Gerät nehmen. Mit { exact: id } wird die Auswahl erzwungen. Fehlt das Gerät, wird die Anfrage mit OverconstrainedError abgelehnt.
Die IDs gelten nur für den jeweiligen Ursprung und können sich ändern, zum Beispiel nachdem der Nutzer die Cookies gelöscht hat. Außerdem sind sie oft leer, solange der Nutzer keine Medienberechtigung erteilt hat.
Ein Gerätewechsel per applyConstraints() funktioniert nicht in allen Browsern zuverlässig. Sicherer ist es, einen neuen Stream anzufordern.

Siehe auch

MediaTrackConstraints.deviceId MediaTrackSupportedConstraints.groupId MediaTrackSupportedConstraints.height MediaTrackSupportedConstraints.volume MediaTrackSupportedConstraints.width