Skip to main content

Secure Stream Recording API

danger

To access the Stream Recording API, you must obtain a dedicated API key by contacting our team. Please note that this is a separate authentication credential from the Eyeson One View API key. The One View API key is not compatible with the Stream Recording API and cannot be used interchangeably.

The Secure Stream Recording Service provides an API to setup a WebRTC video stream, create a recording, and deliver the recording data to a user controlled destination. Furthermore an authentication service is included which allows to create authentication tokens with different kind of permissions.

info

Although this API can be used directly it is recommended to use the Eyeson Streamrec JavaScript SDK.

Stream Setup​

Below the different steps to setup a stream without the help of the Streamrec-Javascript-SDK are listed. Followed by a more detailed hands-on on how to setup a client stream.

Get Auth-token​

The first step in the process for both client and supervisor interactions is authentication. You must obtain an authorization token using your master key. This auth-token establishes the identity and permissions for subsequent API requests. To retrieve an auth-token for the client, make an authenticated request using your master key as detailed in the examples below.

Create Resource​

Create a resource by making an API request to the appropriate endpoint based on your requirements. For client streaming, use the client API endpoints, and for supervision or administrative functions, use the supervisor endpoints. For detailed endpoint specifications and request parameters, refer to the client or supervisor reference documentation.

Setup RTM socket​

The created resource contains the address to the RTM socket. Take it and connect.

Start session with SDP​

Create a SDP from e.g. your webrtc browser stack and put it into the proper RTM-Message to start a client or supervisor session.

Handle RTM-Message​

Handle candidate and sdp_update messages and feed them into your webrtc stack.

Client Stream Setup​

Here the steps listed above are repeated with focusing on setting up a client stream.

Starting with a master-key, an auth-token with proper permissions for client streaming has to be generated:

token=$(curl -X POST https://streamrec.eyeson.com/auth_v2/client \
    -d '{"master_key":"<api-key>", "client_id":"client-0"}' -s | jq -r .auth_token)

Now this token can be used to create a new session:

curl -H "Authorization: Bearer $token" \
   'https://streamrec.eyeson.com/api/v2/session' \
   -d '{"client_id": "client-0"}'

which will return something of like this:

{
  "ice_credentials": {
    "iceServers": [
      {
        "urls": [
          "stun:nuts.eyeson.com:3478"
        ],
        "username": "",
        "credential": ""
      },
      {
        "urls": [
          "turn:nuts.eyeson.com:3478",
          "turn:nuts.eyeson.com:3478?transport=tcp",
          "turn:nuts.eyeson.com:443?transport=tcp"
        ],
        "username": "16832234234:************",
        "credential": "7uW0RP***********"
      }
    ]
  },
  "session_id": "98f06660-5434-4a9c-ae65-0291d5622624",
  "ws_endpoint": "wss://streamrec.eyeson.com/api/v2/io"
}

Note the ws_endpoint field, which contains the websockets endpoint for the realtime messaging interface.

Now, it is the time to prepare your webrtc peer connection and get the SDP offer. Then open a websockets channel to the ws_endpoint (don't forget to add the auth-token), and send a start_session containing the browsers SDP.

{
  "type": "session_start",
  "client_id": "client-0",
  "session_id": "98f06660-5434-4a9c-ae65-0291d5622624",
  "data": {
    "sdp": {
      "type": "offer",
      "sdp": "..."
    },
    "webhook_url": "https://yourserver.com/streamrec"
  }
}
info

Make sure, that the client_id matches the client_id supplied in the first auth request as it is embedded in the token.

Below the whole setup sequence for a client session is depicted as a sequence diagram: