media

1. mediaDevices

mediaDevices接口提供访问连接媒体输入的设备，如照相机和麦克风，以及屏幕共享等。它可以使你取得任何硬件资源的媒体数据。

1-1. enumerateDevices

MediaDevices 的方法 enumerateDevices() 请求一个可用的媒体输入和输出设备的列表，例如麦克风，摄像机，耳机设备等。 返回的 Promise (en-US) 完成时，会带有一个描述设备的 MediaDeviceInfo (en-US) 的数组

var enumeratorPromise = navigator.mediaDevices.enumerateDevices();

返回一个 Promise (en-US) 。当完成时，它接收一个 MediaDeviceInfo (en-US) 对象的数组。每个对象描述一个可用的媒体输入输出设备。.

1-1-1. MediaDeviceInfo

MediaDeviceInfo接口包含描述单个媒体输入或输出设备的信息。

通过调用navigator.mediaDevices.enumerateDevices()获得的设备列表是一个MediaDeviceInfo对象的数组，每个媒体设备一个。

1-2. getUserMedia()

MediaDevices.getUserMedia() 会提示用户给予使用媒体输入的许可，媒体输入会产生一个MediaStream，里面包含了请求的媒体类型的轨道。此流可以包含一个视频轨道（来自硬件或者虚拟视频源，比如相机、视频采集设备和屏幕共享服务等等）、一个音频轨道（同样来自硬件或虚拟音频源，比如麦克风、A/D 转换器等等），也可能是其它轨道类型。

它返回一个 Promise 对象，成功后会resolve回调一个 MediaStream 对象。若用户拒绝了使用权限，或者需要的媒体源不可用，promise会reject回调一个 PermissionDeniedError 或者 NotFoundError 。

navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
  /* 使用这个 stream stream */
})
.catch(function(err) {
  /* 处理 error */
});

1-2-1. getUserMedia 参数 constraints

作为一个MediaStreamConstraints (en-US) 对象，指定了请求的媒体类型和相对应的参数。

constraints 参数是一个包含了video 和 audio两个成员的MediaStreamConstraints 对象，用于说明请求的媒体类型。必须至少一个类型或者两个同时可以被指定。如果浏览器无法找到指定的媒体类型或者无法满足相对应的参数要求，那么返回的 Promise 对象就会处于 rejected［失败］状态，NotFoundError作为 rejected［失败］回调的参数。

• audio 属性： 音频输入源 (Boolean|MediaDeviceInfo|Object)
• video 属性： 视频输入源 (Boolean|MediaDeviceInfo|Object)

{ audio: true, video: true }

参考文档

1-2-2. getUserMedia 成功返回值 stream

MediaStream 接口是一个媒体内容的流.。一个流包含几个轨道，比如视频和音频轨道。

1-2-2-1 属性

• 属性MediaStream.active 只读

    布尔型。如果这个流处于活动状态值为 true，反之为 false
  

• MediaStream.id 只读

    这是一个包含 36 个字符的 DOMString ，用来作为这个对象的唯一标识符 (GUID) 。
  

• MediaStream.ended 只读

    布尔型。如果 ended 事件在这个对象上触发了，也就是说这个流已经被完全读取，值为 true。 如果还没有到达这个流的尾部，值为 false。
  

1-2-2-2 事件

• MediaStream.onaddtrack (en-US)

    这是addtrack事件在这个对象上触发时调用的事件处理器 [event handler]，这时一个MediaStreamTrack对象被添加到这个流。
  

• MediaStream.onended

    这是当流终止 [ended] 时触发的事件。
  

• MediaStream.onremovetrack (en-US)

    这是removetrack事件在这个对象上触发事调用的事件处理器 [event handler]，这时一个对象从流上移除。
  

1-2-2-3 api方法

• MediaStream.addTrack()

    存储传入参数 MediaStreamTrack 的一个副本。如果这个轨道已经被添加到了这个媒体流，什么也不会发生; 如果目标轨道为“完成”状态（也就是已经到尾部了），一个 INVALID_STATE_RAISE 异常会产生。 
  

• MediaStream.clone()

    返回这个MediaStream 对象的克隆版本。返回的版本会有一个新的 ID。
    返回给定 ID 的轨道。如果没有参数或者没有指定 ID 的轨道，将返回 null。如果有几个轨道有同一个 ID，将返回第一个。 
  

• MediaStream.getTracks()

    返回流中所有的MediaStreamTrack列表。
  

• MediaStream.getAudioTracks()

    返回流中 kind 属性为"audio"的MediaStreamTrack列表。顺序是不确定的，不同浏览器间会有不同，每次调用也有可能不同。
  

• MediaStream.getTrackById() (en-US)

    返回给定 ID 的轨道。如果没有参数或者没有指定 ID 的轨道，将返回 null。如果有几个轨道有同一个 ID，将返回第一个。 
  

• MediaStream.getVideoTracks() (en-US)

    返回流中 kind 属性为"video"的MediaStreamTrack列表。顺序是不确定的，不同浏览器间会有不同，每次调用也有可能不同。
  

• MediaStream.removeTrack()

    移除作为参数传入的 MediaStreamTrack。 如果这个轨道不在MediaStream 对象中什么也不会发生； 如果目标轨道为“完成”状态，一个 INVALID_STATE_RAISE 异常会产生。 
  

1-2-3 MediaStreamTrack

MediaStreamTrack 接口在 User Agent 中表示一段媒体源，比如音轨或视频。

1-2-3-1 属性

• MediaStreamTrack.enabled (en-US)

    布尔值，为 true 时表示轨道有效，并且可以被渲染。为 false 时表示轨道失效，只能被渲染为静音或黑屏。如果该轨道连接中断，该值还是可以被改变但不会有任何效果了。
  

• MediaStreamTrack.id (en-US) 只读

    返回一个由浏览器产生的DOMString类型的 GUID 值，作为这个轨道的唯一标识值。
  

• MediaStreamTrack.kind (en-US) 只读

    返回一个DOMString类型的值。如果为“audio”表示轨道为音频轨道，为“video”则为视频轨道。如果该轨道从它的源上分离，这个值也不会改变。
  

• MediaStreamTrack.label (en-US) 只读

    返回一个DOMString类型。内容为一个用户代理指定的标签，来标识该轨道的来源，比如“internal microphone”。该字符串可以为空，并且在没有源与这个轨道连接的情况下会一直为空。当该轨道从它的源上分离时，这个值也不会改变。
  

• MediaStreamTrack.muted (en-US) 只读

  返回一个布尔类型的值，为 true 时表示轨道是静音，其它为 false。

• MediaStreamTrack.readonly 只读

  返回一个布尔类型的值，为 true 时表示该轨道是只读的，比如视频文件源或一个被设置为不能修改的摄像头源，或则为 false。

• MediaStreamTrack.readyState 只读

    返回枚举类型的值，表示轨道的当前状态。该枚举值为以下中的一个：
  
    "live"表示当前输入已经连接并且在尽力提供实时数据。在这种情况下，输出数据可以通过操作 MediaStreamTrack.enabled 属性进行开关。
    “ended”表示这个输出连接没有更多的数据了，而且也不会提供更多的数据了。
  

• MediaStreamTrack.remote (en-US) 只读

    返回布尔值类型，当为 true 时表示数据是通过RTCPeerConnection提供的，否则为 false。 
  

1-2-3-2 事件

• MediaStreamTrack.onstarted

    这是started事件在这个对象上被触发时调用的事件处理器event handler，这时一个新的MediaStreamTrack对象被添加到轨道源上。
  

• MediaStreamTrack.onmute (en-US)

    这是mute事件在这个对象被触发时调用的事件处理器event handler，这时这个流被中断。
  

• MediaStreamTrack.onunmute (en-US)

    这是unmute事件在这个对象上被触发时调用的事件处理器event handler，未实现。
  

• MediaStreamTrack.onoverconstrained (en-US)

    这是overconstrained事件在这个对象上被触发时调用的事件处理器overconstrained，未实现。
  

• MediaStreamTrack.oneended

    这是ended事件在这个对象被触发时调用的事件处理器event handler，未实现。 
  

1-2-3-1 方法

• MediaStreamTrack.getConstraints()

    获取约束 这些约束指示网站或应用程序指定的值和值范围对于包含的可约束属性是必需的或可接受的。
  

• MediaStreamTrack.applyConstraints()

    将一组约束应用到轨道;这些约束让网站或应用程序为轨道的可限制属性(如帧率、尺寸、回声消除等)建立理想值和可接受的值范围。
  

• MediaStreamTrack.getSettings()

    返回一个MediaTrackSettings对象，该对象包含当前MediaStreamTrack的每个可限制属性的当前值。
  

• MediaStreamTrack.getCapabilities()

    返回一个  MediaTrackCapabilities 对象，此对象表示每个可调节属性的值或者范围，该特性依赖于平台和user agent.  
  

• MediaStreamTrack.clone()

    创建一个MediaStreamTrack的副本。这个新的MediaStreamTrack对象除了唯一的id之外是相同的。
  

• MediaStreamTrack.stop()

    停止播放轨道对应的源，源与轨道将脱离关联，同时轨道状态将设为“ended”。 
  

参考文档

1-3. getDisplayMedia()

这个 MediaDevices 接口的 getDisplayMedia() 方法提示用户去选择和授权捕获展示的内容或部分内容（如一个窗口）在一个 MediaStream 里. 然后，这个媒体流可以通过使用 MediaStream Recording API 被记录或者作为WebRTC 会话的一部分被传输。

示例

var promise = navigator.mediaDevices.getDisplayMedia(constraints);

2. MediaRecorder

    MediaRecorder() 构造函数会创建一个对指定的 MediaStream 进行录制的 MediaRecorder 对象

var mediaRecorder = new MediaRecorder(stream, options);

2-1. 参数

• stream

  媒体流

• option

  一个字典对象，它可以包含下列属性：

  • mimeType: 为新构建的 MediaRecorder 指定录制容器的 MIME 类型。在应用中通过调用 MediaRecorder.isTypeSupported() 来检查浏览器是否支持此种mimeType .
  • audioBitsPerSecond: 指定音频的比特率。
  • videoBitsPerSecond: 指定视频的比特率。
  • bitsPerSecond: 指定音频和视频的比特率。此属性可以用来指定上面两个属性. 如果上面两个属性只有其中之一和此属性被指定，则此属性可以用于设定另外一个属性。

2-2. MediaRecorder 对象

2-2-1. 属性

• MediaRecorder.mimeType (en-US) 只读

    返回 MediaRecorder 对象创建时选择器选择的录制容器的 MIME type
  

• MediaRecorder.state (en-US) 只读

    返回录制对象MediaRecorder  的当前状态 (闲置中，录制中或者暂停 ) (inactive, recording, or paused.)
  

• MediaRecorder.stream (en-US) 只读

    返回录制器对象 MediaRecorder 创建时构造函数传入的 stream 对象
  

• MediaRecorder.ignoreMutedMedia

    用以指定 MediaRecorder是否录制无声的输入源。如果这个属性是 false. 录制器对象MediaRecorder  会录制无声的音频或者黑屏的视频，默认值是 false
  

• MediaRecorder.videoBitsPerSecond (en-US) 只读

    返回视频采用的编码比率。它可能和构造函数的设置比率不同.  (if it was provided).
  

• MediaRecorder.audioBitsPerSecond 只读

    返回音频采用的编码比率，它可能和构造函数中设置的比率不同. (if it was provided).
  

2-2-2. 方法

• MediaRecorder.isTypeSupported() (en-US)

    返回一个Boolean (en-US) 值，来表示设置的 MIME type 是否被当前用户的设备支持。
  

• MediaRecorder.pause()

    暂停媒体录制
  

• MediaRecorder.requestData() (en-US)

    请求一个从开始到当前接收到的，存储为Blob类型的录制内容. (或者是返回从上一次调用requestData() 方法之后到现在的内容).  调用这个方法后，录制将会继续进行，但是会创建一个新的Blob对象
  

• MediaRecorder.resume() (en-US)

    继续录制之前被暂停的录制动作。
  

• MediaRecorder.start() (en-US)

    开始录制媒体，这个方法调用时可以通过给timeslice参数设置一个毫秒值，如果设置这个毫秒值，那么录制的媒体会按照你设置的值进行分割成一个个单独的区块，而不是以默认的方式录制一个非常大的整块内容。
  

• MediaRecorder.stop() (en-US)

    停止录制。同时触发dataavailable事件，返回一个存储Blob内容的录制数据。之后不再记录
  

2-2-3. 静态方法

• MediaRecorder.isTypeSupported()

    静态方法，判断给定的 MIME 类型是否支持。返回Boolean (en-US)类型的值。
  

2-2-4. 事件处理

• MediaRecorder.ondataavailable

    调用它用来处理 dataavailable 事件，该事件可用于获取录制的媒体资源 (在事件的 data 属性中会提供一个可用的 Blob 对象.)
  

• MediaRecorder.onerror (en-US)

    一个事件处理程序，用于处理recordingerror事件，包括媒体记录时出现的报告错误。这些是停止记录的致命错误。
  

• MediaRecorder.onpause (en-US)

    用来处理 pause (en-US) 事件，该事件在媒体暂停录制时触发（MediaRecorder.pause()）.
  

• MediaRecorder.onresume (en-US)

    用来处理 resume 事件，该事件在暂停后回复录制视频时触发（MediaRecorder.resume() (en-US)）.
  

• MediaRecorder.onstart (en-US)

    用来处理 start 事件，该事件在媒体开始录制时触发（MediaRecorder.start() (en-US)）.
  

• MediaRecorder.onstop (en-US)

    用来处理 stop 事件，该事件会在媒体录制结束时、媒体流（MediaStream）结束时、或者调用MediaRecorder.stop() (en-US) 方法后触发。