Signatur
MediaTrackConstraints.channelCount
Beschreibung
Die Eigenschaft channelCount im Wörterbuch MediaTrackConstraints ist vom Typ ConstrainULong. Sie legt fest, wie viele Audiokanäle eine Audiospur haben soll. Man nutzt sie in navigator.mediaDevices.getUserMedia() oder in MediaStreamTrack.applyConstraints(), zum Beispiel für eine Mono-Sprachaufnahme mit 1 oder eine Stereo-Musikaufnahme mit 2.
Der Wert kann auf zwei Arten angegeben werden:
- als einfache Zahl, z. B.
channelCount: 2. Der Browser behandelt sie als Wunsch (ideal) und nimmt den nächstbesten Wert, wenn der gewünschte nicht möglich ist. - als Objekt mit den Schlüsseln
exact,ideal,minundmax. Mitexact,minodermaxwird die Vorgabe zur Pflicht. Kann das Gerät sie nicht erfüllen, wird das Promise mit einemOverconstrainedErrorabgelehnt.
Ob der Browser diese Einschränkung überhaupt kennt, prüft man vorher mit navigator.mediaDevices.getSupportedConstraints().channelCount. Welcher Wert tatsächlich gilt, verrät MediaStreamTrack.getSettings().channelCount. Den Bereich, den das Gerät unterstützt, liefert getCapabilities().channelCount.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $channelCount | number | { exact?: number, ideal?: number, min?: number, max?: number } | Gewünschte Anzahl der Audiokanäle als ganze Zahl ohne Vorzeichen (ConstrainULong). Eine einfache Zahl gilt als ideal, also als Wunsch. exact, min und max sind Pflichtvorgaben. |
Rückgabewert
Typ
number | ConstrainULongRange | undefined
Beschreibung
Der gesetzte Wert der Einschränkung, oder
undefined, wenn keiner angegeben wurde. Dieser Wert ist nur die Anforderung. Den tatsächlich verwendeten Wert liefert MediaStreamTrack.getSettings().channelCount.Beispiele
Stereo-Aufnahme als Wunsch anfordern
const stream = await navigator.mediaDevices.getUserMedia({
audio: { channelCount: 2 } // entspricht { ideal: 2 }
});
const [track] = stream.getAudioTracks();
console.log('Kanäle:', track.getSettings().channelCount);Kanäle: 2 (oder 1, wenn das Mikrofon nur Mono kann)
Mono als Pflicht mit Fehlerbehandlung
const supported = navigator.mediaDevices.getSupportedConstraints();
if (!supported.channelCount) {
console.warn('channelCount wird nicht unterstützt');
}
try {
const stream = await navigator.mediaDevices.getUserMedia({
audio: { channelCount: { exact: 1 }, echoCancellation: true }
});
console.log('Mono-Spur bereit:', stream.getAudioTracks()[0].label);
} catch (err) {
if (err.name === 'OverconstrainedError') {
console.error('Nicht erfüllbar:', err.constraint);
} else {
console.error(err);
}
}Mono-Spur bereit: Standard - Mikrofon (Integriert)
Kanalzahl einer laufenden Spur nachträglich ändern
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const caps = track.getCapabilities?.() ?? {};
console.log('Unterstützter Bereich:', caps.channelCount);
if (caps.channelCount?.max >= 2) {
await track.applyConstraints({ channelCount: { min: 2 } });
}
console.log('Aktuell:', track.getSettings().channelCount);Unterstützter Bereich: { min: 1, max: 2 }
Aktuell: 2
// Wichtig · Fallstricke
- Wunsch statt Garantie: Eine einfache Zahl ist nur ein Wunsch. Ob sie erfüllt wurde, prüft man immer mit
getSettings(). - Pflichtvorgaben:
exact,minundmaxkönnen einenOverconstrainedErrorauslösen. Das betroffene Merkmal steht inerr.constraint. - Audioverarbeitung:
echoCancellation,noiseSuppressionundautoGainControlsind oft standardmäßig aktiv. In einigen Browsern (z. B. Chrome) führen sie zu einer Mono-Spur, auch wenn Stereo angefordert wurde. Wer echtes Stereo braucht, schaltet diese Optionen daher meist mitfalseab. - Nur für Audio: Die Einschränkung wirkt nur bei Audiospuren. Bei Videospuren wird sie ignoriert.
- Kompatibilität: Aktuelle Chromium-Browser, Firefox und Safari unterstützen sie.
getCapabilities()fehlt in älteren Firefox-Versionen. Außerdem ist ein sicherer Kontext (HTTPS) nötig und der Nutzer muss den Mikrofonzugriff erlauben.