MediaStreamConstraints.audio

The MediaStreamConstraints dictionary's audio property is used to indicate what kind of audio track, if any, should be included in the MediaStream returned by a call to getUserMedia().

To learn more about how constraints work, see Capabilities, constraints, and settings.

Syntax

var audioConstraints = true | false | MediaTrackConstraints;

Value

The value of the audio property can be specified as either of two types:

A boolean value

If specified, it indicates whether or not an audio track should be included in the returned stream; if it's true, an audio track is included; if no audio source is available or if permission is not given to use the audio source, the call to getUserMedia() will fail. If false, no audio track is included.

MediaTrackConstraints

A constraints dictionary detailing the preferable and/or required values or ranges of values for the track's constrainable properties. If you specify constraints, an audio track meeting the constraints is required.

Examples

For browsers with Feature Policy enabled, the samples below need the microphone feature enabled. See Security in MediaDevices.getUserMedia() for details and examples on how to configure this.

Using a Boolean value

In this example, we provide a simple value of true for the audio property. This tells getUserMedia() that we require an audio track, but we don't care about any specifics beyond that.

document.getElementById("startButton").addEventListener("click", function() {
  navigator.mediaDevices.getUserMedia({
    audio: true
  }).then(stream => audioElement.srcObject = stream)
    .catch(err => log(err.name + ": " + err.message));
}, false);

Here we see an event handler for a click event which uses getUserMedia() to obtain an audio-only stream with no specific constraints, then attaches the resulting stream to an <audio> element once the stream is returned.

Result

Using a MediaTrackConstraints object

Now let's look at a similar example that uses a set of constraints based on the MediaTrackConstraints dictionary:

document.getElementById("startButton").addEventListener("click", function() {
  navigator.mediaDevices.getUserMedia({
    audio: {
      sampleSize: 8,
      echoCancellation: true
    }
  }).then(stream => audioElement.srcObject = stream)
    .catch(err => log(err.name + ": " + err.message));
}, false);

Here we see an event handler for a click event which calls getUserMedia(), specifying a set of audio constraints requesting that echo cancellation be enabled and that, if possible, the sample rate be 8 bits per sample instead of the more common 16 bits (possibly as a bandwidth saving measure). As long as an audio input device is available and the user allows it to be used, an audio track will be included in the resulting stream, and it will match the specified constraints as well as possible.

Result

Specifications

Browser compatibility

See also

• Media Capture and Streams API
• Capabilities, constraints, and settings
• MediaDevices.getUserMedia()
• MediaDevices.getSupportedConstraints()
• MediaTrackSupportedConstraints
• MediaTrackConstraints