Broadcasting - Straas/Straas-web-document GitHub Wiki

WebRTC in Browser

This feature is DEPRECATED. Please contact StraaS team for more information.

Overview

StraaS provides a set of APIs for browsers to broadcast, utilizing WebRTC WebAPIs.

WebRTC provides browsers with Real-Time Communications (RTC) capabilities. With WebRTC-enabled browsers, you can start broadcasting to StraaS without installing other broadcasting softwares on your PC.

In order to establish a WebRTC connection, signalling service is required to exchange SDP & ICE candidate information. We provide a dedicated API to achieve the signalling process. You need only a single API call to start broadcasting.

Prerequisite

• Only Chrome browser is supported.
• Acquire stream key of the live event, via StraaS CMS portal or StraaS CMS API.
  • CMS API Create Live
• Acquire TRUN server credential information of the live event, via StraaS CMS API.
  • CMS API Get Live WebRTC TURN

Getting Started

Stream

• Prepare MediaStream using WebAPI MediaDevices.getUserMedia().
  • Note: Now we only support stream of 720p video w/ audio.

let stream;

navigator.mediaDevices.getUserMedia({
    audio: true,
    video: {
      width: { min: 1280 },
      height: { min: 720 },
    }
  })
  .then(mediaStream => {
    stream = mediaStream;
  });

RTCPeerConnection and SDP

• Prepare RTCPeerConnection, and set onicecandidate event handler to retrieve ICE candidate information.
  • Note: Now we do not support DtlsSrtpKeyAgreement.
  • In this example, video bitrate is limited to 1000 Kbps to get a reliable stream. You could choose your own bitrate setting, or remove the limitation which means the bitrate limit is controlled by browsers.

let peerConn = new RTCPeerConnection({
  iceServers: [
    // replace with TURN server credential info returned from CMS API
    {
      urls: ['turn:1.2.3.4?transport=tcp'],
      username: '1509677133:foobar',
      credential: 'foobarcredential'
    }
  ],
  iceTransportPolicy: 'relay',
}, {
  optional: [{'DtlsSrtpKeyAgreement': false}]
});
let iceCandidates = '';
let offerSDP;

peerConn.onicecandidate = function (event) {
  if (event.candidate) {
    iceCandidates += ('a=' + event.candidate.candidate + '\r\n');
  } else {
    console.log('ICE gathering has finished');
    startBroadcasting(); // Will be defined later
  }
};

peerConn.addStream(stream);
peerConn.createOffer()
  .then(offer => {
    const videoBitrateKbps = 1000;
    offer.sdp = setVideoBitrate(offer.sdp, videoBitrateKbps);
    offerSDP = offer.sdp;
    return peerConn.setLocalDescription(offer);
  });

// SDP modification
function setVideoBitrate(sdp, bitrateKbps) {
  return sdp.replace(/a=mid:video\r\n/g, 'a=mid:video\r\nb=AS:' + bitrateKbps + '\r\n');
}

StraaS API

• Call API POST /broadcasts/webrtc when ICE gathering has finished, and set remote description from the API response.

function startBroadcasting() {
  let path = 'https://rtc-middleware.straas.io/broadcasts/webrtc';
  let headers = 'Content-Type: application/json';
  let body = {
    stream_key: <your stream key>,
    sdp: offerSDP + iceCandidates,
  };
  let remoteCandidates;

  // Replace your HTTP request function here
  httpRequest('POST', path, headers, body)
    .then(responseText => {
      let response = JSON.parse(responseText);
      let remoteDesc = new RTCSessionDescription({type: 'answer', sdp: response.sdp});

      remoteCandidates = response.remoteCandidates;
      return peerConn.setRemoteDescription(remoteDesc);
    })
    .then(() => {
      for (let candidate of remoteCandidates) {
        peerConn.addIceCandidate(new RTCIceCandidate({candidate: candidate}));
      }
    });
}

• To stop broadcasting, call API DELETE /broadcasts/webrtc.

function stopBroadcasting() {
  let path = 'https://rtc-middleware.straas.io/broadcasts/webrtc';
  let headers = 'Content-Type: application/json';
  let body = {
    stream_key: <your stream key>,
  };

  // Replace your HTTP request function here
  httpRequest('DELETE', path, headers, body);
}

Connection State Events

• You can listen to RTCPeerConnection oniceconnectionstatechange event to get the streaming status.
  • WebAPI Reference

peerConn.oniceconnectionstatechange = function(event) {
  if (peerConn.iceconnectionstate === "failed" ||
      peerConn.iceconnectionstate === "closed") {
    // peer connection encountered some errors.
    stopBroadcasting();
};

Sample Code

API Reference

• API Host: rtc-middleware.straas.io

Start Broadcasting

• Path: POST /broadcasts/webrtc

• Headers: Content-Type: application/json

• Request Parameters:

  Name	Required	Description	Type
  stream_key	V	Stream key of the live event.	string
  sdp	V	Offer SDP. Candidate information must be appended.	string

• Response Fields:

  Name	Description	Type
  sdp	Answer SDP.	string
  remoteCandidates	List of remote candidates strings.	list

Stop Broadcasting

• Path: DELETE /broadcasts/webrtc

• Headers: Content-Type: application/json

• Request Parameters:

  Name	Required	Description	Type
  stream_key	V	Stream key of the live event.	string