logo资料库

WebRTC1.0:浏览器间实时通讯.pdf

第1页 / 共108页
第2页 / 共108页
第3页 / 共108页
第4页 / 共108页
第5页 / 共108页
第6页 / 共108页
第7页 / 共108页
第8页 / 共108页
资料共108页,剩余部分请下载后查看
封面
1.介绍
2.一致性
3.术语
4. 对等连接
4.1 介绍
4.2 配置
4.2.1 RTCConfiguration字典
4.2.2 RTCIceCredentialType枚举值
4.2.3 RTCOAuthCredential字典
4.2.4 RTCIceServer字典
4.2.5 RTCIceTransportPolicy枚举值
4.2.6 RTCBundlePolicy枚举值
4.2.7 RTCRtcpMuxPolicy枚举值
4.2.8 邀请/应答选项
4.3 状态定义
4.3.1 RTCSignalingState枚举值
4.3.2 RTCIceGatheringState枚举值
4.3.3 RTCPeerConnectionState枚举值
4.3.4 RTCIceConnectionState枚举值
4.4 RTCPeerConnection接口
4.4.1 操作
4.4.1.1 构造函数
4.4.1.2 操作入队
4.4.1.3 更新连接状态
4.4.1.4 更新ICE收集状态
4.4.1.5 更新ICE连接状态
4.4.1.6 设置RTCSessionDescription
4.4.1.7 设置配置
4.4.2 接口定义
4.4.3 旧版接口扩展
方法扩展
旧版配置扩展
4.4.4 垃圾回收
4.5 错误处理
4.5.1 通用原则
4.6 会话描述模型
4.6.1 RTCSdpType
4.6.2 RTCSessionDescription类
4.7 会话协商模型
4.7.1 设置是否需要协商标记位
4.7.2 清除是否需要协商标记位
4.7.3 更新是否需要协商标记位
4.8 连接建立接口
4.8.1 RTCIceCandidate接口
4.8.1.1 candidate-attribute语法
4.8.1.2 RTCIceProtocal枚举
4.8.1.3 RTCIceTcpCandidateType枚举
4.8.1.4 RTCIceCandidateType枚举
4.8.2 RTCPeerConnectionIceEvent
4.8.3 RTCPeerConnectionIceErrorEvent
4.9 优先级和服务质量(QoS)模型
4.9.1 RTCPriorityType枚举
4.10 证书管理
4.10.1 RTCCertificateExpiration字典
4.10.2 RTCCertificate接口
5. RTP媒体API
5.1 RTCPeerConnection接口扩展
5.1.1 处理远程媒体流轨
5.2 RTCRtpSender接口
5.2.1 RTCRtpParameters字典
5.2.2 RTCRtpSendParameters字典
5.2.3 RTCRtpReceiveParameters字典
5.2.4 RTCRtpCodingParameters字典
5.2.5 RTCRtpDecodingParameters字典
5.2.6 RTCRtpEncodingParameters字典
5.2.7 RTCDtxStatus枚举
5.2.8 RTCDegradationPreference枚举
5.2.9 RTCRtcpParameters字典
5.2.10 RTCRtpHeaderExtensionParameters字典
5.2.11 RTCRtpCodecParameters字典
5.2.12 RTCRtpCapabilities字典
5.2.13 RTCRtpCodecCapability字典
5.2.14 RTCRtpHeaderExtensionCapability字典
5.3 RTCRtpReceiver接口
5.4 RTCRtpTransceiver接口
5.4.1 联播功能
5.4.1.1 编码参数样例
5.4.2 "暂停"功能
5.5 RTCDtlsTransport接口
5.5.1 RTCDtlsFingerprint字典
5.6 RTCIceTransport接口
5.6.1 RTCIceParameters字典
5.6.2 RTCIceCandidatePair字典
5.6.3 RTCIceGathererState枚举
5.6.4 RTCIceTransportState枚举
5.6.5 RTCIceRole枚举
5.6.6 RTCIceComponent枚举
5.7 RTCTrackEvent
6. 点对点数据API
6.1 RTCPeerConnection接口扩展
6.1.1 RTCSctpTransport接口
6.1.1.1 创建实例
6.1.1.2 更新消息大小的最大值
6.1.1.3 连接过程
6.1.2 RTCSctpTransportState枚举
6.2 RTCDataChannel
6.3 RTCDataChannelEvent
6.4 垃圾回收
7. 点对点DTMF
7.1 RTCRtpSender接口扩展
7.3 RTCDTMFSender
7.3 canInsertDTMF算法
7.4 RTCDTMFToneChangeEvent
8. 统计模型
8.1 介绍
8.2 RTCPeerConnection接口扩展
8.3 RTCStatsReport对象
8.4 RTCStats字典
8.5 RTCStatsEvent
8.6 统计信息选择算法
8.7 强制实施统计数据
8.8 GetStats例子
9. 用于网络的Medis Stream API扩展
9.1 介绍
9.2 MediaStream
9.2.1 id
9.3 MediaStreamTrack
9.3.1 MediaTrackSupportedConstraints, MediaTrackCapabilities, MediaTrackConstraints及MediaTrackSettings
10. 例子与调用流程
10.1 简易的点对点示例
10.2 进阶的点对点示例-热身
10.3 点对点传输示例-媒体数据先于信号
10.4 联播示例
10.5 点对点数据示例
10.6 浏览器间的调用流程
10.7 DTMF示例
11. 错误处理
11.1 ECMAScript 6术语
11.2 RTCError对象
11.2.1 RTCError构造函数
11.2.1.1 RTCErrorDetailType枚举
11.2.1.2 RTCError(errorDetail, message)
11.2.2 RTCError构造函数的属性
11.2.2.1 RTCError.prototype
11.2.3 RTCError原型对象属性
11.2.3.1 RTCError.prototype.constructor
11.2.3.2 RTCError.prototype.errorDetail
11.2.3.3 RTCError.prototype.sdpLineNumber
11.2.3.4 RTCError.prototype.httpRequestStatusCode
11.2.3.5 RTCError.prototype.sctpCauseCode
11.2.3.6 RTCError.prototype.receivedAlert
11.2.3.7 RTCError.prototype.sentAlert
11.2.3.8 RTCError.prototype.message
11.2.3.9 RTCError.prototype.name
11.2.4 RTCError实例的属性
12. 事件摘要
13. 隐私与安全考量
13.1 对同源策略的影响
13.2 泄露IP地址
13.3 对本地网络的影响
13.4 通信保密性
13.5 WebRTC公开的持久性信息
A. 致谢
B. 参考文献
B.1 规范性参考文献
B.2 非规范性参考文献
WebRTC 1.0 浏览器间实时通讯 W3C 推荐标准 30分钟构建流畅清晰的视频、音频通话 1天实现稳定的APP私聊、群聊、聊天室功能
网易云信核心能力 IM云 单聊 群聊 多人大群 聊天室 自定义消息扩展 音视频通话 音频通话 视频通话 点对点通话 多对多通话 录制 音视频通话 视频采集 短视频采集编辑 视频播放 CDN分发 频道管理 录制美颜、伴音等 点播 媒体存储 断点续传 视频转码 播放器 CDN加速 视频管理 短视频秒开管理 短信码通道 短信码验证 模板短信 营销短信 多通道切换 短信统计 专线电话 多人通话 多方通话 分钟统计 拨打查询
WebRTC1.0: 浏览器间的实时通信 1.介绍 本规范涵盖了对等通信(peer-to-peer communications)和网页视频会议的多个方面: 利用ICE,STUN,TURN等NAT穿透技术连接至远程对等终端。 将本地产生的媒体流发送至对端并接收对端产生的媒体流。 直接向远程对等终端发送任意数据。 本文档针对这些特性定义了一些API。本规范是在IETF RTCWEB工作组的协议规范,和Media Capture Task Force工 作组的访问本地媒体设备API规范[GEtUSERMEDIA],两者共同催动下发展出来的。系统的概览可以在引用列表中的 RTCWEB-OVERVIW和RTCWEB-SECURITY找到。 2.一致性 关键词 MAY, MUST, MUST NOT, SHALL, SHOULD 的语义解释在RFC2119中都有描述。 本规范定义了适用于某个产 品的一致性标准:用户代理应实现规范包含的接口。 一致性的要求可以被表述为一些算法,或被实现为任意行为的 特定步骤,只要它们最终的结果是等效的。(特别地,规范中定义的算法更易理解,但性能也许不尽如人意。) 本 规范中定义的API,必须(MUST)以WEBIDL中规定的行为一致的ECMAScript绑定的方式实现,毕竟我们使用了它 们的规范与术语。 3.术语 EventHandler接口代表了一个事件回调,ErrorEvent接口定义在HTML51 任务入队(queue a task)和网络任务源(networking task source)的概念定义在HTML51。 构造事件(fire an event)的概念定义在DOM。 事件(event),事件句柄(event handler)和事件句柄类型(event handler event types)定义在HTML51。 performance.timeOrigin和performance.now()定义在HIGHRES-TIME。 可序列化对象(serializable objects),序列化步骤(serialization step),反序列化步骤(deserialization steps)定义在HTML。 媒体流(MediaStream),媒体流轨(MediaStreamTrack),媒体流约束(MediaStreamConstraints)定义在 GETUSERMEDIA。 Blob 定义在FILEAPI。 媒体描述(media description)定义在RFC4566。 媒体传输(media transport)定义在RFC7656。 地址(generation)定义在TRICKLE-ICE的第二节。 RTCStatsType,stats object和monitored object 定义在WEBRTC-STATS。 当引入异常时,WEBIDL-1中定义了 throw和create。 "throw"作为INFRA中的规定来使用:它会终止目前正在运行的操作。 Promises 的上下文中使用的 fulfilled, rejected, resolved, pending和settled 在ECMASCRIPT-6.0中定义。 捆绑(bundle),只捆绑(bundle-only)和捆绑策略(bundle-policy)在JSEP中定义。 OAuth客户端(OAuth Client)和授权服务(Authorization Server)在RFC6749的1.1节被定义。 隔离流(isolated stream),对等身份(peer identity),身份声明请求(request an identity assertion)和身份 认证(validate the identity)在WEBRTC-IDENTITY中定义。 想获取更多技术干货,欢迎访问https://yunxin.163.com/
注意: 通常使用Javascript API的原则包括: 同步运行 和 数据独立 ,它们都在API-DESIGN-PRINCIPLES中定义 了。也就是说,当一个任务正在运行时,任何外部事件都不会影响Javascript应用的可见性。例如,当 Javascript执行时,缓存在数据通道里的数据数量将会随着"send"的调用而增长,并且直到任务的检查点之后, 由于发送数据包导致的减少才被应用可见。 用户代理负责确保呈现给应用程序的的数据是一致的——例如 getContributingSources() (同步调用)会返回当前所有被检测的数据源的值。 4. 对等连接 4.1 介绍 一个RTCPeerConnection实例允许与另一个浏览器,或实现了制定协议的终端中的 RTCPeerConnection 实例建立对 等通信。双方在信令通道中通过控制消息(即自定义的信令协议)协商会话,信号通道并没有明确的制定,但通常是 服务页面中的一段脚本,例如XMLHttpRequest,也可以是WebSockets。 4.2 配置 4.2.1 字典 RTCConfiguration 定义了一系列用于配置如何通过 RTCPeerConnection 建立/重建对等通信的参数。 dictionary RTCConfiguration {  sequence iceServers;  RTCIceTransportPolicy iceTransportPolicy = "all";  RTCBundlePolicy bundlePolicy = "balanced";  RTCRtcpMuxPolicy rtcpMuxPolicy = "require";  DOMString peerIdentity;  sequence certificates; [EnforceRange]  octet iceCandidatePoolSize = 0; }; RTCConfiguration 字典成员变量: sequence类型的的 iceServers :描述可供ICE使用的服务对象数组,例如STUN服务和TURN服务。 RTCIceTransportPolicy类型的 iceTransportPolicy ,缺省值为"all":指示哪个候选 ICE Agent 可用。 RTCBundlePolicy类型的 bundlePolicy ,缺省值为"balanced":当收集候选ICE时指示使用什么媒体捆绑策 略。 RTCRtcpMuxPolicy类型的 rtcMuxPolicy ,缺省值为"require":当收集候选ICE时指示使用什么RTCP复用策 略。 DOMString类型的 peerIdentity :为RTCPeerConnection设置目标对等终端的身份。只有成功地对身份进行 鉴权,RTCPeerConnection才能与远程对等终端建立起连接。 sequence类型的 certificates :RTCPeerConnection鉴权时所需的一系列证书。 此参数的合法值通过调用 generateCertificate 函数得到。 尽管任意给定的DTLS连接只会使用一份证书,但这一属性使得调用方可以供应多种证书以支持不同的算法。在 DTLS连接的握手阶段,它会最终选择一份允许范围内的证书。RTCPeerConnection的具体实现中完成了对给定 连接的证书选择过程,但证书是如何选择的并不在本规范的讨论范围之内。 如果值为空,则每个RTCPeerConnection实例都会生成默认的证书集合。 此选项还使得应用的密钥连续性成为可能。一个 RTCCertificate 可以被持久化存储在INDEXEDDB中并被复 想获取更多技术干货,欢迎访问https://yunxin.163.com/R T C C o n f i g u r a t i o n
用。持久化和复用避免了密钥重复生成的开销。 此配置选项的值在初始化阶段被选择后就不能再被改变。 octet 类型的 iceCandidatePoolSize ,缺省值为 0 :预先获取的ICE池的大小在JSEP的第3.5.4节和4.1.1节被 定义。 4.2.2 枚举值 enum RTCIceCredentialType {    "password",    "oauth" }; 枚举值简述: password:此凭据是依托于用户名和密码的长期认证方式,RFC5389的10.2节有详细描述 oauth:一个基于OAuth2.0的认证方法,在RFC7635有描述。 对于OAuth认证,需要向ICE Agent供应3份证书信息: kid (用于RTCIceServer成员变量username), macKey 和 accessToken (存在于RTCOAuthCredential字典类型内)。 注意:本规范并没有定义应用(起OAuth Client的作用)是如何从 获取 这些证书的,因为WebRTC只处理ICE Agent与TURN Server之间的交互。例 如,应用可能使用PoP(Proof-of-Possession)的Token证书类型,使用OAuth 2.0隐式授权类型。RFC的附 录B中有此示例。 OAuth Client应用,负责刷新证书信息,并且在 accessToken 失效前利用新的证书信息更新ICE Agent。OAuth Client可以利用RTCPeerConnection的setConfiguration方法来周期性的刷新TURN证书。 HMAC密钥(RTCOAuthCredential.macKey)的长度应是一个大于20字节的整数(160位)。 注意:根据RFC76354.1节,HMAC密钥必须是对称密钥,但对称密钥会生成 STUN信息不兼容。 注意:目前的STUN/TURN协议只是用了SHA-1/SHA-2族哈希算法来保证消息完整性,这在[RFC5389]的15.3 节和[STUN-BIS]的14.6节作了定义。 大型的访问令牌,可能和单个 4.2.3 字典 RTCOAuthCredential 字典被STUN/TURN客户端(内置于ICE Agent内)用于描述OAuth的鉴权证书信息,对 STUN/TURN服务器进行身份认证,RFC7635有相关描述。注意 kid 参数并不在此字典类型中,而在 RTCIceServer 的 username 成员变量中。 dictionary RTCOAuthCredential {    required DOMString macKey;    required DOMString accessToken; }; RTCOAuthCredential 字典的成员变量: DOMString类型的 macKey ,非空:"mac_key"是一串base64-url格式的编码,在RFC7635的6.2节有相关描 述。它被用在STUN的消息完整性哈希计算中(密码使用的则是基于密码的认证方式)。注意,OAuth响应里 的"key"参数是一个JSON Web Key(JWK)或JWK编码后JWE格式的消息。同样注意,这是OAuth中唯一一个不 被直接使用的参数,它只能从JWK的"k"参数中提取出来,"k"参数包含了需要的base-64编码的"mac_key"。 DOMString类型的 accessToken ,非空:"access_token"是一串base64格式的编码,在RFC7635的6.2节有相 关描述。这是一个自持有的令牌,应用不可见。认证加密被用于消息的加密和完整性保护。访问令牌包括了一 想获取更多技术干货,欢迎访问https://yunxin.163.com/R T C I c e C r e d e n t i a l T y p e A u t h o r i z a t i o n S e r v e r a c c e s s T o k e n , k i d , m a c K e y  R T C O A u t h C r e d e n t i a l
个未加密的nonce值,供认证服务生成唯一的 mac_key 。令牌的第二部分由认证加密服务保护着,包括 mac_key,时间戳和生存时间。时间戳和生存时间共同组成了过期信息,过期信息描述了令牌证书合法且能被 TURN服务接受的时间窗口。 RTCOAuthCredential字典的一个例子: // EXAMPLE 1 {  macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',  accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA== ' } 4.2.4 字典 RTCIceServer 字典被ICE Agent用来描述和对等终端建立连接的STUN/TURN服务器信息。 dictionary RTCIceServer {    required (DOMString or sequence) urls;             DOMString                          username;             (DOMString or RTCOAuthCredential)  credential;             RTCIceCredentialType               credentialType = "password"; }; RTCIceServer 字典的成员变量: DOMString或sequence类型的 urls ,非空:[RFC7064]和[RFC7065]中定义的STUN/TURN的URI(s),或其他 的URI类型。 DOMString类型的 username :如果 RTCIceServer 代表了一个TURN服务器,且 credentialType 是 "password" ,那么这一属性指定的是TURN服务器使用的用户名。 如果 RTCIceServer 代表了一个TURN服务器,且 credentialType 是 "oauth" ,那么这一属性指定的是TURN 服务器和认证服务器之间共享的对称密钥的密钥id,RFC7635有相关描述。这是一个短暂且唯一的密钥标识 符。 kid 允许TURN服务器选择合适的密钥材料对访问令牌进行解密,因此以 kid 为代表的密钥标识符被用 于"access_token"的加密。 kid 值和OAuth响应中的"kid"参数相同,这被定义在RFC7515的4.1.4节。 DOMString或RTCOAuthCredential类型的 credential :如果 RTCIceServer 代表了一个TURN服务器,那么 这一属性指定的是TURN服务器使用的证书。 如果 credentialType 是 "password" ,那么 credential 是 DOMString 类型,代表了长期使用的认证密码, 这在RFC5389的10.2节有相关描述。 如果 credentialType 是 "oauth" ,那么 credential 是 RTCOAuthCredential 类型,包含了OAuth访问令牌 和MAC值。 RTCIceCredentialType类型的 credentialType ,默认值为"password":如果 RTCIceServer 代表了一个 TURN服务器,那么这一属性在TURN服务器需要认证客户端时使用。 一个RTCIceServer对象数组的例子: [ {urls: 'stun:stun1.example.net'}, {urls: ['turns:turn.example.org', 'turn:turn.example.net'],    username: 'user', 想获取更多技术干货,欢迎访问https://yunxin.163.com/R T C I c e S e r v e r
   credential: 'myPassword',    credentialType: 'password'}, {urls: 'turns:turn2.example.net',    username: '22BIjxU93h/IgwEb',    credential: {      macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',      accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA== '   },    credentialType: 'oauth'} ]; 4.2.5 枚举值 如JSEP4.1.1节所定义,如果 RTCConfiguration 的 iceTransportPolicy 成员被指定,它将指示浏览器获取ICE候选 地址的策略,定义在JSEP 3.5.3节,浏览器只会收集特定的候选地址用于连接性检查。 enum RTCIceTransportPolicy {    "relay",    "all" }; 枚举值的非规范描述: relay:ICE Agent仅获取媒体中继ice候选地址,例如通过TURN服务器传递的ice候选地址。注意:该配置表明 只收集中继服务器分配的ice候选地址,这可以在某些特定场景下防止远程终端获取该用户的真实IP地址。例 如,在一个基于“调用”的应用中,应用可能想防止某个未知的调用者获得被调用方得IP地址,除非被调用方以 某些同意。 all:当被指定为"all"时,ICE Agent可以使用任意类型的候选地址。注意:在具体实现中,仍然可以使用自己的 候选地址过渡策略来限制暴露给应用的IP地址,这在RTCIceCandidate.address中有提到。 4.2.6 枚举值 如JSEP 4.1.1节提到,如果远程端点不支持捆绑,则捆绑策略会影响哪些媒体轨参与协商,以及哪些ICE候选地址被收 集。如果远程端点支持捆绑,所有媒体轨和数据通道都会被捆绑到同一传输路径上。 enum RTCBundlePolicy {    "balanced",    "max-compat",    "max-bundle" }; 枚举值的非规范描述: balanced:为所有正在使用中的媒体类型(音频,视频和数据)收集ICE候选地址。如果远程端点不支持捆绑, 则只会为每个独立的传输协商一个音频或视频。 max-compat:为每个流媒体轨收集ICE候选地址。如果远程端点不支持捆绑,为每个独立传输协商所有的媒体 轨。 max-bundle:只为一个媒体轨收集ICE候选地址。如果远程端点不支持捆绑,只协商一个媒体轨。 想获取更多技术干货,欢迎访问https://yunxin.163.com/R T C I c e T r a n s p o r t P o l i c y R T C B u n d l e P o l i c y
4.2.7 枚举值 如JSEP 4.1.1节中描述的,RtcpMuxPolicy会影响ICE候选地址收集哪些内容以支持非多路复用RTCP。 enum RTCRtcpMuxPolicy { // At risk due to lack of implementers' interest. "negotiate", "require" }; 枚举值的非规范描述: negotiate:同时收集RTP候选地址和RTCP候选地址。如果远程端点能够复用RTCP,则在RTP候选地址之上复用 RTCP。如果不能,独立地使用RTP和RTCP候选地址。注意,JSEP 4.1.1节提到,用户代理可能没有实现不复用 的RTCP,在这种情况下所有试图以 negotiate 策略构造 RTCPeerConnection 的操作都会被拒绝。 require:只收集RTC候选地址和在RTP基础上复用了RTCP的候选地址。如果远程端点不支持rtcp复用,那么会 话协商将失败。 风险特征:支持非多路复用RTP/RTCP的本规范的各个方面被标记为存在风险的特征,因为实现者没有明确的 承诺。包括:1. 对于 negotiate 值,实现者没有明确承诺与此相关的行为。 2.在 RTCRtpSender 和 RTCRtpReceiver 之内支持 rtcpTransport 属性。 4.2.8 邀请/应答选项 这些字典类型描述了可用于邀请/应答创建过程的选项。 dictionary RTCOfferAnswerOptions { boolean voiceActivityDetection = true; }; RTCOfferAnswerOptions 成员变量: boolean类型的 voiceActivityDetection ,缺省值为"true":很多编解码器和系统都能够检测到“静音”,并改 变它们的行为,例如不传输任何媒体信息。在很多场景下,例如处理紧急呼叫或不仅仅人声之外的语音时,我 们希望能够关闭这个选项。这个选项允许应用提供关于是否希望开启或关闭这类处理的信息。 dictionary RTCOfferOptions : RTCOfferAnswerOptions { boolean iceRestart = false; }; RTCOfferOptions 成员变量: boolean类型的 iceRestart ,缺省值为"false":当此值为true时,会生成与当前证书(在 localDescription 属性的SDP中可见)不同的ICE证书。应用此描述将重启ICE,具体描述在ICE的9.1.1.1节。 当此值为false, localDescription 属性具有有效的ICE证书,生成的描述将和当前的 localDescription 属 性一致。 注意:当 转换为"failed"时,建议执行ICE重启。应用也可能额外监听 到"disconnected"的变化,然后使用其他信息来源(比如使用 测量接下来 几秒内发送或接收的字节数是否增加)确定是否应该重启ICE。 RTCAnswerOptions 字典描述了指定 answer 类型会话的选项。 想获取更多技术干货,欢迎访问https://yunxin.163.com/R T C R t c p M u x P o l i c y i c e C o n n e c t i o n S t a t e i c e C o n n e c t i o n S t a t e g e t S t a t s
分享到:
收藏