MediaStreamTrack.contentHint — Eigenschaft · JavaScript-Referenz

Signatur

MediaStreamTrack.contentHint

Beschreibung

Mit contentHint teilt man dem Browser mit, welche Art von Inhalt ein MediaStreamTrack enthält. Der Browser kann den Hinweis nutzen, um Verarbeitung, Kodierung und Netzwerkverhalten besser auf den Inhalt abzustimmen, etwa in einer RTCPeerConnection (WebRTC), bei einem MediaRecorder oder bei Audio-Nachbearbeitung wie Rauschunterdrückung.

Erlaubte Werte hängen von der Track-Art (track.kind) ab:

Audio: "speech" (Sprache, Rauschunterdrückung und Echounterdrückung sinnvoll), "speech-recognition" (Sprache für maschinelle Erkennung, möglichst wenig Nachbearbeitung), "music" (Musik, Klangtreue wichtiger als Sprachverständlichkeit).
Video: "motion" (Bewegung, z. B. Kamera oder Spiel: flüssige Bildrate geht vor Auflösung), "detail" (Details wie Folien oder Gemälde: Schärfe geht vor Bildrate), "text" (Text, z. B. Code in einer Bildschirmfreigabe: höchste Schärfe, Kompressionsartefakte vermeiden).
Leerer String "": kein Hinweis; der Browser entscheidet selbst. Das ist der Standardwert.

Die Eigenschaft ist nur ein Hinweis. Die Wiedergabe des Tracks ändert sich dadurch nicht, und der Browser muss sich nicht daran halten. Am meisten bringt sie bei der Bildschirmfreigabe über getDisplayMedia(): Mit "text" oder "detail" bleibt geteilter Text lesbar. Bei ruckelfreien Videos ist "motion" die richtige Wahl. Bei WebRTC wirkt sich der Hinweis auch auf die Standardwahl von RTCRtpSendParameters.degradationPreference aus.

Parameter

Name	Typ	Default	Beschreibung
$value	"" \| "speech" \| "speech-recognition" \| "music" \| "motion" \| "detail" \| "text"	""	Neuer Wert beim Setzen. Er muss zur Track-Art passen (`kind`). Ungültige oder unpassende Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Inhaltshinweis des Tracks, oder "", wenn keiner gesetzt ist.

Beispiele

Bildschirmfreigabe für Text optimieren

const startScreenShare = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [videoTrack] = stream.getVideoTracks();

  // Code und Folien sollen scharf bleiben – lieber niedrige Bildrate
  if ('contentHint' in videoTrack) {
    videoTrack.contentHint = 'text';
  }
  console.log('Hinweis:', videoTrack.contentHint);
  return stream;
};

startScreenShare();

Hinweis: text

Mikrofon-Track als Sprache kennzeichnen und an WebRTC übergeben

const pc = new RTCPeerConnection();

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [audioTrack] = stream.getAudioTracks();

audioTrack.contentHint = 'speech';
pc.addTrack(audioTrack, stream);

console.log(audioTrack.kind, audioTrack.contentHint);

audio speech

Ungültige Werte werden ignoriert

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();

console.log(JSON.stringify(track.contentHint)); // Standard

track.contentHint = 'music'; // nur für Audio gültig → ignoriert
console.log(JSON.stringify(track.contentHint));

track.contentHint = 'motion';
console.log(track.contentHint);

"" "" motion

Hinweis je nach Freigabe-Modus umschalten

const setShareMode = (track, mode) => {
  // mode: 'praesentation' | 'video'
  const hint = mode === 'video' ? 'motion' : 'detail';
  if ('contentHint' in track) track.contentHint = hint;
  return track.contentHint;
};

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [track] = stream.getVideoTracks();
console.log(setShareMode(track, 'video'));
console.log(setShareMode(track, 'praesentation'));

motion detail

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) und Safari unterstützen die Eigenschaft, Firefox nicht. Vor der Nutzung mit 'contentHint' in track prüfen. In Firefox schadet das Setzen nicht, es hat nur keine Wirkung.
Stilles Ignorieren: Ein ungültiger Wert oder ein Wert der falschen Track-Art (z. B. "music" bei einem Video-Track) löst keinen Fehler aus. Der bisherige Wert bleibt einfach erhalten.
Nur ein Hinweis: Ob und wie Kodierung oder Audioverarbeitung sich ändern, entscheidet der Browser. Wer Bildrate oder Auflösung verbindlich festlegen will, nutzt zusätzlich applyConstraints() bzw. RTCRtpSender.setParameters() mit degradationPreference.
Zeitpunkt: Den Hinweis möglichst setzen, bevor der Track an eine RTCPeerConnection oder einen MediaRecorder übergeben wird. Spätere Änderungen werden nicht in jedem Browser sofort übernommen.
Klone: track.clone() übernimmt den aktuellen contentHint. Danach lassen sich Original und Klon getrennt ändern.

Siehe auch

MediaStreamTrack.enabled MediaStreamTrack.kind MediaStreamTrack.muted MediaStreamTrack.id MediaStreamTrack.label