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:
Boolean
- If a Boolean value is specified, it simply 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 togetUserMedia()
will fail. Iffalse
, 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
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.
HTML content
<p>Click the start button below to begin the demonstration.</p> <div id="startButton" class="button"> Start </div> <audio id="audio" autoplay controls></audio><br> <div id="log"></div>
CSS content
body { font: 14px "Open Sans", "Arial", sans-serif; } audio { margin-top: 20px; border: 1px solid black; width: 160px; } .button { cursor: pointer; width: 160px; border: 1px solid black; font-size: 16px; text-align: center; padding-top: 2px; padding-bottom: 4px; color: white; background-color: darkgreen; }
JavaScript content
let audioElement = document.getElementById("audio"); let logElement = document.getElementById("log"); function log(msg) { logElement.innerHTML += msg + "<br>"; }
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:
HTML content
<p>Click the start button below to begin the demonstration.</p> <div id="startButton" class="button"> Start </div> <audio id="audio" autoplay controls></audio><br> <div id="log"></div>
CSS content
body { font: 14px "Open Sans", "Arial", sans-serif; } audio { margin-top: 20px; border: 1px solid black; width: 160px; } .button { cursor: pointer; width: 160px; border: 1px solid black; font-size: 16px; text-align: center; padding-top: 2px; padding-bottom: 4px; color: white; background-color: darkgreen; }
JavaScript content
let audioElement = document.getElementById("audio"); let logElement = document.getElementById("log"); function log(msg) { logElement.innerHTML += msg + "<br>"; }
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
Specification | Status | Comment |
---|---|---|
Media Capture and Streams The definition of 'MediaStreamConstraints.audio' in that specification. |
Editor's Draft | Initial specification. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Microsoft Edge | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | (Yes) | 38 (38) | ? | No support | (Yes) | ? |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|
Basic support | ? | (Yes) | 38.0 (38) | No support | ? | ? | (Yes) |