Signatur
Beschreibung
Mit setParameters() änderst du, wie ein RTCRtpSender seinen Medien-Track kodiert und überträgt. Typische Anwendungen sind eine Obergrenze für die Bitrate (maxBitrate), eine niedrigere Bildrate (maxFramerate), eine herunterskalierte Auflösung (scaleResolutionDownBy) oder das Ein- und Ausschalten einzelner Simulcast-Ebenen über active.
Die Änderungen greifen ohne neues Offer/Answer. Damit eignet sich die Methode gut für adaptive Qualitätsregelung zur Laufzeit, etwa wenn die Bandbreite schwankt, beim Bildschirmteilen oder wenn in einer Videokonferenz ein Teilnehmer nur noch als Miniaturbild angezeigt wird.
Wichtig ist der Ablauf lesen, ändern, schreiben: Zuerst holst du mit getParameters() das aktuelle Parameterobjekt, dann änderst du es und übergibst es direkt an setParameters(). Das Objekt enthält eine transactionId. Stimmt sie nicht mit der zuletzt von getParameters() gelieferten überein, oder liegt zwischendurch ein Ereignisschleifen-Durchlauf, wird der Aufruf abgelehnt. Nur ein Teil der Felder darf verändert werden, zum Beispiel encodings[i].active, maxBitrate, maxFramerate, scaleResolutionDownBy, priority, networkPriority und degradationPreference. Die Anzahl der Encodings und ihre rid-Werte bleiben unveränderlich.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $parameters Pflicht | RTCRtpSendParameters | Parameterobjekt, das zuvor mit getParameters() geholt und dann verändert wurde. Wichtige Felder: transactionId (nicht verändern), encodings (Array mit active, maxBitrate, maxFramerate, scaleResolutionDownBy, priority, networkPriority, scalabilityMode), degradationPreference. Nur lesbar sind codecs, headerExtensions und rtcp. |
|
| $setParameterOptions | object | {} | Optionales Objekt mit weiteren Optionen, z. B. encodingOptions (Array mit keyFrame: boolean, um ein Keyframe anzufordern). Bisher nur in wenigen Browsern unterstützt. |
Rückgabewert
InvalidStateError (Sender gestoppt oder veraltete bzw. fehlende transactionId), InvalidModificationError (unveränderliche Felder oder Anzahl der Encodings geändert), RangeError (z. B. scaleResolutionDownBy < 1) oder OperationError.Beispiele
Maximale Video-Bitrate begrenzen
const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const sender = pc.addTrack(track, stream);
const setMaxBitrate = async (sender, bitsPerSecond) => {
const params = sender.getParameters();
// Manche Browser liefern vor der Verhandlung ein leeres encodings-Array
if (!params.encodings || params.encodings.length === 0) {
params.encodings = [{}];
}
params.encodings[0].maxBitrate = bitsPerSecond;
await sender.setParameters(params);
console.log('Neue Bitrate:', sender.getParameters().encodings[0].maxBitrate);
};
await setMaxBitrate(sender, 500_000); // 500 kbit/sSimulcast-Ebene abschalten, wenn nur ein Miniaturbild angezeigt wird
const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const { sender } = pc.addTransceiver(stream.getVideoTracks()[0], {
direction: 'sendonly',
sendEncodings: [
{ rid: 'q', scaleResolutionDownBy: 4 },
{ rid: 'h', scaleResolutionDownBy: 2 },
{ rid: 'f' }
]
});
const setHighQuality = async (enabled) => {
const params = sender.getParameters();
for (const enc of params.encodings) {
if (enc.rid === 'f') enc.active = enabled;
}
await sender.setParameters(params);
};
await setHighQuality(false); // volle Auflösung pausieren
console.log(sender.getParameters().encodings.map(e => `${e.rid}:${e.active}`));Bildschirmfreigabe: Schärfe vor Flüssigkeit, mit Fehlerbehandlung
const tuneForScreenShare = async (sender) => {
const params = sender.getParameters();
params.degradationPreference = 'maintain-resolution';
if (params.encodings.length === 0) params.encodings = [{}];
params.encodings[0].maxFramerate = 5;
try {
await sender.setParameters(params);
console.log('Parameter übernommen');
} catch (err) {
console.error(`${err.name}: ${err.message}`);
}
};
const pc = new RTCPeerConnection();
const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
const sender = pc.addTrack(screen.getVideoTracks()[0], screen);
await tuneForScreenShare(sender);// Wichtig · Fallstricke
- Immer
getParameters()direkt vorher aufrufen. Selbst gebaute Objekte oder zwischengespeicherte ältere Parameter scheitern an dertransactionIdund führen zu einemInvalidStateError. Zwischen den beiden Aufrufen darf keinawaitstehen. - Vor Abschluss der SDP-Verhandlung kann
encodingsin manchen Browsern leer sein, vor allem in älteren Chrome- und Firefox-Versionen. In diesem Fall ein Encoding-Objekt ergänzen oder die Einstellungen besser gleich persendEncodingsbeiaddTransceiver()setzen. - Die Anzahl der Encodings und die
rid-Werte lassen sich nachträglich nicht ändern. Simulcast muss also schon beim Anlegen des Transceivers festgelegt werden. maxBitrateist eine Obergrenze, keine feste Zielrate. Die Staukontrolle kann die tatsächliche Rate weiter senken.- Browserunterschiede: Safari hat
scaleResolutionDownByundmaxFramerateerst spät vollständig unterstützt.degradationPreference,scalabilityMode(SVC) undsetParameterOptionswerden nicht überall unterstützt. Vor dem Einsatz prüfen, zum Beispiel indem du nach dem AufrufgetParameters()ausliest. - Den Codec wechselst du nicht über diese Methode (
codecsist nur lesbar), sondern mitRTCRtpTransceiver.setCodecPreferences()und einer anschließenden Neuverhandlung.