Live Streaming API

Live Streaming API enables your WebRTC application to broadcast a video to multiple clients. To learn how to use the API, see Live Streaming API Developer Guide. This document describes the following endpoints which Live Streaming API supports:

Note: The default encoding is UTF-8.

GET /rooms

This API fetches and lists information about rooms created by your application.

Request

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

URL Structure

https://sfu.api.ricoh/v1/rooms

Headers

Query Parameters

Response

{
  "rooms":
  [
    {
      "id": "a39jcbc5-053c-4873-a7c0-0b20c3948472",
      "up_count": 1,
      "down_count": 10,
      "created_at": "2017-01-01T00:00:00Z"
    },
    {
      "id": "b22jabb4-caab-2448-bac0-aa20bc942d22",
      "up_count": 0,
      "down_count": 0,
      "created_at": "2017-01-02T00:00:00Z"
    }
  ]
}

Headers

Body

Object(Room)

Status Codes

GET /rooms/{id}

This API fetches information about a room which is created by your application.

Request

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

URL Structure

https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472

Headers

Path Parameters

Response

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

Headers

Body

Status Codes

POST /rooms

This API creates a new room.

Note: If you’ve already reached your room creation limit, the API request would fail unless you delete some rooms.

Request

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

URL Structure

https://sfu.api.ricoh/v1/rooms

Headers

Response

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

Headers

Body

Status Codes

DELETE /rooms/{id}

This API deletes a specified room.

Request

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

URL Structure

https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472

Headers

Path Parameters

Response

No body is returned.

Status Codes

POST /rooms/{id}/tickets

This API creates a ticket which contains necessary information to connect to a specified room. Broadcasting clients need upload tickets and viewing clients need download tickets. So, in addition to a room ID, a WebRTC client needs to specify up for upload ticket or down for download ticket with direction parameter.

Request

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"}'

URL Structure

https://sfu.api.ricoh/v1/rooms/a39jcbc5-053c-4873-a7c0-0b20c3948472/tickets

Headers

Path Parameters

Body Parameters

Response

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

Headers

Body

Status Codes

WebSocket /servers/{id}

This WebSocket API proceeds signaling with various messages. It supports the following messages:

Some messages are sent from SFU servers, others are from WebRTC clients. To complete signaling process, you need to send a connect message and a answer message, and possibly some candidate messages too. See Developer Guide to understand how to combine those messages to finish signaling. Note that you need to open a WebSocket first.

To learn SDP and SDP exchange, see RFC4566 and RFC3264.

Connect Message

A WebRTC client asks for connection to a SFU server with this message. Once the server receives this message, it verifies specified Access Token and replies with an offer message.

{
  "type": "connect",
  "role": "upstream",
  "channel_id": "a39jcbc5-053c-4873-a7c0-0b20c3948472",
  "metadata": {
    "access_token": "b29jcbc5-053c-4873-a7c0-0b20c39484b9"
  }
}

Fields

Object(Video)

Object(Audio)

Offer Message

After a connect message is accepted, a SFU server sends an offer message to ask for an answer message.

{
  "type": "offer",
  "sdp": "v=0 o=- 3336702409326257609 2 IN IP4 ...",
  "client_id": "cecae2d5-f70d-4387-b55b-40050f32daa2"
}

Fields

Answer Message

To reply to an offer message from a SFU server, a WebRTC client sends an answer message with its SDP specified.

{
  "type": "answer",
  "sdp": "v=0 o=- 3336702409326257609 2 IN IP4 ..."
}

Fields

Update Message

If multistream option is true, an update message will be sent when a new client connects or disconnects. A WebRTC client sends an update message with its Answer SDP specified.

{
  "type": "update",
  "sdp": "v=0 o=- 3336702409326257609 2 IN IP4 ..."
}

Fields

Candidate Message

In addition to answer message, a WebRTC client can describe more SDPs by sending candidate messages to a SFU server. A candidate message can contain only one SDP.

{
  "type": "candidate",
  "candidate": "candidate:3179889176 1 tcp 1518214911 192.168.1.10 0 typ host tcptype active generation 0"
}

Fields

Ping Message

A SFU server sends a ping message to a WebRTC client and wait for a pong message to see if the client is still alive.

{
  "type": "ping"
}

Fields

Pong Message

When a WebRTC client receives a ping message from a SFU server, it should reply with a pong message to notify that it’s still alive.

{
  "type": "pong"
}

Fields

Errors

While an error event is fired when a WebSocket error occurs, a close event is fired when a signaling error occurs. A close event contains reason field to describe the error. Live Streaming API supports the following signaling errors: