MediaTrackSettings.cursor — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.cursor

Beschreibung

Die Eigenschaft cursor des Wörterbuchs MediaTrackSettings gibt an, wie der Mauszeiger im Videotrack einer Bildschirmaufnahme tatsächlich dargestellt wird. Solche Aufnahmen entstehen mit navigator.mediaDevices.getDisplayMedia(). Den Wert liest man mit MediaStreamTrack.getSettings() aus. Er zeigt den aktuellen Zustand, also nicht unbedingt den Wunsch, den die Anwendung angefordert hat.

Mögliche Werte:

"always": Der Zeiger ist immer im Video zu sehen, sofern er sich im erfassten Bereich befindet.
"motion": Der Zeiger erscheint nur, während er sich bewegt. Nach kurzer Ruhe wird er ausgeblendet.
"never": Der Zeiger wird nie ins Video übernommen.

Die Eigenschaft ist nützlich für Bildschirmaufzeichnungen, Anleitungsvideos oder Fernwartung. Dort hängt die Bedienbarkeit oft davon ab, ob der Betrachter den Zeiger sieht. Die Anwendung kann über die Einschränkung (Constraint) cursor in getDisplayMedia() ein Verhalten anfordern. Mit getSettings().cursor prüft sie danach, was der Browser tatsächlich umsetzt. So lässt sich die Oberfläche anpassen, etwa mit einem eigenen Zeiger-Overlay, wenn "never" gemeldet wird.

Ob der Browser die Eigenschaft überhaupt kennt, verrät navigator.mediaDevices.getSupportedConstraints().cursor. Bei Kamera- oder Mikrofon-Tracks aus getUserMedia() ist cursor nicht vorhanden.

Rückgabewert

Typ

"always" | "motion" | "never" | undefined

Beschreibung

Ein String, der angibt, wie der Mauszeiger im erfassten Video dargestellt wird. undefined, wenn der Browser die Eigenschaft nicht unterstützt oder es sich nicht um einen Bildschirmaufnahme-Track handelt.

Beispiele

Tatsächliche Zeiger-Einstellung nach getDisplayMedia() auslesen

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { cursor: 'always' }, // Wunsch: Zeiger immer anzeigen
    audio: false
  });

  const [videoTrack] = stream.getVideoTracks();
  const { cursor } = videoTrack.getSettings();

  console.log(`Zeiger-Modus: ${cursor ?? 'nicht unterstützt'}`);
  return stream;
};

document.querySelector('#start').addEventListener('click', startCapture);

Zeiger-Modus: always

Unterstützung prüfen und Oberfläche anpassen

const supportsCursor = navigator.mediaDevices.getSupportedConstraints().cursor === true;

const recordScreen = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: supportsCursor ? { cursor: 'motion' } : true
  });
  const [track] = stream.getVideoTracks();
  const cursor = track.getSettings().cursor;

  // Hinweis einblenden, wenn der Zeiger nicht im Video zu sehen ist
  const hint = document.querySelector('#cursor-hint');
  hint.hidden = cursor !== 'never';

  console.log('Unterstützt:', supportsCursor, '| Modus:', cursor);
};

document.querySelector('#record').addEventListener('click', recordScreen);

Unterstützt: true | Modus: motion

Zeiger-Modus nachträglich per applyConstraints() ändern

const toggleCursor = async (track) => {
  const current = track.getSettings().cursor;
  const next = current === 'never' ? 'always' : 'never';

  try {
    await track.applyConstraints({ cursor: next });
    console.log(`Vorher: ${current}, jetzt: ${track.getSettings().cursor}`);
  } catch (err) {
    console.warn('Änderung nicht möglich:', err.name);
  }
};

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
await toggleCursor(stream.getVideoTracks()[0]);

Vorher: always, jetzt: never

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Eigenschaft wird nur uneinheitlich unterstützt. Viele Browser ignorieren die cursor-Einschränkung und liefern dann undefined in getSettings(). Vor der Nutzung sollte man getSupportedConstraints().cursor prüfen und eine Alternative vorsehen.
Nur ein Wunsch: Die in getDisplayMedia() übergebene Einschränkung ist eine Empfehlung. Der Browser oder das Betriebssystem kann anders entscheiden. Deshalb sollte man immer getSettings() auswerten, statt vom angeforderten Wert auszugehen.
"motion" ist ungenau festgelegt: Wie lange der Zeiger nach der letzten Bewegung sichtbar bleibt, bestimmt die jeweilige Umsetzung.
Nur bei Bildschirmaufnahmen: Bei Tracks aus getUserMedia() oder canvas.captureStream() gibt es diese Eigenschaft nicht.
Sicherheitskontext: getDisplayMedia() funktioniert nur in sicheren Kontexten (HTTPS), braucht eine Nutzeraktion und muss vom Nutzer bestätigt werden.
Datenschutz: Ein sichtbarer Zeiger kann in Aufzeichnungen verraten, wo der Nutzer hinschaut oder was er anklickt. Bei sensiblen Vorführungen kann "never" sinnvoll sein.

Siehe auch

MediaStreamTrackEvent.track MediaTrackSettings.height MediaTrackSettings.volume MediaTrackSettings.width MediaTrackSettings.groupId