messages.md

Protocol Documentation

Table of Contents

• signalling_messages.proto

  • answer
  • base_message
  • config
  • dataChannelRequest
  • disconnectPlayer
  • endpointId
  • endpointIdConfirm
  • iceCandidate
  • iceCandidateData
  • identify
  • layerPreference
  • listStreamers
  • offer
  • peerConnectionOptions
  • peerDataChannels
  • peerDataChannelsReady
  • ping
  • playerConnected
  • playerCount
  • playerDisconnected
  • pong
  • startStreaming
  • stats
  • stopStreaming
  • streamerDataChannels
  • streamerDisconnected
  • streamerIdChanged
  • streamerList
  • subscribe
  • unsubscribe

• Scalar Value Types

Top

signalling_messages.proto

answer

This is a response to an offer message. It contains the answer SDP. Part of the normal subscribe flow. A peer will subscribe to a streamer and depending on whether offer_to_receive is set, one peer will make an offer and the other should answer.

Field	Type	Label	Description
type	string		Should always be 'answer'
sdp	string		The WebRTC SDP payload
playerId	string	optional	If being sent to a player this should be set to a valid player ID.
minBitrateBps	int32	optional	Specifies the minimum bitrate requested for streams.
maxBitrateBps	int32	optional	Specifies the maximum bitrate requested for streams.

base_message

This is just a helper message type that allows us to use a "base interface" in code to describe that all messages should at least have a 'type field'.

Field	Type	Label	Description
type	string		The type of the message.

config

A config message is sent to each connecting peer when it connects to describe to them the setup of the signalling server they're connecting to.

Field	Type	Label	Description
type	string		Should always be 'config'
peerConnectionOptions	peerConnectionOptions		The user defined peer connnection options
protocolVersion	string	optional	The signalling protocol version the signalling server is using

dataChannelRequest

Message is forwarded to a connected SFU. Tells the SFU that the player requests data channels to the streamer.

Field	Type	Label	Description
type	string		Should always be 'dataChannelRequest'

disconnectPlayer

Message is consumed by the Signalling Server. Requests that the signalling server disconnect the given player matching the player ID.

Field	Type	Label	Description
type	string		Should always be 'disconnectPlayer'
playerId	string		The ID of the player to disconnect.
reason	string	optional	An optional reason string to send to the player.

endpointId

Message is consumed by the Signalling Server. Specifies an id for the streamer. This is used to uniquely identify multiple streamers connected to the same Signalling Server. Note: to preserve backward compatibility when Streamer IDs were optional, when a Streamer first connects it is assigned a temporary ID which allows use of older Streamers if needed. Note: Streamer IDs must be unique and so if the ID provided here clashes with an existing ID, the ID may be altered slightly (usually just an appended number). The streamer will be sent an endpointIdConfirm message to notify it of it's final ID.

Field	Type	Label	Description
type	string		Should always be 'endpointId'
id	string		The requested ID of the streamer.
protocolVersion	string	optional	The signalling protocol version the streamer is using

endpointIdConfirm

A response to endpointId that will notify the streamer of its final ID given. Since streamer IDs must be unique the requested ID may not be available and may need to be altered.

Field	Type	Label	Description
type	string		Should always be 'endpointIdConfirm'
committedId	string		The final ID of the streamer.

iceCandidate

A single ICE candidate entry from WebRTC. Notifies a peer of a possible connection option to another peer.

Field	Type	Label	Description
type	string		Should always be 'iceCandidate'
candidate	iceCandidateData		The ICE candidate data from WebRTC
playerId	string	optional	If being sent to a player this should be a valid player ID.

iceCandidateData

A submessage that contains data from a WebRTC ICE candidate.

Field	Type	Label	Description
candidate	string
sdpMid	string
sdpMLineIndex	int32
usernameFragment	string	optional

identify

A request for a new streamer to give itself an ID. The flow for these messages should be connect->identify->endpointId->endpointIdConfirm

Field	Type	Label	Description
type	string		Should always be 'identify'

layerPreference

Message is forwarded to a connected SFU. Sends a preferred layer index to a connected SFU for a specified player. Useful for switching between SFU quality layers to force a certain resolution/quality option either as part of UX or testing.

Field	Type	Label	Description
type	string		Should always be 'layerPreference'
spatialLayer	int32		The requested spatial layer
temporalLayer	int32		The requested temporal layer
playerId	string		The player ID this preference refers to

listStreamers

A request to the signalling server to send the player a list of available streamers it could possibly subscribe to.

Field	Type	Label	Description
type	string		Should always be 'listStreamers'

offer

An offer message is an offer of a WebRTC stream. When a player subscribes to a streamer the streamer will offer the stream to the new player.

Field	Type	Label	Description
type	string		Should always be 'offer'
sdp	string		The SDP payload from WebRTC
playerId	string	optional	If being sent to a player this should be a valid player ID
sfu	bool	optional	Indiates that this offer is coming from an SFU.

peerConnectionOptions

This is a user defined structure that is sent as part of the config message. Left empty here because everything is optional.

peerDataChannels

Message is forwarded to a player. Sends information to the player about what data channels to use for sending/receiving with the streamer.

Field	Type	Label	Description
type	string		Should always be 'peerDataChannels'
playerId	string		The player ID this message refers to.
sendStreamId	int32		The channel ID to use for sending data.
recvStreamId	int32		The channel ID to use for receiving data.

peerDataChannelsReady

Message is forwarded to a connected SFU. Tells the SFU that the player is ready for data channels to be negotiated.

Field	Type	Label	Description
type	string		Should always be 'peerDataChannelsReady'

ping

A keepalive ping message used to test that the connection is still open.

Field	Type	Label	Description
type	string		Should always be 'ping'
time	int32		The current time

playerConnected

A message sent to a streamer to notify it that a player has just subscribed to it.

Field	Type	Label	Description
type	string		Should always be 'playerConnected'
dataChannel	bool		True if the player should be given a datachannel for stream control purposes.
sfu	bool		True if the player connected is an SFU
playerId	string		The ID of the player that connected.

playerCount

DEPRECATED Message is sent to players to indicate how many currently connected players there are on this signalling server. (Note: This is mostly old behaviour and is not influenced by multi streamers or who is subscribed to what streamer. It just reports the number of players it knows about.)

Field	Type	Label	Description
type	string		Should always be 'playerCount'
count	int32		The number of players connected.

playerDisconnected

Message is used to notify a streamer that a player has unsubscribed/disconnected from the stream.

Field	Type	Label	Description
type	string		Should always be 'playerDisconnected'
playerId	string		The ID of the player that disconnected.

pong

Message is a reply to ping from a streamer. Replies with the time from the ping message.

Field	Type	Label	Description
type	string		Should always be 'pong'
time	int32		The echoed time from the ping message

startStreaming

Sent by the SFU to indicate that it is now streaming.

Field	Type	Label	Description
type	string		Should always be 'startStreaming'

stats

DEPRECATED Message is consumed by the signalling server. Will print out the provided stats data on the console.

Field	Type	Label	Description
type	string		Should always be 'stats'
data	string		The stats data to echo.

stopStreaming

Sent by the SFU to indicate that it is now no longer streaming.

Field	Type	Label	Description
type	string		Should always be 'stopStreaming'

streamerDataChannels

Message is forwarded to the streamer. Sends a request to the streamer to open up data channels for a given player.

Field	Type	Label	Description
type	string		Should always be 'streamerDataChannels'
sfuId	string		The SFU the player is connected to
sendStreamId	int32		The channel ID to use for sending data.
recvStreamId	int32		The channel ID to use for receiving data.

streamerDisconnected

Message is used to notify players when a Streamer disconnects from the signalling server.

Field	Type	Label	Description
type	string		Should always be 'streamerDisconnected'

streamerIdChanged

Message is used to communicate to players that the streamer it is currently subscribed to is changing its ID. This allows players to keep track of it's currently subscribed streamer and allow auto reconnects to the correct streamer. This happens if a streamer sends an endpointID message after it already has an ID assigned. (Can happen if it is late to respond to the identify message and is auto assigned a legacy ID.)

Field	Type	Label	Description
type	string		Should always be 'streamerIdChanged'
newID	string		The new ID of the streamer.

streamerList

Message is a reply to listStreamers from a player. Replies with a list of currently active streamers connected to this server.

Field	Type	Label	Description
type	string		Should always be 'streamerList'
ids	string	repeated	A list of streamer IDs active on the server.

subscribe

Message is consumed by the signalling server. Tells the signalling server that the player requests to subscribe to the given stream.

Field	Type	Label	Description
type	string		Should always be 'subscribe'
streamerId	string		The ID of the streamer the player wishes to subscribe to.

unsubscribe

Message is consumed by the signalling server. Tells the signalling server that the player wishes to unsubscribe from the current stream. The player must have previously used the subscribe message for this to have any effect.

Field	Type	Label	Description
type	string		Should always be 'unsubscribe'

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)