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