WEBRTC

WebRTC

目录

简介

架构

1.    WebRTC架构组件介绍

2.    Network Stream API

3.    RTCPeerConnection

4.    Peer-to-peer Data API

相关

分析

1.    视频

2.    音频

展开

简介

架构

1.    WebRTC架构组件介绍

2.    Network Stream API

3.    RTCPeerConnection

4.    Peer-to-peer Data API

相关

分析

1.    视频

2.    音频

展开

编辑本段简介

　　WebRTC是一项在浏览器内部进行实时视频和音频通信的技术，是谷歌2010年以6820万美元收购Global IP Solutions公司而获得一项技术。^[1]

　　WebRTC实现了基于网页的视频会议，标准是WHATWG 协议，目的是通过浏览器提供简单的javascript就可以达到实时通讯（Real-Time Communications (RTC)）能力。

　　WebRTC（Web Real-Time Communication）项目的最终目的主要是让Web开发者能够基于浏览器（Chrome\FireFox\...）轻易快捷开发出丰富的实时多媒体应用，而无需下载安装任何插件，Web开发者也无需关注多媒体的数字信号处理过程，只需编写简单的Javascript程序即可实现，W3C等组织正在制定Javascript 标准API，目前是WebRTC 1.0版本，Draft状态；另外WebRTC还希望能够建立一个多互联网浏览器间健壮的实时通信的平台，形成开发者与浏览器厂商良好的生态环境。同时，Google也希望和致力于让WebRTC的技术成为HTML5标准之一，可见Google布局之深远。^[2]

　　WebRTC提供了视频会议的核心技术，包括音视频的采集、编解码、网络传输、显示等功能，并且还支持跨平台：windows，linux，mac，android。

编辑本段架构

　　

  

WebRTC架构图

　　架构图颜色标识说明：^[3]

　　（1）紫色部分是Web开发者API层；

　　（2）蓝色实线部分是面向浏览器厂商的API层

　　（3）蓝色虚线部分浏览器厂商可以自定义实现

WebRTC架构组件介绍

　　(1) Your Web App

　　Web开发者开发的程序，Web开发者可以基于集成WebRTC的浏览器提供的web API开发基于视频、音频的实时通信应用。^[2]

　　(2) Web API

　　面向第三方开发者的WebRTC标准API（Javascript），使开发者能够容易地开发出类似于网络视频聊天的web应用，最新的标准化进程可以查看这里。

　　这些API可分成Network Stream API、 RTCPeerConnection、Peer-to-peer Data API三类,详细的API说明可以看这里^[4]。

Network Stream API

　　MediaStream：MediaStream用来表示一个媒体数据流。

　　MediaStreamTrack在浏览器中表示一个媒体源。

RTCPeerConnection

　　RTCPeerConnection: 一个RTCPeerConnection对象允许用户在两个浏览器之间直接通讯。

　　RTCIceCandidate ：表示一个ICE协议的候选者。

　　RTCIceServer:表示一个ICE Server。

Peer-to-peer Data API

　　DataChannel:数据通道( DataChannel)接口表示一个在两个节点之间的双向的数据通道。

　　(3) WebRTC Native C++ API

　　本地C++ API层，使浏览器厂商容易实现WebRTC标准的Web API，抽象地对数字信号过程进行处理。

　　(4) Transport / Session

　　传输/会话层

　　会话层组件采用了libjingle库的部分组件实现，无须使用xmpp/jingle协议

　　a. RTP Stack协议栈

　　Real Time Protocol

　　b. STUN/ICE

　　可以通过STUN和ICE组件来建立不同类型网络间的呼叫连接。

　　c. Session Management

　　一个抽象的会话层，提供会话建立和管理功能。该层协议留给应用开发者自定义实现。

　　(5) VoiceEngine

　　音频引擎是包含一系列音频多媒体处理的框架，包括从视频采集卡到网络传输端等整个解决方案。

　　PS：VoiceEngine是WebRTC极具价值的技术之一，是Google收购GIPS公司后开源的。在VoIP上，技术业界领先，后面的文章会详细了解

　　a. iSAC

　　Internet Speech Audio Codec

　　针对VoIP和音频流的宽带和超宽带音频编解码器，是WebRTC音频引擎的默认的编解码器

　　采样频率：16khz，24khz，32khz；（默认为16khz）

　　自适应速率为10kbit/s ~ 52kbit/；

　　自适应包大小：30~60ms；

　　算法延时：frame + 3ms

　　b. iLBC

　　Internet Low Bitrate Codec

　　VoIP音频流的窄带语音编解码器

　　采样频率：8khz；

　　20ms帧比特率为15.2kbps

　　30ms帧比特率为13.33kbps

　　标准由IETF RFC3951和RFC3952定义

　　c. NetEQ for Voice

　　针对音频软件实现的语音信号处理元件

　　NetEQ算法：自适应抖动控制算法以及语音包丢失隐藏算法。使其能够快速且高解析度地适应不断变化的网络环境，确保音质优美且缓冲延迟最小。

　　是GIPS公司独步天下的技术，能够有效的处理由于网络抖动和语音包丢失时候对语音质量产生的影响。

　　PS：NetEQ 也是WebRTC中一个极具价值的技术，对于提高VoIP质量有明显效果，加以AEC\NR\AGC等模块集成使用，效果更好。

　　d. Acoustic Echo Canceler (AEC)

　　回声消除器是一个基于软件的信号处理元件，能实时的去除mic采集到的回声。

　　e. Noise Reduction (NR)

　　噪声抑制也是一个基于软件的信号处理元件，用于消除与相关VoIP的某些类型的背景噪声（嘶嘶声，风扇噪音等等… …）

　　(6) VideoEngine

　　WebRTC视频处理引擎

　　VideoEngine是包含一系列视频处理的整体框架，从摄像头采集视频到视频信息网络传输再到视频显示整个完整过程的解决方案。

　　a. VP8

　　视频图像编解码器，是WebRTC视频引擎的默认的编解码器

　　VP8适合实时通信应用场景，因为它主要是针对低延时而设计的编解码器。

　　PS:VPx编解码器是Google收购ON2公司后开源的，VPx现在是WebM项目的一部分，而WebM项目是Google致力于推动的HTML5标准之一

　　b. Video Jitter Buffer

　　视频抖动缓冲器，可以降低由于视频抖动和视频信息包丢失带来的不良影响。

　　c. Image enhancements

　　图像质量增强模块

　　对网络摄像头采集到的图像进行处理，包括明暗度检测、颜色增强、降噪处理等功能，用来提升视频质量。

编辑本段相关

　　谷歌2011年6月3日宣布向开发人员开放WebRTC架构的源代码。这个源代码将根据没有专利费的BSD（伯克利软件发布）式的许可证向用户提供。^[5]目前，开发人员可访问并获取WebRTC的源代码、规格说明和工具等。^[1]

编辑本段分析

视频

　　WebRTC的视频部分，包含采集、编解码(I420/VP8)、加密、媒体文件、图像处理、显示、网络传输与流控(RTP/RTCP)等功能。

　　视频采集---video_capture

　　源代码在webrtc\modules\video_capture\main目录下，包含接口和各个平台的源代码。

　　在windows平台上，WebRTC采用的是dshow技术，来实现枚举视频的设备信息和视频数据的采集，这意味着可以支持大多数的视频采集设备；对那些需要单独驱动程序的视频采集卡（比如海康高清卡）就无能为力了。

　　视频采集支持多种媒体类型，比如I420、YUY2、RGB、UYUY等，并可以进行帧大小和帧率控制。

　　视频编解码---video_coding 　　

源代码在webrtc\modules\video_coding目录下。

　　WebRTC采用I420/VP8编解码技术。VP8是google收购ON2后的开源实现，并且也用在WebM项目中。VP8能以更少的数据提供更高质量的视频，特别适合视频会议这样的需求。

　　视频加密--video_engine_encryption 　　

视频加密是WebRTC的video_engine一部分，相当于视频应用层面的功能，给点对点的视频双方提供了数据上的安全保证，可以防止在Web上视频数据的泄漏。

　　视频加密在发送端和接收端进行加解密视频数据，密钥由视频双方协商，代价是会影响视频数据处理的性能；也可以不使用视频加密功能，这样在性能上会好些。

　　视频加密的数据源可能是原始的数据流，也可能是编码后的数据流。估计是编码后的数据流，这样加密代价会小一些，需要进一步研究。

　　视频媒体文件--media_file 　　

源代码在webrtc\modules\media_file目录下。

　　该功能是可以用本地文件作为视频源，有点类似虚拟摄像头的功能；支持的格式有Avi。

　　另外，WebRTC还可以录制音视频到本地文件，比较实用的功能。

　　视频图像处理--video_processing 　　

源代码在webrtc\modules\video_processing目录下。

　　视频图像处理针对每一帧的图像进行处理，包括明暗度检测、颜色增强、降噪处理等功能，用来提升视频质量。

　　视频显示--video_render 　　

源代码在webrtc\modules\video_render目录下。

　　在windows平台，WebRTC采用direct3d9和directdraw的方式来显示视频，只能这样，必须这样。

　　网络传输与流控 　　

对于网络视频来讲，数据的传输与控制是核心价值。WebRTC采用的是成熟的RTP/RTCP技术。

音频

　　WebRTC的音频部分，包含设备、编解码(iLIBC/iSAC/G722/PCM16/RED/AVT、NetEQ)、加密、声音文件、声音处理、声音输出、音量控制、音视频同步、网络传输与流控(RTP/RTCP)等功能。

　　音频设备---audio_device 　　

源代码在webrtc\modules\audio_device\main目录下，包含接口和各个平台的源代码。

　　在windows平台上，WebRTC采用的是Windows Core Audio和Windows Wave技术来管理音频设备，还提供了一个混音管理器。

　　利用音频设备，可以实现声音输出，音量控制等功能。

　　音频编解码---audio_coding 　　

源代码在webrtc\modules\audio_coding目录下。

　　WebRTC采用iLIBC/iSAC/G722/PCM16/RED/AVT编解码技术。

　　WebRTC还提供NetEQ功能---抖动缓冲器及丢包补偿模块，能够提高音质，并把延迟减至最小。

　　另外一个核心功能是基于语音会议的混音处理。

　　声音加密--voice_engine_encryption 　　

和视频一样，WebRTC也提供声音加密功能。

　　声音文件 　　

该功能是可以用本地文件作为音频源，支持的格式有Pcm和Wav。

　　同样，WebRTC也可以录制音频到本地文件。

　　声音处理--audio_processing 　　

源代码在webrtc\modules\audio_processing目录下。

　　声音处理针对音频数据进行处理，包括回声消除(AEC)、AECM、自动增益(AGC)、降噪处理等功能，用来提升声音质量。

　　网络传输与流控 　　

和视频一样，WebRTC采用的是成熟的RTP/RTCP技术。

 

 

http://sites.google.com/site/webrtc/

 

1、WebRTC目的

       

       WebRTC（Web Real-Time Communication）项目的最终目的主要是让Web开发者能够基于浏览器（Chrome\FireFox\...）轻易快捷开发出丰富的实时多媒体应用，而无需下载安装任何插件，Web开发者也无需关注多媒体的数字信号处理过程，只需编写简单的Javascript程序即可实现，W3C等组织正在制定Javascript 标准API，目前是WebRTC 1.0版本，Draft状态，网址；另外WebRTC还希望能够建立一个多互联网浏览器间健壮的实时通信的平台，形成开发者与浏览器厂商良好的生态环境。同时，Google也希望和致力于让WebRTC的技术成为HTML5标准之一，可见Google布局之深远。

 

 

2、WebRTC架构图

 

架构图颜色标识说明：

（1）紫色部分是Web开发者API层；

（2）蓝色实线部分是面向浏览器厂商的API层（也就是红色框标内模块，也是本人专注研究的部分）

（3）蓝色虚线部分浏览器厂商可以自定义实现

 

3、WebRTC架构组件介绍

 

(1) Your Web App
Web开发者开发的程序，Web开发者可以基于集成WebRTC的浏览器提供的web API开发基于视频、音频的实时通信应用。

 

(2) Web API
面向第三方开发者的WebRTC标准API（Javascript），使开发者能够容易地开发出类似于网络视频聊天的web应用，最新的标准化进程可以查看这里。

(3) WebRTC Native C++ API
本地C++ API层，使浏览器厂商容易实现WebRTC标准的Web API，抽象地对数字信号过程进行处理。

 

(4) Transport / Session

传输/会话层

会话层组件采用了libjingle库的部分组件实现，无须使用xmpp/jingle协议

a.  RTP Stack协议栈
Real Time Protocol

b.  STUN/ICE
可以通过STUN和ICE组件来建立不同类型网络间的呼叫连接。

c.  Session Management
一个抽象的会话层，提供会话建立和管理功能。该层协议留给应用开发者自定义实现。

 

(5) VoiceEngine
音频引擎是包含一系列音频多媒体处理的框架，包括从视频采集卡到网络传输端等整个解决方案。
PS：VoiceEngine是WebRTC极具价值的技术之一，是Google收购GIPS公司后开源的。在VoIP上，技术业界领先，后面的文章会详细了解

 

a.  iSAC

Internet Speech Audio Codec

针对VoIP和音频流的宽带和超宽带音频编解码器，是WebRTC音频引擎的默认的编解码器
采样频率：16khz，24khz，32khz；（默认为16khz）
自适应速率为10kbit/s ~ 52kbit/；
自适应包大小：30~60ms；
算法延时：frame + 3ms

 

b.  iLBC
Internet Low Bitrate Codec
VoIP音频流的窄带语音编解码器
采样频率：8khz；
20ms帧比特率为15.2kbps
30ms帧比特率为13.33kbps
标准由IETF RFC3951和RFC3952定义

c.  NetEQ for Voice

针对音频软件实现的语音信号处理元件

NetEQ算法：自适应抖动控制算法以及语音包丢失隐藏算法。使其能够快速且高解析度地适应不断变化的网络环境，确保音质优美且缓冲延迟最小。

是GIPS公司独步天下的技术，能够有效的处理由于网络抖动和语音包丢失时候对语音质量产生的影响。

PS：NetEQ 也是WebRTC中一个极具价值的技术，对于提高VoIP质量有明显效果，加以AEC\NR\AGC等模块集成使用，效果更好。

 

d.  Acoustic Echo Canceler (AEC)
回声消除器是一个基于软件的信号处理元件，能实时的去除mic采集到的回声。

 

e.  Noise Reduction (NR)
噪声抑制也是一个基于软件的信号处理元件，用于消除与相关VoIP的某些类型的背景噪声（嘶嘶声，风扇噪音等等… …）

 

(6) VideoEngine
WebRTC视频处理引擎
VideoEngine是包含一系列视频处理的整体框架，从摄像头采集视频到视频信息网络传输再到视频显示整个完整过程的解决方案。

 

a.  VP8
视频图像编解码器，是WebRTC视频引擎的默认的编解码器
VP8适合实时通信应用场景，因为它主要是针对低延时而设计的编解码器。
PS:VPx编解码器是Google收购ON2公司后开源的，VPx现在是WebM项目的一部分，而WebM项目是Google致力于推动的HTML5标准之一

 

b.  Video Jitter Buffer
视频抖动缓冲器，可以降低由于视频抖动和视频信息包丢失带来的不良影响。

 

c.  Image enhancements
图像质量增强模块
对网络摄像头采集到的图像进行处理，包括明暗度检测、颜色增强、降噪处理等功能，用来提升视频质量。

 

 

4、WebRTC核心模块API

 

(1)、网络传输模块：libjingle

WebRTC重用了libjingle的一些组件，主要是network和transport组件，关于libjingle的文档资料可以查看这里。

 

(2)、音频、视频图像处理的主要数据结构

常量\VideoEngine\VoiceEngine

 

注意：以下所有的方法、类、结构体、枚举常量等都在webrtc命名空间里  

类、结构体、枚举常量	头文件	说明
Structures	common_types.h	Lists the structures common to the VoiceEngine & VideoEngine
Enumerators	common_types.h	List the enumerators common to the  VoiceEngine & VideoEngine
Classes	common_types.h	List the classes common to VoiceEngine & VideoEngine
class VoiceEngine	voe_base.h	How to allocate and release resources for the VoiceEngine using factory methods in the VoiceEngine class. It also lists the APIs which are required to enable file tracing and/or traces as callback messages
class VideoEngine	vie_base.h	How to allocate and release resources for the VideoEngine using factory methods in the VideoEngine class. It also lists the APIs which are required to enable file tracing and/or traces as callback messages

 

(3)、音频引擎（VoiceEngine）模块 APIs

 

下表列的是目前在 VoiceEngine中可用的sub APIs

sub-API	头文件	说明
VoEAudioProcessing	voe_audio_processing.h	Adds support for Noise Suppression (NS), Automatic Gain Control (AGC) and Echo Control (EC). Receiving side VAD is also included.
VoEBase	voe_base.h	Enables full duplex VoIP using G.711. NOTE: This API must always be created.
VoECallReport	voe_call_report.h	Adds support for call reports which contains number of dead-or-alive detections, RTT measurements, and Echo metrics.
VoECodec	voe_codec.h	Adds non-default codecs (e.g. iLBC, iSAC, G.722 etc.), Voice Activity Detection (VAD) support.
VoEDTMF	voe_dtmf.h	Adds telephone event transmission, DTMF tone generation and telephone event detection. (Telephone events include DTMF.)
VoEEncryption	voe_encryption.h	Adds external encryption/decryption support.
VoEErrors	voe_errors.h	Error Codes for the VoiceEngine
VoEExternalMedia	voe_external_media.h	Adds support for external media processing and enables utilization of an external audio resource.
VoEFile	voe_file.h	Adds file playback, file recording and file conversion functions.
VoEHardware	voe_hardware.h	Adds sound device handling, CPU load monitoring and device information functions.
VoENetEqStats	voe_neteq_stats.h	Adds buffer statistics functions.
VoENetwork	voe_network.h	Adds external transport, port and address filtering, Windows QoS support and packet timeout notifications.
VoERTP_RTCP	voe_rtp_rtcp.h	Adds support for RTCP sender reports, SSRC handling, RTP/RTCP statistics, Forward Error Correction (FEC), RTCP APP, RTP capturing and RTP keepalive.
VoEVideoSync	voe_video_sync.h	Adds RTP header modification support, playout-delay tuning and monitoring.
VoEVolumeControl	voe_volume_control.h	Adds speaker volume controls, microphone volume controls, mute support, and additional stereo scaling methods.

 

(4)、视频引擎（VideoEngine）模块 APIs

下表列的是目前在 VideoEngine中可用的sub APIs

sub-API	头文件	说明
ViEBase	vie_base.h	Basic functionality for creating a VideoEngine instance, channels and VoiceEngine interaction. NOTE: This API must always be created.
ViECapture	vie_capture.h	Adds support for capture device allocation as well as capture device capabilities.
ViECodec	vie_codec.h	Adds non-default codecs, codec settings and packet loss functionality.
ViEEncryption	vie_encryption.h	Adds external encryption/decryption support.
ViEErrors	vie_errors.h	Error codes for the VideoEngine
ViEExternalCodec	vie_external_codec.h	Adds support for using external codecs.
ViEFile	vie_file.h	Adds support for file recording, file playout, background images and snapshot.
ViEImageProcess	vie_image_process.h	Adds effect filters, deflickering, denoising and color enhancement.
ViENetwork	vie_network.h	Adds send and receive functionality, external transport, port and address filtering, Windows QoS support, packet timeout notification and changes to network settings.
ViERender	vie_render.h	Adds rendering functionality.
ViERTP_RTCP	vie_rtp_rtcp.h	Adds support for RTCP reports, SSRS handling RTP/RTCP statistics, NACK/FEC, keep-alive functionality and key frame request methods.

 

 

 

摘要
为了实现在两个联网的浏览器或者设备之间实现合适的实时协议来传输视频和语音，这篇文档在WebIDL中定义了一系列的ECMAscript的API。这个规格还在与IETF RTCWEB 小组开发的一个协议规以及Media Capture Task Force制定的访问本地媒体设备的API规范协同开发.(反正还在变就对了，google的chromium的代码实现在变，前一阵子微软好像也公开了一个他的webrct规范，好像有点故意与google的不兼容的那么个意思)

文档状态

这一节描述了这篇文档在发表时的状态。其它文档可能会取代这一篇.W3C的的技术报告和公开发表物的列表请看这里

这个文档还不全.可能会做大的修改，但是早期的实验是值得鼓励。（炮灰？）。所以这个文档不是用来实现的，API是以早期的工作为基础的。

从上一个版本的文档开始，融合Javascript Session Establishment Protocol(JSEP)到API中，以及将MediaStream和MediaStreamTrack对象融合到Media capture and Stream API中,并且在WebIDL做了大量的清理和整理工作。

注意最近有一篇提案是另外一个不同的实现，提交到了工作组，工作组还没有决定哪一个提案会实质影响现在工作的方向。（这老外明显的不待见微软嘛，另外一个不同的实现不就是微软提交的实现的，呵呵，连名字都不提）

这个文档作为 Web Real-Time Communications工作组的工作稿件公开。这篇文档着力成为W3C的推荐(标准？）.如果你对这篇文档有意见，请发邮件到[email protected]，任何反馈都是欢迎的。

作为工作稿件（working draft）发布，并不意味着被W3C成员认可。这个文档可能在任何时候被更新、替换或者被其它的文档废弃.如果不是作为正在修改中的文档引用是不恰当的。

这篇文档以以为原则，用小组工作方式产生的。

W3C 维护着一个与小组交付物相关的公开的专利列表；那个页面也包含公开专利的步骤。任何个人知道那些包括专利条款的公开信息必须遵守第6节的W3C的专利条款。
（以上这一段感觉翻译得怪怪的，所以将原文也附在下面）
W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

1.介绍
对应原文的这个链接开始的文字：

这一节是非规范性的(non-normative).

这个规范中覆盖了html视频会议的多个方面：

表示一段多媒体流，这个多媒体流是从本地设备（视频摄像机、麦克风、web摄像头）或者一段用户事先录好的文件。

使用诸如ICE、STUN和TURN 的NAT穿透技术连接到远端节点。

发送本地生成的流到远端以及接受远端节点发送过来的流。

直接发送任意的数据到对端。

这篇文档定义了为实现这些特性的一系列的API。这个规格与正在IETE RTCWEB 小组开发的协议规范以及Media Capture Task Force开发的访问本地设备的API在协同开发。

2. 一致性

这一节也是标记为非规范性的(non-normative).所有的创作指导、图表、示例以及规范都是非规范性的。

在这个规格中的关键字must, must not, required, should, should not, recommended, may, and optional 和 [RFC2119]中描述的一致.

这个规格定义的一致性标尺应用到一个单个产品:实现包含这些接口的用户代理。

用ECMAScrip来实作这个规格中定义的这些API必须和Web IDL 规格中定义的ECMAScript Bindings保持一致，因为这个规格使用了WEBIDL的规格和术语。

3. 术语

EventHandler interface 表示 在[HTML5]定义的回调事件处理函数.

queue a task 和 fires a simple event 在 [HTML5]中定义.

event handlers 的条款和event handler event 类型在 [HTML5]中定义.

No related posts.

4. Network Stream API

4.1 介绍

MediaStream 接口, 定义在 [GETUSERMEDIA] 规格中, 一般情况下表示一段音频和（或者）视频流数据. 一个 MediaStream 对象可以被扩展为表示 一段或者是向远端节点发送的数据流或者是从远端节点接受的数据量。(比方说，不仅仅是本地摄像头). 在 MediaStream 对象上开启这个功能的扩展将在本文档中描述。

一个MediaStream 定义在 [GETUSERMEDIA]的对象可以包含零个或者多个MediaStreamTrack 对象. 对于接受者来说一个发送到对端的MediaStreamTrack 对象会表现为一个且只有一个MediaStreamTrack . Peer是定义为一个支持这个规格的用户代理(User Agent可以理解为浏览器或者支持webrtc的设备）

通道(Channels) 是 MediaStream 规格中最小的单位. 为了传输的目的，比如作为RTP的负载类型，所有的通道（Channels）预期在一起编码.由一个编解码器共同编码的通道 一定 要在同一个MediaStreamTrack对象中 而且 编解码器 应该（should） 可以编码, 或者丢弃, 所有track中的通道(Channels).

The concepts of an input and output to 一个给定的的 MediaStream对象的输入输出的概念同样应用到了在网络上传输的 MediaStream 对象上. 一个 MediaStream 由RTCPeerConnection  (稍后描述)创建的对象会作为输入接收远端传过来的数据. 类似的, 一个  从本地源创建的MediaStream对象, 比如一个 [GETUSERMEDIA]描述的摄像头，如果它正在被RTCPeerConnection对象使用的话，就会有一个表示传输到远端节点的输出.

在 [GETUSERMEDIA]中描述的复制 MediaStream 对象的概念在这里也适用。 举例子来说，这个功能能够在这样的场景使用：这个一个视频会议中，在本地的监视器显示本地的视频和以及播放麦克风的声音，但是只传输声音到远端。(e.g. 对应用户所用的 “视频静音”的功能). 将不同的MediaStream对象上tracks 合并到一个新的MediaStream在某些特定的场景中也是非常有用的。

4.2 接口定义

注意

在本小节, 我们仅仅阐述使用时与  RTCPeerConnection相关的下列对象的各个方面。因为通用信息需要使用 MediaStream 和 MediaStreamTrack请参考在[GETUSERMEDIA] 文档中参考原始的对象定义。.

4.2.1 MediaStream

4.2.1.1 label

specified in 在MediaStream描述的label 属性返回一个唯一标识这个stream的label,因此stream可以在通过code>RTCPeerConnection API发送以后被识别。

当一个MediaStream被创建来标示一个从远端获取的stream时,  label 被从远端源中提供的信息初始化.

注意

MediaStream 对象的label属性对源stream是唯一的,但是并不表示最终不能复制它.比如,一个本地生成的stream可以通过本地的用户代理（User agent，一般就是指浏览器)  RTCPeerConnection发送给远端节点 ,然后用相同的方式发送回来到原始的用户代理（User agent，一般就是指浏览器), 那么原始的用户代理（User agent，一般就是指浏览器)就会有多个stream但是有相同的label (本地产生了一个又从远端接收了一个).

4.2.1.2 MediaStream的事件

一个新的 media track可能会和一个MediaStream关联。举个例子来说,如果一个远端节点在一个MediaStream 对象的track列表中新增一个 MediaStreamTrack对象，这个MediaStream对象正在通过一个 RTCPeerConnection发送, 这个过程是可以被本地的用户代理（user agent）观察到的. 如果这个因为例证而发生, 或者因为 add() [GETUSERMEDIA]方法被本地 a MediaStreamTrackList对象调用 或者tracks将被作为一个创建的stream被增加以外的原因被调用, 用户代理（user agent） must 必须运行一下的步骤:

1. 创建一个 MediaStreamTrack 对象 track 来表示媒体组件.
2. 如果track’s 变量的kind 属性等于“audio“, 将它加入 MediaStream 对象的audioTracks MediaStreamTrackList 对象中.
3. 如果track变量的 kind的属性等于”video“, 则将它加入 MediaStream 对象的 videoTracks MediaStreamTrackList 对象中。
4. 在MediaStreamTrackList对象上触发一个名字叫做 addtrack track事件，附带一个新创建的 track 作为参数.

当一个存在的media track 也被从一个 MediaStream断连时， 而且不是因为 the remove() [GETUSERMEDIA] 方法在本地的 a MediaStreamTrackList 对象上被调用了或者一个stream对象被销毁了, 用户代理（user agent）必须执行 must 如下的步骤:

1. 准备移除媒体组件的MediaStreamTrack对象track.
2. 从 MediaStreamTrackList对象移除track.
3. 在MediaStreamTrackList 对象上触发一个名字叫做 removetrack的事件，将 track 变量作为参数 .

在网络实例中，事件 onended是来自 RTCPeerConnection 对象的.

4.2.2 MediaStreamTrack

一个MediaStream 对象引用的 非本地媒体源MediaStreamTrack 对象 (一个RTP 源, 比如一个从RTCPeerConnection接收的MediaStream对象) 总是确定的.

一个归属于MediaStream的从远端传输过来的track，当远端节点已经永久停止发送数据时，必须 在track上触发一个the ended 事件 , 在 [GETUSERMEDIA]中有详细描述。

问题 1

ISSUE: 你怎么知道它什么时候停止？这像是一个SDP问题,不是一个媒体层的问题。

一个从 RTCPeerConnection接收的MediaStream对象中的track属性 , 一定 有它的readyState 属性 [GETUSERMEDIA] 设置为 静音 (1)直到接收打媒体数据。

另外,如果本地的用户代理（user agent）disable了对应的MediaStreamTrack对象，对应的远端的MediaStreamTrack 的属性readyState 将会设置为静音。当 addstream event 在RTCPeerConnection被触发时, 所有的MediaStream中产生的MediaStreamTrack将被设置为静音，直到从RTP 源中收到数据为止。

问题 2

ISSUE: 你如何知道何时他被disable了？ 这好像是个SDP的问题, 而不是媒体级的问题.

4.3 AudioMediaStreamTrack

注意

DTMF API有大量讨论列表而且可能会改动。

AudioMediaStreamTrack是 MediaStreamTrack的具体的类（specialization，基本上和面向对象的语言的抽象类具体类类似）它只传输音频而且扩展了发送和（或者）接收DTMF codes的能力。

AudioMediaStreamTrack的接口 : MediaStreamTrack {

    readonly attribute boolean canInsertDTMF;

    void insertDTMF (DOMString tones, optional long duration);

};

4.3.1 属性

canInsertDTMF of type boolean, readonly

The canInsertDTMF 属性 must 指明是否 AudioMediaStreamTrack 有能力发送DTMF.

4.3.2 Methods

insertDTMF

当一个 AudioMediaStreamTrack 对象的insertDTMF()的方法被调用时,用户代理（user agent） 必须 将一个发送 DTMF tones的任务放到队列中去。

tone 参数是被当做一系列的字符对待的。 字符 0 到 9, A 到 D, #, 和 * 产生了相关的DTMF tones。字符 a 到 d 和 A 到 D是相等的。这个字符,指明延迟2秒处理下一个tones中的字符。其它不认识的参数将被忽略。

duration参数指明播放在tones参数中的各个DTMF的时长，单位为ms（毫秒）。 duration必须 小于6000 大于 70。 duration缺省值是100. tones之间的间隙 必须至少为 50 ms 但是在此基础上越短越好.

问题 3

ISSUE: 非法的值是如何处理的?

如果当insertDTMF被调用时，这个对象上已经现有的产生DTMF的任务在运行, 现有的任务将被取消。那就因为着如果调用insertDTMF 并且传一个空的tones参数可以取消在正在发送的任何tones。

注意

编者注: 我们需要在这个对象上增加一个回调函数，这个回调函数将在tones发送之后被调用。这个对应用来说是非常需要的，因为他们要知道什么时候可以发送新的tones而不会取消现在正在发送的tones.

注意

编者注:看来我们需要一个回调函数来通知我们收到了一个tones。草案是将列表在扬声器上作为音频播放，但是我不知道是否有用。

Parameter	Type	Nullable	Optional	Description
tones	DOMString	✘	✘
duration	long	✘	✔

 

5. Peer-to-peer connections

一个 RTCPeerConnection 对象允许两个用户之间直接通讯，,浏览器到浏览器。通信通过一个信号通道来协调，这个信号通道没有指定方式，但是一般情况下是页面的script 通过服务器比如XMLHttpRequest来交互的。（译者注：iwebrtc现有版本的实现没有通过XMLHttpRequest，而是通过NPAPI的插件实现了一个socket连接到服务器端，同时，这个连接还有可能会用来中转语音和视频的数据。iwebrtc的详细描述可以看这里：

调用new RTCPeerConnection(configuration ) 会创建一个新的 RTCPeerConnection 对象.

configuration变量 包含了需要访问的 [STUN] 和 [TURN] 服务器. 对于 TURN server 和STUN server可以由多台服务器作为选择.

一个RTCPeerConnection 对象还关联了 ICE agent对象, RTCPeerConnection readiness state, 和ICE state. 当对象被创建时这些将会被初始化。

当RTCPeerConnection() 构造函数被调用时, 用户代理（user agent一般指浏览器） 必须 运行以下的步骤。这个算法有一个同步的段 (它将被作为事件循环的一部分运行).

1. 创建一个ICE Agent而且让 connection的RTCPeerConnection ICE Agent 作为ICE Agent将configuration数组中的STUN and TURN 服务器传给它。在IceTransports 约束没有被设置为”none”之前， [ICE] 将会尽快处理搜集。在这个时间点上 ICE Agent 不知道它需要多少个ICE components(因此 candidates的数量也需要搜集)但是它可以做一个合理的假设而且随着RTCPeerConnection对象获取了更多信息的时它可以随时调节组件的数量。
2. 设置connection的 RTCPeerConnection readiness 状态为 to new .
3. 设置 connection的 RTCPeerConnection ice 状态 为 new .
4. 设置connection的 localStreams 属性为为空的只读MediaStream 数组。
5. 设置 connection’s remoteStreams属性为为空的只读 MediaStream 数组。
6. 返回 connection变量, 继续异步执行这些步骤。
7. 等待一个稳当的状态。.同步段落包含算法的剩下这些步骤。

在RTCPeerConnection对象的生命周期中,如下的过程将被继续:

1. 如果 iceState 变量值是”new”且IceTransports 约束没有被设置为“none”,  必须 在队列中增加一个任务来开始采集ICE 地址且将iceState 变量值设为“gathering”.
2. 如果ICE Agent已经为 MediaStreamTrack找到一个或者多个candidate pairs 而且形成一条合法的链接, ICE state 将被修改为”connected”.
3. 当ICE Agent结束检查所有的candidate pairs后, 如果为MediaStreamTrack至少找到一条连接 ,  iceState变量将被修改为”completed”，如果任何一个MediaStreamTrack都没有找到一条连接 , iceState 将被修改为“failed”.

问题 4

ISSUE: 注意这个意味着如果 我可以通过ICE协商成功音频，但是视频协商失败， 那么 iceState == “completed”. 这个真的是想要的结果吗?

4. 如果 iceState 等于“connected”或者“completed”而且本地和远端的 session 描述符被设置, RTCPeerConnection的状态将被置为“active”.
5. 如果 iceState 等于“failed”, 队列里将插入一个任务来调用call方法。

问题 5

ISSUE:: CJ – 这个我认为是错的。

用户代理（User agents）协商 编解码器的分辨率, 比特率,以及其它媒体参数.我们 推荐用户代理（User agents)用最大的分辨率为视频流进行协商。对于那些将要渲染视频流 (通过一个 video 标签), 我们推荐用户代理（user agents）以将要渲染的分辨率进行协商。

NOTE

用本地的分辨率开始意味着如果Web应用开始传输数据时，用本地分辨率通知对端节点，而对端节点用相应的分辨率准备video标签, 那么就没有必要重像如下的步骤新协商了。

“components”这个词在这个上下文里指一个 RTP media 流而且与 [ICE] 如何使用术语”component”毫无关系。

当一个用户代理（user agent）已经到达了一个 MediaStream 已经被创建来表示一个进入的 components, 用户代理（User agent）必须 执行如下的步骤:

1. 让connection做为 RTCPeerConnection 来接收媒体.
2. 创建一个MediaStream来表示这个媒体.
3. 对于media stream中的每个 component执行如下的步骤。
   1. 创建一个MediaStreamTrack 对象 track变量来表示component. [[编辑的话:这里我们可以直接参考3.2.1.2吗？]]
   2. 如果 track的 kind属性等于“audio“,将它加到MediaStream 对象的audioTracks MediaStreamTrackList 对象属性中。
   3. 如果track的 kind属性等于“video“,将它加到MediaStream 对象的 videoTracks MediaStreamTrackList 对象属性中。

注意

新收到的MediaStreams的创建（应该是指创建函数或者创建过程）会是被SDP 协商或者是在一个指定的flow上接收了媒体来触发的。

注意

在接收端MediaStreamTrackList对象的内部的顺序应该反映发送端的顺序。一个强制这个顺序的方法是指定在SDP中的顺序。

4. 将任务加入队列中来执行下列的子步骤：
   1. 如果connection的 RTCPeerConnection readiness 状态是CLOSED (3), 那么就放弃这些步骤.
   2. 将新创建的MediaStream 对象加入到connection的 remoteStreams 数组尾部。
   3. 触发一个stream的名为 addstream的事件， 并将新创建的 connection o对象上的MediaStream对象作为参数传给它。

当一个用户代理（User agent）已经为一个从属于一个已经表示了一个已经存在的MediaStream 对象的媒体流的component协商媒体时, 用户代理（user agent ）必须 关联这个 component 到这个MediaStream 对象。

当一个RTCPeerConnection对象发现一个从远端节点过来的stream被移除时 , 用户代理（user agent） 必须 执行如下的步骤:

1. 将作为RTCPeerConnection类的connection和这个stream关联的变量移除.
2. 如果存在，则将作为MediaStream类的 stream 表示这个媒体流的变量移除。如果没有，则放弃这些步骤。
3. 根据定义 变量stream 现在 完结.

注意

因此队列中增加了一个任务来更新 stream 以及触发一个事件。

4. 在队列中增加一个任务来执行下列的子步骤:
   1. 如果变量connection的RTCPeerConnection readiness 状态 等于closed (3), 则忽略这些步骤。
   2. 从connection变量的remoteStreams 数组中移除 stream.
   3. 在connection 对象的stream属性上触发一个stream事件 名字叫做 removestream.

这一节中的所列出的任务的任务源是网络任务源。

如果浏览器中一些修改引起 RTCPeerConnection对象需要初始化一个新的session 描述符协商，, 一个negotiationneeded 将在 RTCPeerConnection 对象上触发。

具体来说, 如果一个RTCPeerConnection 对象正在消费（consuming） 一个 MediaStream对象，此时一个track被其中一个 stream的 MediaStreamTrackList 对象中, 比如 add() 方法被调用了, RTCPeerConnection 对象的 must 触发 “negotiationneeded” 事件。 同理，移除一个媒体components 也必须触发 “negotiationneeded”事件。

为了防止网络嗅造成的一个第四方通过截获的信息创建一个连接到另外的节点来愚弄客户，configuration 信息 应该始终用加密连接传输。

5.1 RTCPeerConnection

RTCPeerConnection的一般操作在这个文档中描述： [RTCWEB-JSEP].

5.1.1 RTCSdpType

RTCSdpType 枚举类型描述 RTCSessionDescription 实例的类型（Type）。

enum RTCSdpType {

    "offer",

    "pranswer",

    "answer"

};

枚举类型描述
offer	一个 RTCSdpType 类型的”offer”取值指定一个描述符应该被当做一个 [SDP] offer.
pranswer	一个 RTCSdpType 类型的”pranswer”取值指定一个描述符应该被当做 [SDP] answer,但不是最终的answer（final answer）。一个描述符（description）用作一个SDP “pranswer” 可能被用作SDP offer的应答, 或者更新上一个已经发送了的 SDP “pranswer”。
answer	一个RTCSdpType类型的”answer”取值指定一个描述符（description）应该被当做 [SDP] final answer, 而且这个offer-answer交互过程应该被认为完结。一个描述符（description）被用作一个SDP answer 应该用来作为一个SDP offer的应答, 或者更新上一个已经发送了的 SDP “pranswer”

5.1.2 RTCSessionDescription 类型(class)

RTCSessionDescription() 构造函数有一个可选的“字典”类型的参数, descriptionInitDict, 它的内容是用来初始化新的RTCSessionDescription 对象。如果字典的key不存在于 descriptionInitDict中,那么对应的属性就会被初始化为 null。如果没有给构造函数传递字典参数,那么所有的属性都会被初始化为空。这个类为包含的数据未来扩展留了余地而且不需要做进一步的处理。

[Constructor (optional RTCSessionDescriptionInit descriptionInitDict)]

interface RTCSessionDescription {

             attribute RTCSdpType? type;

             attribute DOMString?  sdp;

    stringifier DOMString ();

};

dictionary RTCSessionDescriptionInit {

    RTCSdpTypetype;

    DOMString  sdp;

};

5.1.2.1 属性

sdp of type DOMString, nullable

The string representation of the SDP [SDP]

type of type RTCSdpType, nullable

What type of SDP this RTCSessionDescription represents.

5.1.2.2 方法

DOMString

实现了RTCSessionDescription 接口的对象必须可以通过执行如下步骤转换为string（stringify ）。让类型（ type）和 sdp元素的属性列表,属性列表包含在字符化的表示结果中.

1. 让结果包含 U+0028 左圆括号和 U+007B 左花括号.

2. 对于每个添加到结果中属性列表中的属性，属性的名字加上： U+003A 冒号和U+0022 引号,属性的值加上： U+0022 引号和 U+002C 逗号。如果是属性列表中最后一个属性,则去掉最后的 U+002C 逗号。

3. 在结果中添加 U+007D 右花括号 U+0029 和右圆括号然后返回结果。

没有参数.

返回类型:字符串( stringifier注：此处应该是json类型的字符串) 

5.1.2.3 字典 RTCSessionDescriptionInit 成员

sdp ：类型是DOMString

type：类型是 RTCSdpType

DOMString sdp

5.1.3 RTCSessionDescriptionCallback

回调方法 RTCSessionDescriptionCallback = void (RTCSessionDescription sdp);

5.1.3.1 回调方法 RTCSessionDescriptionCallback参数

sdp：类型是 RTCSessionDescription

包含 SDP的对象 [SDP].

5.1.4 RTCVoidCallback

回调方法 RTCVoidCallback = void ();

5.1.5 RTCPeerConnectionErrorCallback

回调方法RTCPeerConnectionErrorCallback = void (DOMString errorInformation);

5.1.5.1 Callback RTCPeerConnectionErrorCallback 参数

类型 DOMString的错误信息

什么出错的信息.

问题 6

ISSUE:这应该是个枚举类型吗?

5.1.6 RTCPeerState Enum

enum RTCPeerState {

    "new",

    "opening",

    "active",

    "closing",

    "closed"

};

枚举类型描述
new	对象刚刚创建，而且还没有任何网络消息发送或者接收。
opening	用户代理（ user agent）正在尝试通过ICE agent 建立连接并等待本地和远端的SDP被设置。 问题 7 ISSUE: 我们需要在 “opening” 和”active”之间加上更多的状态吗?
active	ICE Agent已经发现了一个连接而且本地和远端的SDP已经被设置好了。可以开始媒体流程了。
closing	RTCPeerConnection对象结束了所有的媒体流而且正在关闭连接的过程中。
closed	连接已经关闭了。

5.1.7 RTCIceState 枚举

注意

这些状态还正在讨论过程中，有可能被修改。

enum RTCIceState {

    "new",

    "gathering",

    "waiting",

    "checking",

    "connected",

    "completed",

    "failed",

    "closed"

};

枚举类型描述
new	RTCPeerConnection 对象刚刚被创建,没有任何网络消息被发送和接收。
gathering	ICE Agent正在尝试收集地址。
waiting	ICE Agent没有在收集任何地址，它在等待另外一端的candidates完成之后它才会开始检查。
checking	ICE Agent正在检查candidate对，但是还没有找到一个连接。不光是检查，它有可能还在搜集地址。
connected	ICE Agent已经找到一条连接，但是还在检查其它的candidate对，看能否找到一条更好的连接。它也可能还在收集地址。
completed	ICE Agent 已经完成搜集工作而且已经找到一条连接（对比上一个状态可以知道这是最好的一条连接）
failed	ICE Agent 正在完成检查所有的 candidate 对，但是没有找到一条连接。
closed	ICE Agent已经关闭了而且不再响应STUN的请求。

5.1.8 RTCIceCandidate Type

    RTCIceCandidate()  构造函数构造函数接收一个可选的字典参数， candidateInitDict, whose它的内容用来初始化新的RTCIceCandidate 对象。如果一个字典中的key在candidateInitDict不存在,对应的属性将被初始化为空。如果没有将字典参数传给构造函数,所有的属性将初始化为空。这个类是可以为未来的携带的数据做扩充扩展而不需要执行任何实质性的处理。

[Constructor (optional RTCIceCandidateInit candidateInitDict)]

interface RTCIceCandidate {

             attribute DOMString?      candidate;

             attribute DOMString?      sdpMid;

             attribute unsigned short? sdpMLineIndex;

    stringifier DOMString ();

};

dictionary RTCIceCandidateInit {

    DOMString      candidate;

    DOMString      sdpMid;

    unsigned short sdpMLineIndex;

};

5.1.8.1 属性

candidate ：类型DOMString, 可能为空

这个属性携带 candidate-attribute 定义在 [ICE]的15.1 节.

sdpMLineIndex ：类型unsigned short, 可能为空

这个指定index (从0开始的) ，是在SDP Mline对应的数组下标。

sdpMid ：类型DOMString, 可以为空

如果存在这个属性,它包含了“media stream identification”的标识符，这个在 [RFC 3388]中为和这个candidate关联的 m-line 定义的。

5.1.8.2 方法

DOMString

    实现了 RTCIceCandidate接口的对象必须实现字符串化（ stringify）的方法，这个方法的算法在 RTCSessionDescription stringifier algorithm 中定义，包括candidate, sdpMid, sdpMLineIndex 作为元素的属性列表。

没有参数

返回类型: 字符串（stringifier）

5.1.8.3 字典RTCIceCandidateInit 的成员

candidate：类型是DOMString

DOMString sdpMid

sdpMLineIndex ：类型是unsigned short

sdpMid ：类型是DOMString

unsigned short sdpMLineIndex

5.1.9 RTCIceServer 类型

dictionary RTCIceServer {

    DOMString          url;

    nullable DOMString credential;

};

5.1.9.1 字典RTCIceServer 成员

credential：可以为空的DOMString

如果内部数字的url元素是一个 TURN URI, 那么这个credential（凭据）是用在 TURN server上的。

url ：类型是 DOMString

一个stun或者turn的 URI，定义在这两个文档中：[STUN-URI] 和 [TURN-URI]。

    在多层NAT（译者注：看到多层NAT这个词，我马上想到一个例子：国内的宽带运营商，比如长城宽带、中信宽带等一些小的宽带运营商（无贬义），本身分配的ip地址就不多，通过pppoe拨上去以后，运营商本身分配给用户的的就是内网地址，比如10或者172或者192开头的地址，在运营商这一层就做了一次NAT。如果用户自己再接了一个无线路由器，那就是第二层NAT，这就是多层NAT）的网络拓扑图中，除了TURN Server之外，需要在每两层NAT之间设置一个STUN Server，用来减少网络延时。（说实话没理解设置多个STUN Server对于减少网络延时有什么用）

一个 RTCIceServer对象数组的例子是:

[ { url:"stun:stun.example.net"] } , { url:"turn:[email protected]", credential:"myPassword"} ]

5.1.10 RTCConfiguration 类型

dictionary RTCConfiguration {

    RTCIceServer[] iceServers;

};

5.1.10.1 字典 RTCConfiguration 的成员

iceServers：RTCIceServer类型的数组

JS提供的包含STUN和TURN 服务器的数组用在ICE协议中。

5.1.11 RTCPeerConnection 接口

typedef MediaStream[] MediaStreamArray;

[Constructor (RTCConfiguration configuration, optional MediaConstraints

        constraints)]

interface RTCPeerConnection : EventTarget  {

    void        createOffer (RTCSessionDescriptionCallback successCallback, optional RTCPeerConnectionErrorCallback failureCallback, optional MediaConstraints constraints);

    void        createAnswer (RTCSessionDescription offer, RTCSessionDescriptionCallback successCallback, optional RTCPeerConnectionErrorCallback? failureCallback = null, optional optional MediaConstraints constraints = null, optional optional boolean createProvisionalAnswer = false);

    void        setLocalDescription (RTCSessionDescription description, optional RTCVoidCallback successCallback, optional RTCPeerConnectionErrorCallback failureCallback);

    readonly attribute RTCSessionDescriptionlocalDescription;

    void        setRemoteDescription (RTCSessionDescription description, optional RTCVoidCallback successCallback, optional RTCPeerConnectionErrorCallback failureCallback);

    readonly attribute RTCSessionDescriptionremoteDescription;

    readonly attribute RTCPeerState          readyState;

    void        updateIce (optional RTCConfiguration? configuration = null, optional optional MediaConstraints? constraints = null, optional boolean restart = false);

    void        addIceCandidate (RTCIceCandidate candidate);

    readonly attribute RTCIceState           iceState;

    readonly attribute MediaStreamArray      localStreams;

    readonly attribute MediaStreamArray      remoteStreams;

    DataChannelcreateDataChannel ([TreatNullAs=EmptyString] DOMString label, optional DataChannelInit dataChannelDict);

             attribute EventHandler          ondatachannel;

    void        addStream (MediaStream stream, optional MediaConstraints constraints);

    void        removeStream (MediaStream stream);

    void        close ();

             attribute EventHandler          onnegotationneeded;

             attribute EventHandler          onicecandidate;

             attribute EventHandler          onopen;

             attribute EventHandler          onstatechange;

             attribute EventHandler          onaddstream;

             attribute EventHandler          onremovestream;

             attribute EventHandler          onicechange;

};

属性：

iceState 类型是 RTCIceState, 只读

iceState  属性  必须 返回RTCPeerConnection的 ICE Agent的 ICE state.

localDescription的类型是 RTCSessionDescription, 只读

localDescription 属性必须返回类型为RTCSessionDescription最近传给 setLocalDescription()的参数 , 加上任何从那时起ICE Agent生成的本机的candidates。

如果 local description没有设置过则返回空。

localStreams 类型是 MediaStreamArray, 只读

返回一个包含本地流媒体活跃(live)的数组(那些通过addStream()加入的流媒体 ).

onaddstream 类型是 EventHandler

这是一个事件处理器，事件处理器的类型是addstream,当远端节点增加一个媒体流时实现了RTCPeerConnection 接口的所有对象必须 实现触发这个事件。

ondatachannel 类型是 EventHandler

这个事件处理器,类型是 datachannel ,   所有实现了 RTCPeerConnection 接口的必须支持.

onicecandidate 类型是 EventHandler

这个事件处理器,事件处理器的类型是 onicecandidate , 所有实现了 RTCPeerConnection接口的对象必须支持。当一个新的ICE candidate加入之前的offer或者answer中将会触发这个事件。

onicechange类型是 EventHandler

这个事件处理器,事件处理器的类型是  icechange, 所有实现了 RTCPeerConnection接口的对象必须支持. 当 iceState 变化时这个事件将触发。

onnegotationneeded 类型是 EventHandler

这个事件处理器,事件处理器的类型是  negotiationneeded , 所有实现了 RTCPeerConnection接口的对象必须支持。

onopen of 类型是 EventHandler

这个事件处理器,事件处理器的类型是 open , 所有实现了 RTCPeerConnection接口的对象必须支持。

onremovestream of type EventHandler

这个事件处理器,事件处理器的类型是 removestream, 所有实现了 RTCPeerConnection接口的对象必须支持。当一个媒体流被移除时，这个事件将被触发。

onstatechange of type EventHandler

这个事件处理器,事件处理器的类型是 statechange , 所有实现了 RTCPeerConnection接口的对象必须支持。当 readyState属性被修改时，这个事件触发。

readyState类型是 RTCPeerState, 只读

readyState 属性 必须返回 RTCPeerConnection 对象的 RTCPeerConnection readiness 状态.

remoteDescription 类型是 RTCSessionDescription, 只读

remoteDescription 属性 必须 返回最近传给setRemoteDescription()方法的RTCSessionDescription对象, 加上从那时起任何通过 addIceCandidate()添加远端的 candidates.

如果没有设置过远端描述符，将会返回空。

remoteStreams 类型是 MediaStreamArray, 只读

返回一个包含远端流活动(live)数组(那些远端添加的媒体流).

当addstream 和 removestream 事件被触发时数组将会更新.

方法

addIceCandidate

    addIceCandidate() 方法给ICE Agent提供了一个远端的 candidate, 这个candidate将会被加到远端的描述符中去。连接检查将在”IceTransports”约束没有被设置为“none”之前发送到新的candidates 去。这个方法调用将造成ICE Agent的状态改变,而且如果因此创建了另外一条连接有，媒体状态也会改变。

如果candidate格式不正确，那么TBD 异常（exception）会抛出。

参数	类型	是否为空	是否可选	描述
candidate	RTCIceCandidate	✘	✘

Return type: void

addStream

给RTCPeerConnection添加一个流。

当addStream() 方法被调用时,用户代理（user agent）必须执行如下的步骤:

1. 如果RTCPeerConnection 对象的 RTCPeerConnection readiness 状态是closed (3), 则抛出 INVALID_STATE_ERR异常。

2. 如果这个流(stream )已经在 RTCPeerConnection 对象的 localStreams 对象中存在, 则放弃执行下面的步骤。

3. 将流(stream)加入 RTCPeerConnection对象的 localStreams 对象的尾部.

4. 分析应用程序提供的约束（ constraints),如果可能将它们应用到MediaStream。注意–这里需要处理抛出的异常。

5. 触发 negotiationneeded 事件.

问题 9

ISSUE:如果 RTCPeerConnection是一个新的对象，还要触发事件吗?

参数	类型	是否为空	是否可选	描述
流(stream)	MediaStream	✘	✘
约束(constraints)	MediaConstraints	✘	✔

返回值类型: void

close

当 close()方法被调用时,用户代理（ user agent）必须执行如下的步骤:

1. 如果RTCPeerConnection 对象的 RTCPeerConnection readiness 状态是 closed (3),抛出一个 INVALID_STATE_ERR 异常。

2. 销毁 RTCPeerConnection ICE Agent, 快速结束任何活跃的 ICE 处理过程和任何活跃的流（ streaming), 且释放相关的资源 (比如. TURN 资源).

3. 设置对象的 RTCPeerConnection readiness state to closed (3).

没有参数

返回值类型: void

createAnswer

     createAnswer方法根据传入的configuration 参数为会话（session)产生一个 [SDP] answer 消息，此消息与offer的参数保持兼容。和createOffer类似,返回的 blob包含了管理了本地 MediaStreams 的RTCPeerConnection对象,协商过的编解码器/RTP/RTCP选项,和任何ICE Agent搜集的candidates 。可能会传入约束参数来提供额外的控制信息来生成应答（answer）.

作为一个应答（answer）,生成的SDP会包含指定的配置(configuration）,和offer消息一起, 指定媒体层（media plane）应该如果建立。SDP的生成必须遵循如下的适当的过程来生成一个应答(answer)消息或者 临时应答(provisional answer)。

如果setLocalDescription方法在sucessCallback函数中被调用的话，不需要生成错误消息 ，createAnswer 方法生成的会话描述符（Session descriptions）必须立即作为可用状态提供给setLocalDescription方法。类似于createOffer方法,返回的描述符（description）应该反映当前系统的状态。会话描述符 必须 remain 通过setLocalDescription 方法保持可用且不产生任何错误，直到successCallback function结束。获取ICE 用户名和密码需要调用这个方法。只有当 createProvisionalOffer 标志为真时会创建在 [RTCWEB-JSEP]中描述的临时的offer（ Provisional offers）。

当系统不能为指定的offer消息生成应答消息（answer)时，failureCallback 函数将被触发。

如果约束参数格式不正确，TBD异常 将被抛出。

参数	类型	是否为空	可选	描述
offer	RTCSessionDescription	✘	✘
successCallback	RTCSessionDescriptionCallback	✘	✘
null	RTCPeerConnectionErrorCallback? failureCallback =	✘	✔
null	optional MediaConstraints constraints =	✘	✔
false	optional boolean createProvisionalAnswer =	✘	✔

Return type: void

createDataChannel

    用指定的标签（label)创建一个新的 DataChannel 对象。  DataChannelInit 字典参数可以用来配置底层的传输通道，比如数据的可靠性。如果通道创建设置成功的话，一个对应的 DataChannel对象将在对端的节点部署。

当调用 createDataChannel() 方法时, 用户代理（user agent）必须执行如下的步骤：

1. 如果RTCPeerConnection 对象的 RTCPeerConnection readiness 状态是closed (3), 抛出一个 INVALID_STATE_ERR 异常。

2. 让channel 成为一个新创建的 DataChannel 对象。

3. 用第一个参数来初始化channel的label 属性。

4. 将channel 的reliable属性设置为true。

5. 如果第二个参数存在而且它包含一个 reliable 的字典成员, 那么就将channel的 reliable 属性设置为对应的字典成员的值。

6. 返回channel然后在后台继续执行余下的步骤。

7. 创建通道 channel的关联的底层数据传输通道（underlying data transport）。

参数	类型	是否为空	是否可选	描述
label	DOMString	✘	✘
dataChannelDict	DataChannelInit	✘	✔

返回类型: DataChannel

createOffer

     createOffer 方法生成一个SDP数据块,包含了 RFC 3264 协议中的offer消息以及会话(session)的配置，包括关联到这个 RTCPeerConnection对象的本地媒体流(local MediaStreams) 描述符(description), 这个实现支持的编解码器/RTP/RTCP选项，以及ICE Agent搜集的candidates。约束参数可能为offer消息的生成提供了附加的控制信息。

作为一个offer消息，生成的SDP将会包含会话支持的完整的功能。(和answer消息不同,它只包含指定的协商过的子集）;对于每行SDP消息，SDP的生成offer消息的过程必须正确。在会话建立之后createOffer方法被调用的事件中，, createOffer会生成一个offer消息与当前的会话(session)兼容, 自从上次完整的offer-answser消息交换过程完成后作用在这个会话上变化将会合并进来，比如增加或者减少流(stream)。如果没有任何变化，offer消息将会包含当前本地的描述符的功能（capabilities ）以及任何附加的可用在更新的offer消息协商的功能。

createOffer 生成的会话(Session)描述符must必须 be立即置为可用提供给setLocalDescription使用，并保证在setLocalDiscription方法被 successCallback 函数调用时不出错。如果系统资源有限(比如：有限的解码器数量）, createOffer需要返回一个能够反映当前系统状态的 offer消息, 因此当setLocalDescription获取那些系统资源能够成功。直到successCallback函数结束时会话（session）描述符must必须 remain为setLocalDescription保持可用不出错。调用这个方法需要获取 ICE的用户名和密码。

failureCallback 方法将在系统不能在给定的RTCPeerConnection状态下生成正确的offer消息时被调用。

如果约束参数的格式不正确，一个TBD 异常将被抛出。

To Do: Discuss privacy aspects of this from a finger printing point of view – it’s probably around as bad as access to a canvas （这个To Do暂时保留不翻译，因为感觉不太重要，第一眼也看得太明白）

参数	类型	是否为空	是否可选	描述
successCallback	RTCSessionDescriptionCallback	✘	✘
failureCallback	RTCPeerConnectionErrorCallback	✘	✔
constraints	MediaConstraints	✘	✔

返回值类型: void

removeStream

    在RTCPeerConnection 对象中从LocalStream 数组移除指定流(stream )并触发negotiationneeded事件。

当另外一个节点（对端）用这样的方式停止发送流(stream),一个removestream 事件将在 RTCPeerConnection 对象上触发。

当 removeStream() method 方法被触发时，用户代理（user agent）必须执行如下的步骤:

1. 如果RTCPeerConnection 对象的 RTCPeerConnection readiness 的状态是closed (3), 抛出一个 INVALID_STATE_ERR 异常。

2. 如果流(stream) 不存在于 RTCPeerConnection 对象的 localStreams 对象中, 那么放弃下面的步骤。. TODO:需要在这里抛出异常吗?

3. 从RTCPeerConnection 对象的 localStreams 对象中移除此流（stream)。

4. 触发negotiationneeded事件。

参数	类型	是否为空	是否可选	描述
流	MediaStream	✘	✘

返回值类型: void

setLocalDescription

    setLocalDescription() method 方法命令 RTCPeerConnection将传递的 RTCSessionDescription 参数作为本地描述符。

这个API修改本地媒体状态(local media state),为了能成功处理这样的场景：应用程序想要从一种媒体格式转换到另外一种不兼容的格式。 RTCPeerConnection 必须能够同时支持使用老的和新的本地描述符(比如支持在两者中存在的编解码器)一直到收到一个最终的应答消息(final answer),此时RTCPeerConnection能够完全采纳新的本地描述符（local description）,如果对端不同意修改则回滚（ roll back )到老的描述符。

问题 8

ISSUE: 如何指定回滚?

To Do: 指定SDP的那一部分在createOffer和setLocalDescription之间可以修改。

修改到媒体传输状态会引起最终的应答(final answer)将会成功应用。 localDescription 必须 return 返回之前的描述符直到新的描述符成功应用。

如果 RTCSessionDescription 是合法的但是没能应用到媒体层( cannot be applied at the media layer),那么failureCallback 将被触发，比如没有足够的资源应用SDP。当失败发生时而新的描述符部分已经应用，用户代理( user agent) 必须 根据需要回滚 。

如果SDP的内容非法，一个 TBD 异常将被抛出。

参数	类型	是否为空	可选	描述
description	RTCSessionDescription	✘	✘
successCallback	RTCVoidCallback	✘	✔
failureCallback	RTCPeerConnectionErrorCallback	✘	✔

返回值类型: void

setRemoteDescription

    setRemoteDescription() 方法指令RTCPeerConnection对象应用传递的 RTCSessionDescription 作为远端offer或者answer消息。这个API修改本地媒体状态(local media state)

修改到媒体传输(media transmission)将会造成最终的应答( final answer)成功设置。remoteDescription must必须 返回之前的描述符直到新的描述符被成功应用。

如果 RTCSessionDescription 是合法的但是没能应用到媒体层( cannot be applied at the media layer),那么failureCallback 将被触发，比如没有足够的资源应用SDP。当失败发生时而新的描述符部分已经应用，用户代理( user agent) 必须 根据需要回滚 。

如果SDP的内容非法，一个 TBD 异常将被抛出。

参数	类型	是否为空	可选	描述
description	RTCSessionDescription	✘	✘
successCallback	RTCVoidCallback	✘	✔
failureCallback	RTCPeerConnectionErrorCallback	✘	✔

返回值类型: void

updateIce

    updateIce方法重启或者更新ICE Agent搜集本地candidate和pinging远端candidate的流程。如果有一个固定的名为”IceTransports”约束，它将会控制ICE 引擎如何工作。这个可以对被调用者用来限制使用TURN candidates来防止泄露本地信息优先于接受调用。

这个调用可能导致 ICE Agent状态变化, 如果它导致连接被建立的话，就可能导致需要修改媒体状态。

如果restart这个参数被设置为true，ICE状态机( state machine)将丢弃它搜集的所有candidates,重新为主机candidate分配新的端口，如果没有之前的ICE 会话(session)然后重启ICE and restarts ICE。当有些事情已经发生严重错误时，应用程序可以用这个方法来重置所有的ICE协商。

如果参数格式不正确，一个TBD异常将被抛出。

参数	类型	是否可以为空	是否可选	描述
null	RTCConfiguration? configuration =	✘	✔
null	optional MediaConstraints? constraints =	✘	✔
false	boolean restart =	✘	✔

返回值类型: void