Live Streaming API

Live Streaming API enables your WebRTC application to broadcast a video to multiple clients. The API supports two functions:

• Broadcast Videos
• Watch Videos

This guide demonstrates the basic usage of Live Streaming API. See Live Streaming API Reference for more API details.

Contents

• Quick Start
• Endpoints
• API Usage
• Manage Rooms
• Broadcast a Video
• Watch a Video
• Samples
• See Also

Quick Start

This section is designed to show you how to get started with Live Streaming API. If you already have an API Client for Live Streaming API, you can skip Step 1. Note that you need a RICOH Account for Step 1. To create one, see Get Started for detailed instructions. You can also look at Samples for working code.

Step 1: Create an API Client

Create an API client for Live Streaming API at Management Console. See Get Started for detailed instructions. After you successfully finish the procedure, you can check your Client ID and Client Secret at Dashboard.

Note: You can skip this step if you already have an API client for Live Streaming API.

Step 2: Obtain an Access Token

Obtain an access token using your Client ID and Client Secret to authenticate your API requests. Notice that Live Streaming API supports Client Credentials Grant of Authorization API. Learn how to make a request to Authorization API to obtain an access token and an API key at Obtain an Access Token and implement it on your application.

Step 3: Try Live Streaming API

Try Live Streaming API using your access token. To start broadcasting a video or watching the broadcast, you need to make a “room”, create some “tickets” and proceed to signaling. See the following sections to understand how the flow works and how to implement the flow on your application.

• API Usage Flow
• Manage Rooms
• Broadcast a Video
• Watch a Video

Endpoints

This section lists all of the Live Streaming API endpoints and a relevant endpoint:

API Usage Flow

Here is how to broadcast or watch a video:

1. Create a room
   • Room is a concept of streaming channel like channels in television. Rooms transmit your videos to your viewers. So, the first thing to start broadcasting your video is to create a room in SFU server.
   • You can make multiple rooms at a time.
2. Create tickets
   • Ticket contains necessary information to connect to a room.
   • There are two types of tickets: “upload” ticket for broadcasting client and “download” ticket for viewing client.
   • After creating a room, you can create an “upload” ticket and multiple “download” tickets for the room.
3. Signaling
   • Both broadcasting and viewing clients with tickets connect to the room via signaling.
   • When signaling is successfully done, those clients can start broadcasting a video or watching the broadcast.

Manage Rooms

To create or delete a room, send respective HTTP requests with an access token described in Step2 of Quick Start. Rooms transmit your broadcasting videos to viewers.

Create a Room

Create a POST request with your access token.

curl --request POST 'https://sfu.api.ricoh/v1/rooms' \
     --header 'Authorization: Bearer <Access Token>'

A successful response contains a JSON body like this:

{
  "id": "a39jcbc5-053c-4873-a7c0-0b20c3948472",
  "up_count": 0,
  "down_count": 0,
  "created_at": "2004-04-01T00:00:01Z"
}

The id is a room ID which you use to get tickets. Since this room is created soon before the response, it has 0 up_count, which means 0 broadcasting client, and 0 down_count, which means 0 viewing client. You can also obtain room status like this with HTTP GET request. See Live Streaming API Reference for details.

Note: The number of rooms you can own simultaneously differs according to your plan.

Delete a Room

After finishing your broadcast via a room, delete it by creating a DELETE request with your access token and its room ID.

curl --request DELETE 'https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472' \
     --header 'Authorization: Bearer <Access Token>'

Broadcast a Video

This section go through the procedure to broadcast a video. This procedure contains two steps: creating an upload ticket and signaling.

Create a Ticket

Create a POST request with your access token and a room ID. Also, you need to specify up with direction parameter.

curl --request POST 'https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472/tickets' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'Content-Type: application/json' \
     --data '{"direction":"up"}'

A successful response contains a JSON body like this:

{
  "access_token": "b29jcbc5-053c-4873-a7c0-0b20c39484b9",
  "id": "39jcbc5-053c-4873-a7c0-0b20c3948472",
  "url": "wss://sfu.api.ricoh/servers/1",
}

Both ticket token(access_token) and signaling endpoint(url) are necessary for signaling.

Signaling

For signaling phase, Live Streaming API supports WebSocket. To complete signaling, you need to open a WebSocket and send several messages. When signaling is successfully done, you can start broadcasting a video.

Once you open a WebSocket, you should attach some handlers such as onmessage and onclose to it in order to handle some status changes. When signaling errors occur, the onclose handler is called. See Live Streaming API Reference for more details and supported errors.

Open a WebSocket

Specify the signaling endpoint which you receive when you create a ticket, and then open a WebSocket.

var ws = new WebSocket('wss://sfu.api.ricoh/servers/1');

Send a Connect Message

Send a connect message via WebSocket. You must specify a room ID (channel_id), a ticket token (access_token) and role. Set role to upstream for broadcasting. Once this message succeeds, you will receive an offer message.

ws.send({
  "type": "connect",
  "role": "upstream",
  "channel_id": "39jcbc5-053c-4873-a7c0-0b20c3948472",
  "metadata": {
    "access_token": "b29jcbc5-053c-4873-a7c0-0b20c39484b9"
  }
});

Send an Answer Message

Once you receive an offer message, send an answer message back. You must include a SDP in the answer message. SDP is used to create connections between broadcasting/watching clients and the SFU server.

let localStream = null;
navigator.mediaDevices.getUserMedia(constraints)
 .then((stream) => {
    localStream = stream;
  });

ws.onmessage = async (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type == 'offer') {
    const config = msg.config;
    const certificate = await RTCPeerConnection.generateCertificate({ name: 'ECDSA', namedCurve: 'P-256' });
    config.certificates = [certificate];
    const pc = new RTCPeerConnection(config);
    pc.onicecandidate = (event) => {
      if (event.candidate) {
        const candidate = event.candidate.toJSON();
        candidate.type = 'candidate';
        ws.send(JSON.stringify(candidate));
      }
    };
    pc.addStream(localStream);
    await this.pc.setRemoteDescription(new RTCSessionDescription(msg));
    const sdp = await this._pc.createAnswer({});
    await this.pc.setLocalDescription(sdp);
    ws.send(JSON.stringify({ type: 'answer', sdp: pc.localDescription.sdp }));
  }
};

Once a connection is made, set a local video so that you can start broadcasting it.

(Optional) Send a Candidate Message

You can also specify more SDPs via candidate messages. A candidate message can describe a single SDP.

ws.send({
  "type": "candidate",
  "candidate": "candidate:3179889176 1 tcp 1518214911 192.168.1.10 0 typ host tcptype active generation 0"
});

Watch a Video

To watch a video, you need to go through a procedure similar to the one described in Broadcast a Video. This section focuses on some parts of the procedure which are different from broadcasting.

Create a Ticket

Create a POST request with your access token and a room ID. Also, you need to specify down with direction parameter.

curl --request POST 'https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472/tickets' \
     --header 'Authorization: Basic <base64 string>' \
     --header 'Content-Type: application/json' \
     --data '{"direction":"down"}'

A successful response contains a JSON body like this:

{
  "access_token": "b29jcbc5-053c-4873-a7c0-0b20c39484b9",
  "id": "39jcbc5-053c-4873-a7c0-0b20c3948472",
  "url": "wss://sfu.api.ricoh/servers/1",
}

Signaling

For signaling phase, you open a WebSocket and send “connect”, “answer” and possibly “candidate” messages like broadcasting signaling phase. But there are some minor differences described below.

Send a Connect Message

Send connect message via WebSocket with role as downstream.

ws.send({
  "type": "connect",
  "role": "downstream",
  "channel_id": "39jcbc5-053c-4873-a7c0-0b20c3948472",
  "metadata": {
    "access_token": "b29jcbc5-053c-4873-a7c0-0b20c39484b9"
  }
});

Send an Answer Message

Once you receive an offer message, send an answer message back. Once a connection is made, set a streamed video so that you can start watching it.

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type == 'offer') {
    const config = msg.config;
    const certificate = await RTCPeerConnection.generateCertificate({ name: 'ECDSA', namedCurve: 'P-256' });
    config.certificates = [certificate];
    const pc = new RTCPeerConnection(config);
    pc.onicecandidate = (event) => {
      if (event.candidate) {
        const candidate = event.candidate.toJSON();
        candidate.type = 'candidate';
        ws.send(JSON.stringify(candidate));
      }
    };
    pc.onaddstream = (event) => {
      const elmVideo = document.getElementById('remoteVideo');
      elmVideo.src = window.URL.createObjectURL(event.stream);
    }
    await this.pc.setRemoteDescription(new RTCSessionDescription(msg));
    const sdp = await this._pc.createAnswer({});
    await this.pc.setLocalDescription(sdp);
    ws.send(JSON.stringify({ type: 'answer', sdp: pc.localDescription.sdp }));
  }
};

Samples

• Live Streaming Sample: With this sample, you can broadcast and watch a video. It has a back-end Web API server and a front-end WebRTC application. The server deals with authorization and manages rooms. The WebRTC application broadcasts or shows videos.

See Also

• Live Streaming API Reference
• RICOH Cloud SDK