Media capture and constraints
媒体捕获和限制
The media part of WebRTC covers how to access hardware capable of capturing video and audio, such as cameras and microphones, as well as how media streams work. It also covers display media, which is how an application can do screen capturing.
WebRTC的媒体部分涵盖了如何访问能够捕获视频和音频的硬件,如相机和麦克风,以及媒体流如何工作。还涵盖了显示媒体,即应用程序如何进行屏幕捕获。
Media devices
媒体设备
All cameras and microphones that are supported by the browser are accessed and managed through the navigator.mediaDevices
object. Applications can retrieve the current list of connected devices and also listen for changes, since many cameras and microhpones connect through USB and can be connected and disconnected during the lifecycle of the application. Since the state of a media device can change at any time, it is recommended that applications register for device changes in order to properly handle changes.
浏览器支持的所有摄像头和麦克风都可以通过navigator.mediaDevices对象进行访问和管理。应用程序可以检索当前连接设备的列表,也可以监听变化,因为许多摄像头和microhpone都是通过USB连接的,并且可以在应用程序的生命周期中进行连接和断开连接。由于媒体设备的状态可以随时更改,因此建议应用程序注册设备更改,以便正确处理更改。
Constraints
限制
When accessing media devices, it is a good practice to provide as detailed constraints as possible. While it is possible to open the default camera and microphone with a simple constraint, it might deliver a media stream that is far from the most optimal for the application.
访问媒体设备时,最好提供尽可能详细的约束。虽然可以通过简单的约束打开默认的摄像头和麦克风,但它可能会提供远不是应用程序最佳的媒体流。
The specific constraints are defined in a MediaTrackConstraint
object, one for audio and one for video. The attributes in this object are of type ConstraintLong
, ConstraintBoolean
, ConstraintDouble
or ConstraintDOMString
. These can either be a specific value (e.g., a number, boolean or string), a range (LongRange
or DoubleRange
with a minimum and maximum value) or an object with either an ideal
or exact
definition. For a specific value, the browser will attempt to pick something as close as possible. For a range, the best value in that range will be used. When exact
is specified, only media streams that exactly match that constraint will be returned.
特定约束在MediaTrackConstraint对象中定义,一个用于音频,一个则用于视频。此对象中的属性类型为ConstraintLong、ConstraintBoolean、ConstraintDouble或ConstraintDOMString。它们可以是特定值(例如,数字、布尔值或字符串)、范围(具有最小值和最大值的LongRange或DoubleRange)或具有理想或精确定义的对象。对于特定的值,浏览器将尝试选择尽可能接近的值。对于一个范围,将使用该范围中的最佳值。当指定精确时,将只返回与该约束完全匹配的媒体流。
NEAR
近似
// Camera with a resolution as close to 640x480 as possible
{
"video": {
"width": 640,
"height": 480
}
}
RANGE
范围
// Camera with a resolution in the range 640x480 to 1024x768
{
"video": {
"width": {
"min": 640,
"max": 1024
},
"height": {
"min": 480,
"max": 768
}
}
}
EXACT
精确
// Camera with the exact resolution of 1024x768
{
"video": {
"width": {
"exact": 1024
},
"height": {
"exact": 768
}
}
}
To determine the actual configuration a certain track of a media stream has, we can call MediaStreamTrack.getSettings()
which returns the MediaTrackSettings
currently applied.
要确定媒体流的某个轨道的实际配置,我们可以调用MediaStreamTrack.getSettings(),它返回当前应用的MediaTrackSettings。
It is also possible to update the constraints of a track from a media device we have opened, by calling applyConstraints()
on the track. This lets an application re-configure a media device without first having to close the existing stream.
也可以通过调用轨道上的applyConstraints(),从打开的媒体设备更新轨道的约束。这允许应用程序重新配置媒体设备,而无需首先关闭现有流。
Display media
显示媒体数据
An application that wants to be able to perform screen capturing and recording must use the Display Media API. The function getDisplayMedia()
(which is part of navigator.mediaDevices
is similar to getUserMedia()
and is used for the purpose of opening the content of the display (or a portion of it, such as a window). The returned MediaStream
works the same as when using getUserMedia()
.
想要执行屏幕捕获和录制的应用程序必须使用显示媒体API。函数getDisplayMedia()(它是navigator.mediaDevices的一部分)类似于getUserMedia(),用于打开显示器的内容(或其中的一部分,如窗口)。返回的MediaStream与使用getUserMedia()时的工作原理相同。
The constraints for getDisplayMedia()
differ from the ones used for regular video or audio input.
getDisplayMedia()的约束与用于常规视频或音频输入的约束不同。
{
video: {
cursor: 'always' | 'motion' | 'never',
displaySurface: 'application' | 'browser' | 'monitor' | 'window'
}
}
The code snipet above shows how the special constraints for screen recording works. Note that these might not be supported by all browsers that have display media support.
上面的代码片段显示了屏幕录制的特殊约束是如何工作的。请注意,并非所有支持显示媒体的浏览器都支持这些功能。
Streams and tracks
流和轨道
A MediaStream
represents a stream of media content, which consists of tracks (MediaStreamTrack
) of audio and video. You can retrieve all the tracks from MediaStream
by calling MediaStream.getTracks()
, which returns an array of MediaStreamTrack
objects.
MediaStream表示媒体内容流,由音频和视频的音轨(MediaStreamTrack)组成。可以通过调用MediaStream.getTracks()从MediaStream中检索所有轨道,返回一个MediaStreamTrack对象数组。
MediaStreamTrack
媒体流轨道
A MediaStreamTrack
has a kind
property that is either audio
or video
, indicating the kind of media it represents. Each track can be muted by toggling its enabled
property. A track has a Boolean property remote
that indicates if it is sourced by a RTCPeerConnection
and coming from a remote peer.
MediaStreamTrack有一个音频或视频的种类属性,指示它所代表的媒体种类。每个轨迹都可以通过切换其启用的属性来静音。轨道有一个布尔属性remote,用于指示它是否由RTCPeerConnection来源并来自远程对等源。