Web Socket Signaling Specification 1.0.0

Accepts the following message:

Accepts one of the following messages:

• #0BroadcasterResponse

  Type of message sent by the signaling server as a response to a command sent by the broadcaster client. It is used to confirm the acceptance of the command and provide additional data associated with the response.
  
  The content of the 'payload' field in the response message can vary depending on the type of command message that was sent by the broadcaster.

  Payload

  Expand all

  anyOf

  Can adhere to:

  Expand all

  object

  uid: PublishResponse

  The purpose of this message is to confirm that a previous publish message has been received and processed correctly by the API, and to provide additional information related to the publication.

  type

  string

  Allowed values:
  • "response"

  transId

  integer

  Refers to the transaction identifier (transId) of the publish command message that the response message is related to.

  data

  Expand all

  object

  uuid

  string

  A unique identifier for the stream.

  feedId

  string

  A unique identifier for the feed.

  publisherId

  string

  A unique identifier for the publisher.

  clusterId

  string

  The identifier of the cluster where the stream is published.

  streamId

  string

  The identifier of the stream that was published.

  sdp

  string

  The SDP message that describes the published stream.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: DescribeResponse

  The purpose of this message is to confirm that the previous describe command has been received and processed correctly and to provide detailed information about a specific data stream.

  type

  string

  Allowed values:
  • "response"

  transId

  integer

  Refers to the transaction identifier (transId) of the describe command message that the response message is related to

  data

  Expand all

  object

  sdp

  string

  The SDP configuration for the subscriber's stream.

  suscriberId

  string

  The unique ID of the subscriber.

  clusterId

  string

  The ID of the cluster where the stream is located.

  streamId

  string

  The ID of the stream being described

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - Publish Command Response Example

    {
      "type": "response",
      "transId": 0,
      "data": {
        "uuid": "feeds://77a944b6e75f40929bb6e3274389ae4a/308f7b5a-8429-4da4-b572-52aa3af5fcb2",
        "feedId": "308f7b5a-8429-4da4-b572-52aa3af5fcb2",
        "publisherId": "77a944b6e75f40929bb6e3274389ae4a",
        "clusterId": "do-sfo-legacy",
        "streamId": "udAcdT/lbxyfxso",
        "sdp": "sdp"
      }
    }
    

• #1Error

  It is used to reject a command sent by the other peer and pass some custom data associated to the error.

  Payload

  Expand all

  object

  type

  string

  Allowed values:
  • "error"

  transId

  integer

  Value from the command this response belongs to.

  data

  string

  Custom error data.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - Invalid command

    {
      "type": "error",
      "transId": 3,
      "data": "Internal Server Error"
    }
    

• #2Event

  Event messages are used when the sending side does not expect any kind of response back. Events can occur at any time.

  Payload

  Expand all

  anyOf

  Can adhere to:

  Expand all

  object

  uid: ViewerCountEvent

  Fires when the viewer counts changes.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "viewercount"

  data

  Expand all

  object

  viewerCount

  integer

  The current number of viewers.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: ActiveEvent

  Fires when the live stream is active, or has started broadcasting.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "active"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  sourceId

  string

  A unique identifier for the source of the live stream.

  tracks

  Expand all

  array<object>

  An array of tracks that are part of the live stream.

  trackId

  string

  A unique identifier for the track (either 'video' or 'audio').

  Allowed values:
  • "video"
  • "audio"

  mediaId

  string

  A unique identifier for the media associated with the track.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: InactiveEvent

  This event is sent when the stream stops broadcasting but is still available.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "inactive"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  sourceId

  string

  A unique identifier for the source of the live stream.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: StopEvent

  This event is sent when the stream is stopped.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "stopped"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  reason

  string

  The reason for the stop, which can be one of the following categories:
  

  • geoblocked: when a new publish for the stream updates the geoblocking information and geoblocks the viewer (rare).
  • stream-stopped: the published stream has been stopped and has been idle for a long time.
  • ice-timeout: ICE keepalives failed.
  • dtls-closed: received a DTLS close from the client (ie. via pc.stop()).
  • viewer-stopped: server is shutting down.
  • unview: graceful termination via unview command.
  • conn-closed: websocket connection closed.

  Allowed values:
  • "geoblocked"
  • "stream-stopped"
  • "ice-timeout"
  • "dtls-closed"
  • "viewer-stopped"
  • "unview"
  • "conn-closed"

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: LayerEvent

  When broadcasting with simulcast, this events fires when there is an update of the state of the layers in a stream.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "layers"

  data

  Expand all

  object

  medias

  Expand all

  object

  An object containing information about the media.

  <media_id>

  Expand all

  object

  An object containing information about a specific media stream.

  active

  Expand all

  array<object>

  id

  string

  The unique identifier for the active layer.

  simulcastIdx

  integer

  The simulcast index of the active layer.

  bitrate

  integer

  The bitrate of the active layer.

  layers

  Expand all

  array<object>

  encodingId

  string

  The encoding identifier of the layer.

  simulcastIdx

  integer

  The simulcast index of the layer.

  spatialLayerId

  integer

  The spatial layer identifier of the layer.

  temporalLayerId

  integer

  The temporal layer identifier of the layer.

  bitrate

  integer

  The bitrate of the layer.

  inactive

  Expand all

  array<object>

  An array of inactive layers for the media.

  id

  string

  The unique identifier for the inactive layer.

  layers

  Expand all

  array<object>

  An array of all layers for the media.

  encodingId

  string

  The encoding identifier of the layer.

  simulcastIdx

  integer

  The simulcast index of the layer.

  spatialLayerId

  integer

  The spatial layer identifier of the layer.

  temporalLayerId

  integer

  The temporal layer identifier of the layer.

  bitrate

  integer

  The bitrate of the layer.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: MigrateEvent

  This event is sent when the server is having problems, is shutting down or when viewers need to move for load balancing purposes.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "migrate"

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: VadEvent

  This event is sent when using multiplexed tracks for audio.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "vad"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  mediaId

  string

  A unique identifier of the source that is being projected.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - Viewer Count Event Example

    {
      "type": "event",
      "name": "viewercount",
      "data": {
        "viewerCount": 0
      }
    }
    

  • #2 Example - Active Event Example - Main stream active

    {
      "type": "event",
      "name": "active",
      "data": {
        "streamId": "udAcdT/lbxyfxso",
        "sourceId": "null",
        "tracks": [
          {
            "trackId": "audio",
            "media": "audio"
          },
          {
            "trackId": "video",
            "media": "video"
          }
        ]
      }
    }
    

  • #3 Example - Inactive Event Example - Main stream inactive

    {
      "type": "event",
      "name": "inactive",
      "data": {
        "streamId": "udAcdT/lbxyfxso",
        "sourceId": "null"
      }
    }
    

  • #4 Example - Layers Event Example

    {
      "type": "event",
      "name": "layers",
      "data": {
        "medias": {
          "0": {
            "active": [
              {
                "id": "1",
                "simulcastIdx": 1,
                "bitrate": 306776,
                "layers": []
              },
              {
                "id": "0",
                "simulcastIdx": 0,
                "bitrate": 105784,
                "layers": []
              }
            ],
            "inactive": [
              {
                "id": "2"
              }
            ],
            "layers": [
              {
                "encodingId": "1",
                "simulcastIdx": 1,
                "spatialLayerId": 255,
                "temporalLayerId": 255,
                "bitrate": 306776
              },
              {
                "encodingId": "0",
                "simulcastIdx": 0,
                "spatialLayerId": 255,
                "temporalLayerId": 255,
                "bitrate": 105784
              }
            ]
          }
        }
      }
    }
    

  • #5 Example - Stopped Event Example

    {
      "type": "event",
      "name": "stopped",
      "data": {
        "streamId": "xRp7nh/ams",
        "reason": "viewer-stopped"
      }
    }
    

Accepts the following message:

Accepts one of the following messages:

• #0ViewerResponse

  This message type is used by the server to respond to commands sent by the client viewer, and includes custom data associated with the response.
  
  For certain command types, including project, unproject, select, unview, mute, record, and unrecord, no data field is necessary for the response. The specific payload structure may vary depending on the type of command sent by the client viewer.

  Payload

  Expand all

  anyOf

  Can adhere to:

  Expand all

  object

  uid: ViewResponse

  The purpose of this message is to confirm the successful processing of a request to view a data stream and provide additional information related to the stream view.

  type

  string

  Allowed values:
  • "response"

  transId

  integer

  Refers to the transaction identifier (transId) of the view command message that the response message is related to.

  data

  Expand all

  object

  sdp

  string

  Session Description Protocol (SDP) for the stream.

  suscriberId

  string

  The ID of the subscriber who is watching the stream.

  clusterId

  string

  The ID of the cluster where the stream is being hosted.

  streamId

  string

  The ID of the stream that the client is subscribing to.

  streamViewId

  string

  The ID of the stream view for the subscribed stream.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: DescribeResponse

  The purpose of this message is to confirm that the previous describe command has been received and processed correctly and to provide detailed information about a specific data stream.

  type

  string

  Allowed values:
  • "response"

  transId

  integer

  Refers to the transaction identifier (transId) of the describe command message that the response message is related to

  data

  Expand all

  object

  sdp

  string

  The SDP configuration for the subscriber's stream.

  suscriberId

  string

  The unique ID of the subscriber.

  clusterId

  string

  The ID of the cluster where the stream is located.

  streamId

  string

  The ID of the stream being described

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - View Command Response Example

    {
      "type": "response",
      "transId": 0,
      "data": {
        "sdp": "sdp",
        "subscriberId": "2bebebf36c6143b8b9a7431a16432d09",
        "clusterId": "do-sfo-legacy",
        "streamId": "KQkaGG/l9i3sb96",
        "streamViewId": "e6cda950-2d0c-4e9d-b4e6-e3ba7896e1aa"
      }
    }
    

  • #2 Example - Describe Command Response Example

    {
      "type": "response",
      "transId": 1,
      "data": {
        "sdp": "sdp",
        "subscriberId": "ae0262e06ff6420db0c1b08da9887202",
        "clusterId": "do-sfo-legacy",
        "streamId": "udAcdT/lbxyfxso"
      }
    }
    

• #1Error

  It is used to reject a command sent by the other peer and pass some custom data associated to the error.

  Payload

  Expand all

  object

  type

  string

  Allowed values:
  • "error"

  transId

  integer

  Value from the command this response belongs to.

  data

  string

  Custom error data.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - Invalid command

    {
      "type": "error",
      "transId": 3,
      "data": "Internal Server Error"
    }
    

• #2Event

  Event messages are used when the sending side does not expect any kind of response back. Events can occur at any time.

  Payload

  Expand all

  anyOf

  Can adhere to:

  Expand all

  object

  uid: ViewerCountEvent

  Fires when the viewer counts changes.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "viewercount"

  data

  Expand all

  object

  viewerCount

  integer

  The current number of viewers.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: ActiveEvent

  Fires when the live stream is active, or has started broadcasting.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "active"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  sourceId

  string

  A unique identifier for the source of the live stream.

  tracks

  Expand all

  array<object>

  An array of tracks that are part of the live stream.

  trackId

  string

  A unique identifier for the track (either 'video' or 'audio').

  Allowed values:
  • "video"
  • "audio"

  mediaId

  string

  A unique identifier for the media associated with the track.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: InactiveEvent

  This event is sent when the stream stops broadcasting but is still available.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "inactive"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  sourceId

  string

  A unique identifier for the source of the live stream.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: StopEvent

  This event is sent when the stream is stopped.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "stopped"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  reason

  string

  The reason for the stop, which can be one of the following categories:
  

  • geoblocked: when a new publish for the stream updates the geoblocking information and geoblocks the viewer (rare).
  • stream-stopped: the published stream has been stopped and has been idle for a long time.
  • ice-timeout: ICE keepalives failed.
  • dtls-closed: received a DTLS close from the client (ie. via pc.stop()).
  • viewer-stopped: server is shutting down.
  • unview: graceful termination via unview command.
  • conn-closed: websocket connection closed.

  Allowed values:
  • "geoblocked"
  • "stream-stopped"
  • "ice-timeout"
  • "dtls-closed"
  • "viewer-stopped"
  • "unview"
  • "conn-closed"

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: LayerEvent

  When broadcasting with simulcast, this events fires when there is an update of the state of the layers in a stream.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "layers"

  data

  Expand all

  object

  medias

  Expand all

  object

  An object containing information about the media.

  <media_id>

  Expand all

  object

  An object containing information about a specific media stream.

  active

  Expand all

  array<object>

  id

  string

  The unique identifier for the active layer.

  simulcastIdx

  integer

  The simulcast index of the active layer.

  bitrate

  integer

  The bitrate of the active layer.

  layers

  Expand all

  array<object>

  encodingId

  string

  The encoding identifier of the layer.

  simulcastIdx

  integer

  The simulcast index of the layer.

  spatialLayerId

  integer

  The spatial layer identifier of the layer.

  temporalLayerId

  integer

  The temporal layer identifier of the layer.

  bitrate

  integer

  The bitrate of the layer.

  inactive

  Expand all

  array<object>

  An array of inactive layers for the media.

  id

  string

  The unique identifier for the inactive layer.

  layers

  Expand all

  array<object>

  An array of all layers for the media.

  encodingId

  string

  The encoding identifier of the layer.

  simulcastIdx

  integer

  The simulcast index of the layer.

  spatialLayerId

  integer

  The spatial layer identifier of the layer.

  temporalLayerId

  integer

  The temporal layer identifier of the layer.

  bitrate

  integer

  The bitrate of the layer.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: MigrateEvent

  This event is sent when the server is having problems, is shutting down or when viewers need to move for load balancing purposes.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "migrate"

  Additional properties are allowed.

  Or to:

  Expand all

  object

  uid: VadEvent

  This event is sent when using multiplexed tracks for audio.

  type

  string

  Allowed values:
  • "event"

  name

  string

  Event name

  Allowed values:
  • "vad"

  data

  Expand all

  object

  streamId

  string

  A unique identifier for the live stream.

  mediaId

  string

  A unique identifier of the source that is being projected.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  • #1 Example - Viewer Count Event Example

    {
      "type": "event",
      "name": "viewercount",
      "data": {
        "viewerCount": 0
      }
    }
    

  • #2 Example - Active Event Example - Main stream active

    {
      "type": "event",
      "name": "active",
      "data": {
        "streamId": "udAcdT/lbxyfxso",
        "sourceId": "null",
        "tracks": [
          {
            "trackId": "audio",
            "media": "audio"
          },
          {
            "trackId": "video",
            "media": "video"
          }
        ]
      }
    }
    

  • #3 Example - Inactive Event Example - Main stream inactive

    {
      "type": "event",
      "name": "inactive",
      "data": {
        "streamId": "udAcdT/lbxyfxso",
        "sourceId": "null"
      }
    }
    

  • #4 Example - Layers Event Example

    {
      "type": "event",
      "name": "layers",
      "data": {
        "medias": {
          "0": {
            "active": [
              {
                "id": "1",
                "simulcastIdx": 1,
                "bitrate": 306776,
                "layers": []
              },
              {
                "id": "0",
                "simulcastIdx": 0,
                "bitrate": 105784,
                "layers": []
              }
            ],
            "inactive": [
              {
                "id": "2"
              }
            ],
            "layers": [
              {
                "encodingId": "1",
                "simulcastIdx": 1,
                "spatialLayerId": 255,
                "temporalLayerId": 255,
                "bitrate": 306776
              },
              {
                "encodingId": "0",
                "simulcastIdx": 0,
                "spatialLayerId": 255,
                "temporalLayerId": 255,
                "bitrate": 105784
              }
            ]
          }
        }
      }
    }
    

  • #5 Example - Stopped Event Example

    {
      "type": "event",
      "name": "stopped",
      "data": {
        "streamId": "xRp7nh/ams",
        "reason": "viewer-stopped"
      }
    }