Наши волонтёры ещё не перевели данную статью на Русский. Присоединяйтесь к нам и помогите закончить эту работу!
Deprecated
This feature has been removed from the Web standards. Though some browsers may still support it, it is in the process of being dropped. Avoid using it and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
The Navigator.getUserMedia()
method prompts the user for permission to use up to one video input device (such as a camera or shared screen) and up to one audio input device (such as a microphone). If permission is granted, a MediaStream
whose video and/or audio tracks come from those devices is delivered to the specified success callback. If permission is denied, no compatible input devices exist, or any other error condition occurs, the error callback is executed with a MediaStreamError
object describing what went wrong. If the user instead doesn't make a choice at all, neither callback is executed.
While this method is still present, and is still callback based, every other method in the Media Capture and Streams API uses promise
s. Although technically this method isn't deprecated, we are treating it as such here because the specification warns that discussions are ongoing about whether or not it should be removed. As such, you should try to avoid using this method, and should use navigator.mediaDevices.getUserMedia()
instead.
Syntax
navigator.getUserMedia(constraints, successCallback, errorCallback);
Parameters
constraints
- A
MediaStreamConstaints
object specifying the types of media to request, along with any requirements for each type. For details, see the constraints section under the modernMediaDevices.getUserMedia()
method, as well as the article Capabilities, constraints, and settings. successCallback
- A function which is invoked when the request for media access is approved. The function is called with one parameter: the
MediaStream
object that contains the media stream. Your callback can then assign the stream to the desired object (such as an<audio>
or<video>
element), as shown in the following example:function(stream) { var video = document.querySelector('video'); video.src = window.URL.createObjectURL(stream); video.onloadedmetadata = function(e) { // Do something with the video here. }; }
errorCallback
- When the call fails, the function specified in the
errorCallback
is invokedwith aMediaStreamError
object as its sole argument; this object is is modeled onDOMException
. See {anch("Errors")}} below for a list of the errors which can occur.
Return value
Errors
Rejections of the returned promise are made by passing a DOMException
error object to the promise's failure handler. Possible errors are:
AbortError
- Although the user and operating system both granted access to the hardware device, and no hardware issues occurred that would cause a
NotReadableError
, some problem occurred which prevented the device from being used. NotAllowedError
- The user has specified that the current browsing instance is not permitted access to the device; or the user has denied access for the current session; or the user has denied all access to user media devices globally.
Older versions of the specification used
SecurityError
for this instead;SecurityError
has taken on a new meaning. NotFoundError
- No media tracks of the type specified were found that satisfy the given constraints.
NotReadableError
- Although the user granted permission to use the matching devices, a hardware error occurred at the operating system, browser, or Web page level which prevented access to the device.
OverConstrainedError
- The specified constraints resulted in no candidate devices which met the criteria requested. The error is an object of type
OverconstrainedError
, and has aconstraint
property whose string value is the name of a constraint which was impossible to meet, and amessage
property containing a human-readable string explaining the problem.Because this error can occur even when the user has not yet granted permission to use the underlying device, it can potentially be used as a fingerprinting surface. SecurityError
- User media support is disabled on the
Document
on whichgetUserMedia()
was called. The mechanism by which user media support is enabled and disabled is left up to the individual user agent. TypeError
- The list of constraints specified is empty, or has all constraints set to
false
.
Examples
Width and height
Here's an example of using getUserMedia()
, including code to cope with various browsers' prefixes. Note that this is the deprecated way of doing it: See the Examples section under the MediaDevices.getUserMedia()
for modern examples.
navigator.getUserMedia = navigator.getUserMedia || navigator.webkitGetUserMedia || navigator.mozGetUserMedia; if (navigator.getUserMedia) { navigator.getUserMedia({ audio: true, video: { width: 1280, height: 720 } }, function(stream) { var video = document.querySelector('video'); video.src = window.URL.createObjectURL(stream); video.onloadedmetadata = function(e) { video.play(); }; }, function(err) { console.log("The following error occurred: " + err.name); } ); } else { console.log("getUserMedia not supported"); }
Permissions
To use getUserMedia()
in an installable app (for example, a Firefox OS app), you need to specify one or both of the following fields inside your manifest file:
"permissions": { "audio-capture": { "description": "Required to capture audio using getUserMedia()" }, "video-capture": { "description": "Required to capture video using getUserMedia()" } }
See permission: audio-capture and permission: video-capture for more information.
Specifications
Specification | Status | Comment |
---|---|---|
Media Capture and Streams The definition of 'navigator.getUserMedia' in that specification. |
Editor's Draft | Initial definition. |
Browser compatibility
New code should use Navigator.mediaDevices.getUserMedia()
instead.
Feature | Chrome | Firefox (Gecko) | Microsoft Edge | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 21webkit [1] | 17moz [3] | (Yes) | No support | 12 [2] 18webkit |
No support |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Phone | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic Support | ? | 40.0webkit [2] | 24moz [3] | 1.2moz [4] 1.4moz |
No support | 12 [2] | No support | No support |
[1] Later versions of Chrome support unprefixed MediaDevices.getUserMedia()
, that replaced this deprecated method.
[2] Chrome and Opera still use an outdated constraint syntax, but the syntax described here is available through the adapter.js polyfill.
[3] The constraint syntax described here is available as of Firefox 38. Earlier versions (32-37) used an outdated constraint syntax, but the syntax described here is available there through the adapter.js polyfill.
[4] In Firefox OS 1.2 only audio
was supported, 1.4 added support for video
.
See also
MediaDevices.getUserMedia()
that replaces this deprecated method.- WebRTC - the introductory page to the API
- MediaStream API - the API for the media stream objects
- Taking webcam photos - a tutorial on using
getUserMedia() for taking photos rather than video.