MediaDevices.getUserMedia() 会提示用户给予使用媒体输入的许可,媒体输入会产生一个MediaStream
,里面包含了请求的媒体类型的轨道。此流可以包含一个视频轨道(来自硬件或者虚拟视频源,比如相机、视频采集设备和屏幕共享服务等等)、一个音频轨道(同样来自硬件或虚拟音频源,比如麦克风、A/D转换器等等),也可能是其它轨道类型。
它返回一个 Promise
对象,成功后会resolve回调一个 MediaStream
对象。若用户拒绝了使用权限,或者需要的媒体源不可用,promise会reject回调一个 PermissionDeniedError 或者 NotFoundError 。
返回的promise对象可能既不会resolve也不会reject,因为用户不是必须选择允许或拒绝。
通常你可以使用 navigator.mediaDevices
来获取 MediaDevices
,例如:
navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
/* 使用这个stream stream */
})
.catch(function(err) {
/* 处理error */
});
语法 :var promise = navigator.mediaDevices.getUserMedia(constraints);
参数 :constraints
作为一个MediaStreamConstraints 对象,指定了请求的媒体类型和相对应的参数。
constraints
参数是一个包含了video
和 audio
两个成员的MediaStreamConstraints
对象,用于说明请求的媒体类型。必须至少一个类型或者两个同时可以被指定。如果浏览器无法找到指定的媒体类型或者无法满足相对应的参数要求,那么返回的Promise对象就会处于rejected[失败]状态,NotFoundError
作为rejected[失败]回调的参数。
以下同时请求不带任何参数的音频和视频:
{ audio: true, video: true }
如果为某种媒体类型设置了 true ,得到的结果的流中就需要有此种类型的轨道。如果其中一个由于某种原因无法获得,getUserMedia() 将会产生一个错误。
尺寸
当由于隐私保护的原因,无法访问用户的摄像头和麦克风信息时,应用可以使用额外的constraints参数请求它所需要或者想要的摄像头和麦克风能力。下面演示了应用想要使用1280x720的摄像头分辨率:
{
audio: true,
video: { width: 1280, height: 720 }
}
浏览器会试着满足这个值,有可能返回其它的分辨率。
强制要求获取特定的尺寸时,可以使用关键字min
, max
, 或者 exact
(就是 min == max). 以下参数表示要求获取最低为1280x720的分辨率。
{
audio: true,
video: {
width: { min: 1280 },
height: { min: 720 }
}
}
不支持尺寸时:如果摄像头不支持请求的或者更高的分辨率,返回的Promise
会处于rejected
状态,NotFoundError
作为rejected
回调的参数,而且用户将不会得到要求授权的提示。
给定理想值,范围
{
audio: true,
video: {
width: { min: 1024, ideal: 1280, max: 1920 },
height: { min: 776, ideal: 720, max: 1080 }
}
}
匹配最佳摄像头或理想值:当请求包含一个ideal(应用最理想的)值时,这个值有着更高的权重,意味着浏览器会先尝试找到最接近指定的理想值的设定或者摄像头(如果设备拥有不止一个摄像头)。
针对多种媒体devices
强制使用前置摄像头(如果有的话):
{ audio: true, video: { facingMode: "user" } }
强制使用后置摄像头,请用:
{ audio: true, video: { facingMode: { exact: "environment" } } }
返回值
返回一个 Promise , 这个Promise成功后的回调函数带一个 MediaStream 对象作为其参数。
异常
返回一个失败状态的Promise
,这个Promise失败后的回调函数带一个DOMException
对象作为其参数。 可能的异常有:
代码 | 类型 | 描述 |
---|---|---|
AbortError | 中止错误 | 找不到满足请求参数的媒体类型。 |
NotAllowedError | 拒绝错误 | 用户拒绝了当前的浏览器实例的访问请求;或者用户拒绝了当前会话的访问;或者用户在全局范围内拒绝了所有媒体访问请求。较旧版本的规范使用了SecurityError,但在新版本当中SecurityError被赋予了新的意义。 |
NotFoundError | 找不到错误 | 找不到满足请求参数的媒体类型。 |
NotReadableError | 无法读取错误 | 尽管用户已经授权使用相应的设备,操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。 |
OverConstrainedError | 无法满足要求错误 | 指定的要求无法被设备满足,此异常是一个类型为OverconstrainedError的对象,拥有一个constraint属性,这个属性包含了当前无法被满足的constraint对象,还拥有一个message属性,包含了阅读友好的字符串用来说明情况。因为这个异常甚至可以在用户尚未授权使用当前设备的情况下抛出,所以应当可以当作一个探测设备能力属性的手段[fingerprinting surface]。 |
SecurityError | 安全错误 | 在getUserMedia() 被调用的 Document 上面,使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。 |
TypeError | 类型错误 | constraints对象未设置[空],或者都被设置为false。 |