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:

Method Description
GET /rooms Fetch information about rooms
GET /rooms/{id} Fetch information about specified room
POST /rooms Create a new room
DELETE /rooms/{id} Delete specified room
POST /rooms/{id}/tickets Create a ticket for specified room
WebSocket /servers/{id} Proceed signaling

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

Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.

Query Parameters

Field Description
state Optional. State of rooms
all(default): The endpoint will return all the rooms associated with your application.
onair: The endpoint will return only currently streaming rooms.

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

Header Description
Content-Type application/json; charset=utf-8

Body

Field Type Description
rooms array of objects(room) List of rooms

Object(Room)

Field Type Description
id string Room ID
up_count integer Number of uploading streams
The number is updated with a short delay.
down_count integer Number of downloading streams
The number is updated with a short delay.
created_at string Room creation date and time in UTC (ISO8601 format)

Status Codes

Code Reason
200 OK
401 Unauthorized. Invalid or expired Access Token.
500 Internal server error.

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

Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.

Path Parameters

Field Type Description
id string Room ID

Response

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

Headers

Header Description
Content-Type application/json; charset=utf-8

Body

Field Type Description
id string Room ID
up_count integer Number of uploading streams
The number is updated with a short delay.
down_count integer Number of downloading streams
The number is updated with a short delay.
created_at string Room creation date and time in UTC (ISO8601 format)

Status Codes

Code Reason
200 OK
401 Unauthorized. Invalid or expired Access Token.
404 Not found.
500 Internal server error.

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

Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.

Response

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

Headers

Header Description
Content-Type application/json; charset=utf-8

Body

Field Type Description
id string Room ID
up_count integer Number of uploading streams
The number is updated with a short delay.
down_count integer Number of downloading streams
The number is updated with a short delay.
created_at string Room creation date and time in UTC (ISO8601 format)

Status Codes

Code Reason
200 OK
401 Unauthorized. Invalid or expired Access Token.
429 Too many requests. Your room creation limit reached.
500 Internal server error.

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

Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.

Path Parameters

Field Type Description
id string Room ID

Response

No body is returned.

Status Codes

Code Reason
204 No Content.(success)
401 Unauthorized. The access token is invalid or expired.
404 Not found.
500 Internal server error.

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

Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.
Content-Type Required. application/json

Path Parameters

Field Type Description
id string Room ID

Body Parameters

Field Type Description
direction string Optional. The value MUST be either up or down
If no value is set, down is set as a default.

Response

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

Headers

Header Description
Content-Type application/json; charset=utf-8

Body

Field Type Description
id string Room ID
access_token string Ticket Token
direction string The value MUST be either up or down
url string Signaling url

Status Codes

Code Reason
200 OK
400 Bad request.
401 Unauthorized. The access token is invalid or expired.
404 Not found.
500 Internal server error.

WebSocket /servers/{id}

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

Message Subject Description
connect WebRTC client Ask for connection to a SFU server with an Access Token
offer SFU server Reply to a connect message and ask for an answer message
answer WebRTC client Reply to an offer message to specify Client’s SDP
candidate WebRTC client Describe more Client’s SDPs
ping SFU server Ask for a pong message to make sure client is still alive
pong WebRTC client Reply to a ping message

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

Field Type Description
type string Required. The value MUST be connect
role string Required. The value MUST be either upstream or downstream
channel_id string Required. Room ID
metadata.access_token string Required. Ticket Token
video boolean or object(Video) Optional. Describe a video or false for no video usage
audio boolean or object(Audio) Optional. Describe a audio or false for no audio usage

Object(Video)

Field Type Description
codec_type string The value MUST be VP8 or VP9 or H264
bit_rate integer Optional. Max video bit rate(kbps)
Set an integer value smaller than your bit rate limitation.
Setting too big value causes a RAPI-EXCEED-MAX-CHANNEL-CONNECTIONS error.

Object(Audio)

Field Type Description
codec_type string OPUS or PCMU

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

Field Type Description
type string Required. The value MUST be offer
sdp string Required. SFU server’s SDP
client_id string Required. The value which a SFU server uses
Note that it’s NOT related to Client Credentials Grant’s Client ID.

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

Field Type Description
type string Required. The value MUST be answer
sdp string Required. WebRTC client’s SDP

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

Field Type Description
type string Required. The value MUST be candidate
candidate string Required. WebRTC client’s SDP

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

Field Type Description
type string Required. The value MUST be ping

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

Field Type Description
type string Required. The value MUST be pong

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:

Reason Description
CONNECT-WAIT-TIMEOUT connect message is too late
CONNECT-WAIT-TIMEOUT-ERROR connect message is too late
CONNECTION-CREATED-WAIT-TIMEOUT-ERROR signaling did not complete in time
EXCEED-MAX-CONNECTIONS server full
FAILURE-JSON-DECODE invalid json
FAILURE-SDP-PARSE invalid sdp
FAILURE-MISSING-SDP invalid sdp
INTERNAL-ERROR internal error
INVALID-AUDIO-FORMAT not supported audio
INVALID-VIDEO-FORMAT not supported video
MISSING-ICE-SDP invalid sdp
MISSING-TYPE invalid json
NO-MEDIA invalid json
NOT-USE-CHANNEL-ID invalid json
PONG-TIMEOUT-ERROR pong message is too late
RAPI-EXCEED-MAX-CHANNEL-CONNECTIONS connection to the channel is full
RAPI-INTERNAL-ERROR internal error
RAPI-INVALID-TOKEN invalid token
RAPI-INVALID-PARAMETER invalid json
SIGNALING-INTERNAL-ERROR internal error
TRANSPORT-INTERNAL-ERROR internal error
UNKNOWN-CODEC-TYPE not supported codec
UNKNOWN-TYPE invalid json