path: root/files/ru/web/api/webrtc_api/webrtc_basics/index.html

---
title: Основы WebRTC
slug: Web/API/WebRTC_API/WebRTC_basics
translation_of: Web/API/WebRTC_API/Signaling_and_video_calling
translation_of_original: Web/API/WebRTC_API/WebRTC_basics
---
<p>{{WebRTCSidebar}}</p>

<p>{{Draft}}</p>

<div class="summary">
<p>После того, как вы понимаете <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Architecture" title="/en-US/docs/Web/Guide/API/WebRTC/WebRTC_architecture">WebRTC architecture</a>, вы можете прочитать эту статью, которая сопроводит вас через создание кросс-браузерного RTC приложения. К концу этой документации, вы должны иметь рабочие каналы соединения равноправных узлов ЛВС и передачи данных средств массовой информации.</p>
</div>

<h2 id="Полу-старое_содержание_из">Полу-старое содержание, из</h2>

<h2 id="RTCPeerConnection">RTCPeerConnection</h2>

<p>Материал здесь происходит от RTCPeerConnection; она может остаться здесь, или же  может переместится в другое место.</p>

<p><strong>Основы использования</strong><br>
 Базовое использование RTCPeerConnection предполагает переговоры связь между локальной машиной и удаленной машиной один генерируя Session Description Protocol для обмена между ними. Вызывающая программа начинает процесс, отправив предложение на удаленное устройство, которое реагирует либо принять или отклонить запрос на соединение.</p>

<p>Обе стороны (вызывающий и вызываемый абонент) необходимо настроить свои собственные экземпляры RTCPeerConnection, чтобы представить их конец соединения равноправных узлов ЛВС:</p>

<pre class="brush: js notranslate">var pc = new RTCPeerConnection();
pc.onaddstream = function(obj) {
  var vid = document.createElement("video");
  document.appendChild(vid);
  vid.srcObject = obj.stream;
}

// функция помощник
function endCall() {
  var videos = document.getElementsByTagName("video");
  for (var i = 0; i &lt; videos.length; i++) {
    videos[i].pause();
  }

  pc.<a href="#close()">close</a>();


function error(err) {
  endCall();
}
</pre>

<h3 id="При_инициализации_вызова">При инициализации вызова</h3>

<p>Если вы один инициирующий вызов, вы будете использовать navigator.getUserMedia(), чтобы получить видеопоток, а затем добавить поток в RTCPeerConnection. Как только это было сделано, вызов RTCPeerConnection, чтобы создать предложение, настроить предложение, а затем отправить его на сервер, через  соединение которое было создано.</p>

<pre class="brush: js notranslate">// Получить список людей с сервера
// Пользователь выбирает список людей, чтобы установить соединение с нужным человеком
navigator.getUserMedia({video: true}, function(stream) {
  // Добавление локального потока не вызовет onaddstream обратного вызова,
  // так называют его вручную.
  pc.onaddstream = e =&gt; video.src = URL.createObjectURL(e.stream);
  pc.<a href="#addStream()">addStream</a>(stream);

  pc.<a href="#createOffer()">createOffer</a>(function(offer) {
    pc.<a href="#setLocalDescription()">setLocalDescription</a>(offer, function() {
      // send the offer to a server to be forwarded to the friend you're calling.
    }, error);
  }, error);
});
</pre>

<h3 id="Ответ_на_вызов">Ответ на вызов</h3>

<p>На противоположном конце, друг получит предложение от сервера, используя любой протокол используется для того чтобы сделать это. После того, как предложение прибывает, {{domxref ("navigator.getUserMedia ()")}} вновь используется для создания потока, который добавляется к RTCPeerConnection. {{Domxref ("RTCSessionDescription")}} объект создается и установить в качестве удаленного описания с помощью вызова {{domxref ("RTCPeerConnection.setRemoteDescription ()")}}.</p>

<p>Тогда ответ создается с помощью RTCPeerConnection.createAnswer () и отправляется обратно на сервер, который направляет его к вызывающему абоненту.</p>

<pre class="brush: js notranslate">var offer = getOfferFromFriend();
navigator.getUserMedia({video: true}, function(stream) {
  pc.onaddstream = e =&gt; video.src = URL.createObjectURL(e.stream);
  pc.<a href="#addStream()">addStream</a>(stream);

  pc.setRemoteDescription(new <span class="nx">RTCSessionDescription</span>(offer), function() {
    pc.<a href="#createAnswer()">createAnswer</a>(function(answer) {
      pc.<a href="#setLocalDescription()">setLocalDescription</a>(answer, function() {
        // send the answer to a server to be forwarded back to the caller (you)
      }, error);
    }, error);
  }, error);
});
</pre>

<p><strong>Ответ на вызов</strong></p>

<p>На противоположном конце, человек получит предложение от сервера, используя любой протокол используется для того чтобы сделать это. После того, как предложение принято, navigator.getUserMedia () вновь используется для создания потока, который добавляется к RTCPeerConnection.  объект создается и установить в качестве удаленного описания с помощью вызова {{domxref ("RTCPeerConnection.setRemoteDescription ()")}}.</p>

<p>Тогда ответ создается с помощью RTCPeerConnection.createAnswer () и отправляется обратно на сервер, который направляет его к вызывающему абоненту.</p>

<pre class="brush: js notranslate">// ПК был создан раньше, когда мы сделали первоначальное предложение
var offer = getResponseFromFriend();
pc.<a href="#createAnswer()">setRemoteDescription</a>(new <span class="nx">RTCSessionDescription</span>(offer), function() { }, error);</pre>

<h2 id="Old_content_follows!">Old content follows!</h2>

<p>Все, что находится ниже этого пункта,  потенциально устарело. Это по-прежнему находится в стадии рассмотрения  и возможного включения в другие части документации, если они все еще актуальны.</p>

<div class="note">
<p><strong>Не используйте примеры на этой странице.</strong> Смотрите статью <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a> для работы, актуальный пример с использованием WebRTC media.</p>
</div>

<h3 id="Note">Note</h3>

<p>Due to recent changes in the API there are many old examples that require fixing:</p>

<ul>
 <li><a href="http://louisstow.github.io/WebRTC/media.html">louisstow</a></li>
 <li><a href="http://mozilla.github.io/webrtc-landing/">mozilla</a></li>
 <li><a href="https://www.webrtc-experiment.com/">webrtc-experiment</a></li>
</ul>

<p>The currently working example is:</p>

<ul>
 <li><a href="https://apprtc.appspot.com">apprtc</a> (<a href="https://github.com/webrtc/apprtc">source</a>)</li>
</ul>

<p>Implementation may be inferred from the <a href="http://w3c.github.io/webrtc-pc/">specification</a>.</p>

<p>This remainder of this page contains outdated information as <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1119285">noted on bugzilla</a>.</p>

<h3 id="Shims">Shims</h3>

<p>As you can imagine, with such an early API, you must use the browser prefixes and shim it to a common variable.</p>

<pre class="brush: js notranslate">var RTCPeerConnection = window.mozRTCPeerConnection || window.webkitRTCPeerConnection;
var IceCandidate = window.mozRTCIceCandidate || window.RTCIceCandidate;
var SessionDescription = window.mozRTCSessionDescription || window.RTCSessionDescription;
navigator.getUserMedia = navigator.getUserMedia || navigator.mozGetUserMedia || navigator.webkitGetUserMedia;</pre>

<h3 id="RTCPeerConnection_2">RTCPeerConnection</h3>

<p>This is the starting point to creating a connection with a peer. It accepts configuration options about ICE servers to use to establish a connection.</p>

<pre class="brush: js notranslate">var pc = new RTCPeerConnection(configuration);</pre>

<h3 id="RTCConfiguration"><strong><code>RTCConfiguration</code></strong></h3>

<p>The {{domxref("RTCConfiguration")}} object contains information about which TURN and/or STUN servers to use for ICE. This is required to ensure most users can actually create a connection by avoiding restrictions in NAT and firewalls.</p>

<pre class="brush: js notranslate">var configuration = {
    iceServers: [
        {urls: "stun:23.21.150.121"},
        {urls: "stun:stun.l.google.com:19302"},
        {urls: "turn:numb.viagenie.ca", credential: "webrtcdemo", username: "louis%40mozilla.com"}
    ]
}</pre>

<p>Google runs a <a href="https://code.google.com/p/natvpn/source/browse/trunk/stun_server_list">public STUN server</a> that we can use. I also created an account at http://numb.viagenie.ca/ for a free TURN server to access. You may want to do the same and replace with your own credentials.</p>

<h3 id="ICECandidate">ICECandidate</h3>



<p>After creating the PeerConnection and passing in the available <a href="/en-US/docs/Web/Guide/API/WebRTC/WebRTC_architecture#What_is_STUN.3F">STUN</a> and <a href="/en-US/docs/Web/Guide/API/WebRTC/WebRTC_architecture#What_is_TURN.3F">TURN</a> servers, an event will be fired once the ICE framework has found some “candidates” that will allow you to connect with a peer. This is known as an ICE Candidate and will execute a callback function on <a href="/en-US/docs/Web/API/RTCPeerConnection.onicecandidate">PeerConnection#onicecandidate</a>.</p>

<pre class="brush: js notranslate" lang="javascript">pc.onicecandidate = function (e) {
    // candidate exists in e.candidate
    if (!e.candidate) return;
    send("icecandidate", JSON.stringify(e.candidate));
};</pre>

<p>When the callback is executed, we must use the signal channel to send the Candidate to the peer. On Chrome, multiple ICE candidates are usually found, we only need one so I typically send the first one then remove the handler. Firefox includes the Candidate in the Offer SDP.</p>

<h3 id="Signal_Channel">Signal Channel</h3>

<p>Now that we have an ICE candidate, we need to send that to our peer so they know how to connect with us. However this leaves us with a chicken and egg situation; we want PeerConnection to send data to a peer but before that we need to send them metadata…</p>

<p>This is where the signal channel comes in. It’s any method of data transport that allows two peers to exchange information. In this article, we’re going to use <a href="http://firebase.com">FireBase</a> because it’s incredibly easy to setup and doesn't require any hosting or server-code.</p>

<p>For now just imagine two methods exist: <code>send()</code> will take a key and assign data to it and <code>recv()</code> will call a handler when a key has a value.</p>

<p>The structure of the database will look like this:</p>

<pre class="brush: js notranslate" lang="json">{
    "": {
        "candidate:": …
        "offer": …
        "answer": …
    }
}</pre>

<p>Connections are divided by a <code>roomId</code> and will store 4 pieces of information, the ICE candidate from the offerer, the ICE candidate from the answerer, the offer SDP and the answer SDP.</p>

<h3 id="Offer">Offer</h3>

<p>An Offer SDP (Session Description Protocol) is metadata that describes to the other peer the format to expect (video, formats, codecs, encryption, resolution, size, etc etc).</p>

<p>An exchange requires an offer from a peer, then the other peer must receive the offer and provide back an answer.</p>

<pre class="brush: js notranslate" lang="javascript">pc.createOffer(function (offer) {
    pc.setLocalDescription(offer, function() {
        send("offer", JSON.stringify(pc.localDescription);
    }, errorHandler);
}, errorHandler, options);</pre>

<h4 id="errorHandler"><strong><code>errorHandler</code></strong></h4>

<p>If there was an issue generating an offer, this method will be executed with error details as the first argument.</p>

<pre class="brush: js notranslate" lang="javascript">var errorHandler = function (err) {
    console.error(err);
};</pre>

<h5 id="options"><strong><code>options</code></strong></h5>

<p>Options for the offer SDP.</p>

<pre class="brush: js notranslate" lang="javascript">var options = {
    offerToReceiveAudio: true,
    offerToReceiveVideo: true
};</pre>

<p><code>offerToReceiveAudio/Video</code> tells the other peer that you would like to receive video or audio from them. This is not needed for DataChannels.</p>

<p>Once the offer has been generated we must set the local SDP to the new offer and send it through the signal channel to the other peer and await their Answer SDP.</p>

<h3 id="Answer">Answer</h3>

<p>An Answer SDP is just like an offer but a response; sort of like answering the phone. We can only generate an answer once we have received an offer.</p>

<pre class="brush: js notranslate" lang="javascript">recv("offer", function (offer) {
    offer = new SessionDescription(JSON.parse(offer))
    pc.setRemoteDescription(offer);

    pc.createAnswer(function (answer) {
        pc.setLocalDescription(answer, function() {
            send("answer", JSON.stringify(pc.localDescription));
        }, errorHandler);
    }, errorHandler);
});</pre>

<h3 id="DataChannel">DataChannel</h3>

<p>I will first explain how to use PeerConnection for the DataChannels API and transferring arbitrary data between peers.</p>

<p><em>Note: At the time of this article, interoperability between Chrome and Firefox is not possible with DataChannels. Chrome supports a similar but private protocol and will be supporting the standard protocol soon.</em></p>

<pre class="brush: js notranslate" lang="javascript">var channel = pc.createDataChannel(channelName, channelOptions);</pre>

<p>The offerer should be the peer who creates the channel. The answerer will receive the channel in the callback <code>ondatachannel</code> on PeerConnection. You must call <code>createDataChannel()</code> once before creating the offer.</p>

<h4 id="channelName"><strong><code>channelName</code></strong></h4>

<p>This is a string that acts as a label for your channel name. <em>Warning: Make sure your channel name has no spaces or Chrome will fail on <code>createAnswer()</code>.</em></p>

<h4 id="channelOptions"><strong><code>channelOptions</code></strong></h4>

<pre class="brush: js notranslate" lang="javascript">var channelOptions = {};</pre>

<p>Currently these options are not well supported on Chrome so you can leave this empty for now. Check the <a href="http://dev.w3.org/2011/webrtc/editor/webrtc.html#attributes-7">RFC</a> for more information about the options.</p>

<h4 id="Channel_Events_and_Methods">Channel Events and Methods</h4>

<h5 id="onopen"><strong><code>onopen</code></strong></h5>

<p>Executed when the connection is established.</p>

<h5 id="onerror"><strong><code>onerror</code></strong></h5>

<p>Executed if there is an error creating the connection. First argument is an error object.</p>

<pre class="brush: js notranslate" lang="javascript">channel.onerror = function (err) {
    console.error("Channel Error:", err);
};</pre>

<h5 id="onmessage"><strong><code>onmessage</code></strong></h5>

<pre class="brush: js notranslate" lang="javascript">channel.onmessage = function (e) {
    console.log("Got message:", e.data);
}</pre>

<p>The heart of the connection. When you receive a message, this method will execute. The first argument is an event object which contains the data, time received and other information.</p>

<h5 id="onclose"><strong><code>onclose</code></strong></h5>

<p>Executed if the other peer closes the connection.</p>

<h4 id="Binding_the_Events"><strong>Binding the Events</strong></h4>

<p>If you were the creator of the channel (meaning the offerer), you can bind events directly to the DataChannel you created with <code>createChannel</code>. If you are the answerer, you must use the <code>ondatachannel</code> callback on PeerConnection to access the same channel.</p>

<pre class="brush: js notranslate" lang="javascript">pc.ondatachannel = function (e) {
    e.channel.onmessage = function () { … };
};</pre>

<p>The channel is available in the event object passed into the handler as <code>e.channel</code>.</p>

<h5 id="send"><strong><code>send()</code></strong></h5>

<pre class="brush: js notranslate" lang="javascript">channel.send("Hi Peer!");</pre>

<p>This method allows you to send data directly to the peer! Amazing. You must send either String, Blob, ArrayBuffer or ArrayBufferView, so be sure to stringify objects.</p>

<h5 id="close"><strong><code>close()</code></strong></h5>

<p>Close the channel once the connection should end. It is recommended to do this on page unload.</p>

<h3 id="Media">Media</h3>

<p>Now we will cover transmitting media such as audio and video. To display the video and audio you must include a <code>&lt;video&gt;</code> tag on the document with the attribute <code>autoplay</code>.</p>

<h4 id="Get_User_Media">Get User Media</h4>

<pre class="brush: js notranslate">&lt;video id="preview" autoplay&gt;&lt;/video&gt;

var video = document.getElementById("preview");
navigator.getUserMedia(constraints, function (stream) {
    video.src = URL.createObjectURL(stream);
}, errorHandler);</pre>

<p><strong><code>constraints</code></strong></p>

<p>Constraints on what media types you want to return from the user.</p>

<pre class="brush: js notranslate" lang="javascript">var constraints = {
    video: true,
    audio: true
};</pre>

<p>If you just want an audio chat, remove the <code>video</code> member.</p>

<h5 id="errorHandler_2"><strong><code>errorHandler</code></strong></h5>

<p>Executed if there is an error returning the requested media.</p>

<h4 id="Media_Events_and_Methods">Media Events and Methods</h4>

<h5 id="addStream"><strong><code>addStream</code></strong></h5>

<p>Add the stream from <code>getUserMedia</code> to the PeerConnection.</p>

<pre class="brush: js notranslate" lang="javascript">pc.addStream(stream);</pre>

<h5 id="onaddstream"><strong><code>onaddstream</code></strong></h5>

<pre class="brush: js notranslate">&lt;video id="otherPeer" autoplay&gt;&lt;/video&gt;

var otherPeer = document.getElementById("otherPeer");
pc.onaddstream = function (e) {
    otherPeer.src = URL.createObjectURL(e.stream);
};</pre>

<p>Executed when the connection has been setup and the other peer has added the stream to the peer connection with <code>addStream</code>. You need another <code>&lt;video&gt;</code> tag to display the other peer's media.</p>

<p>The first argument is an event object with the other peer's media stream.</p>