OpenVidu Server RPC protocol
OpenVidu Server offers a WebSocket endpoint at path /openvidu
where clients must connect to ...
- Call methods: clients are able to directly call OpenVidu Server methods. Some of them will only be available if the user has the proper role inside the session.
- Receive server events: OpenVidu Server will send session events to clients connected to that specific session.
OpenVidu hides all this implementation with OpenVidu Browser JavaScript library, that can be used in all officially supported platforms. But of course it would be possible to develop an SDK implementing this WebSocket based RPC protocol using any desired language or technology.
For example, openvidu-android tutorial is a native Android app, so it cannot make use of OpenVidu Browser JavaScript library. The solution to this problem: the application internally implements the OpenVidu Server RPC protocol. But to do so, it is necessary to be very clear about what operations-responses and what server events are defined in OpenVidu Server.
Client-Server methods 🔗
All operations send by the client side must be a JSON object with these properties
jsonrpc
: version of JSON-RPC protocol. Always"2.0"
method
: the name of the methodparams
: a JSON object with the method parametersid
: an integer to identify this operation call. Must be unique with respect to any other operation call
All responses from OpenVidu Server to each one of these operations are a JSON object with these properties
jsonrpc
: version of JSON-RPC protocol. Always"2.0"
id
: an integer matching theid
property of the operation call that generated this response. This allows pairing the operation call sent from the client with its respective server responseresult
: a JSON object with the operation result. Its fields are obviously dependent on the method that generated this response. Not included iferror
property is definederror
: a JSON object with information about an error triggered during the operation call. Not included ifresult
property is defined. This JSON object has 2 properties:code
: a number identifying the type of errormessage
: a string with a detailed description about the error
Complete list of operations:
- ping
- joinRoom
- publishVideo
- receiveVideoFrom
- onIceCandidate
- unpublishVideo
- unsubscribeFromVideo
- leaveRoom
- sendMessage
- forceUnpublish
- forceDisconnect
- applyFilter
- removeFilter
- execFilterMethod
- addFilterEventListener
- removeFilterEventListener
- reconnectStream
ping 🔗
Ping message for the ping-pong mechanism. This is necessary to make OpenVidu Server aware of a client connection, and to act accordingly if no ping is received in a certain interval time. params
property is only necessary in the first call to this method.
Method sent by client
{
"jsonrpc": "2.0",
"method": "ping",
"params": {
"interval": 5000 // Not necessary after first call
},
"id": 0
}
Response from OpenVidu Server
{
"id": 0,
"result":{
"value":"pong"
},
"jsonrpc":"2.0"
}
joinRoom 🔗
Join a client to an already initialized session. The equivalent method in OpenVidu Browser is Session#connect
Method sent by client
{
"jsonrpc": "2.0",
"method": "joinRoom",
"params": {
"token": "wss://localhost:4443?sessionId=TestSession&token=rpjyfwrwckltdtk3&role=PUBLISHER&version=2.11.0",
"session": "TestSession",
"platform": "Chrome 76.0.3809.132 on Linux 64-bit",
"metadata": "{clientData: TestClient}",
"secret": "",
"recorder": false
},
"id": 1
}
Response from OpenVidu Server
{
"id": 1,
"result": {
"id": "y4gsjcy37m1rcjkx",
"createdAt": 1568198320797,
"metadata": "{clientData: TestClient}",
"value": [
{
"id": "ydqsx1r7jp3zmduf",
"createdAt": 1568197954222,
"metadata": "{clientData: OtherClient}",
"streams": [
{
"id": "ydqsx1r7jp3zmduf_CAMERA_MLMZG",
"createdAt": 1568197956221,
"hasAudio": true,
"hasVideo": true,
"videoActive": true,
"audioActive": true,
"typeOfVideo": "CAMERA",
"frameRate": 30,
"videoDimensions": "{\"width\":640,\"height\":480}",
"filter": {}
}
]
}
],
"sessionId": "nqo83ml4kc2kgaoe65311n7in0"
},
"jsonrpc": "2.0"
}
publishVideo 🔗
Start publishing a stream to the session. The equivalent method in OpenVidu Browser is Session#publish
Method sent by client
{
"jsonrpc": "2.0",
"method": "publishVideo",
"params": {
"sdpOffer": "v=0 ... ssrc:1665235233 label:f320e350-b667-4765-87da-4ee4f595b9fe\r\n",
"doLoopback": false,
"hasAudio": true,
"hasVideo": true,
"audioActive": true,
"videoActive": true,
"typeOfVideo": "CAMERA",
"frameRate": 30,
"videoDimensions": "{\"width\":640,\"height\":480}"
},
"id": 2
}
Response from OpenVidu Server
{
"id": 2,
"result": {
"sdpAnswer": "v=0 ... :EA:63:12:29:12:D6:4B:9A:63:F1:AB:D4:CC\r\n",
"id": "nflyoomouisnvvas_CAMERA_DYVFP",
"createdAt": 1568193997244,
"sessionId": "lu7h4for17svik11aum6qqi9v1"
},
"jsonrpc": "2.0"
}
receiveVideoFrom 🔗
Subscribe to a stream being published to the session. The equivalent method in OpenVidu Browser is Session#subscribe
Method sent by client
{
"jsonrpc": "2.0",
"method": "receiveVideoFrom",
"params": {
"sender": "ydqsx1r7jp3zmduf_CAMERA_MLMZG",
"sdpOffer": "v=0 ... a=rtpmap:123 ulpfec/90000\r\n"
},
"id": 3
}
Response from OpenVidu Server
{
"id": 3,
"result": {
"sdpAnswer": "v=0 ... :FD:66:54:68:B4:47:25:EF:B6:04:74:AF:7B:08:66:09:F2:7C\r\n",
"sessionId": "ajcecubc3sdcki0f6fnsefrr0t"
},
"jsonrpc": "2.0"
}
onIceCandidate 🔗
Send and ICE candidate to the server.
Method sent by client
{
"jsonrpc": "2.0",
"method": "onIceCandidate",
"params": {
"endpointName": "nflyoomouisnvvas",
"candidate": "candidate:3885250869 1 udp 2122260223 172.17.0.1 53467 typ host generation 0 ufrag 3KLI network-id 1 network-cost 50",
"sdpMid": "0",
"sdpMLineIndex": 0
},
"id": 4
}
Response from OpenVidu Server
{
"id": 4,
"result": {
"sessionId": "lu7h4for17svik11aum6qqi9v1"
},
"jsonrpc": "2.0"
}
unpublishVideo 🔗
Stop publishing a stream to the session. The equivalent method in OpenVidu Browser is Session#unpublish
Method sent by client
{
"jsonrpc": "2.0",
"method": "unpublishVideo",
"params": {},
"id": 5
}
Response from OpenVidu Server
{
"id": 5,
"result": {
"sessionId": "822vl7sqllncvbivsoqt8q0nes"
},
"jsonrpc": "2.0"
}
unsubscribeFromVideo 🔗
Stop the subscription from a stream to which the user is currently subscribed. The equivalent method in OpenVidu Browser is Session#unsubscribe
Method sent by client
{
"jsonrpc": "2.0",
"method": "unsubscribeFromVideo",
"params": {
"sender": "ydqsx1r7jp3zmduf"
},
"id": 6
}
Response from OpenVidu Server
{
"id": 6,
"result": {
"sessionId": "ajcecubc3sdcki0f6fnsefrr0t"
},
"jsonrpc": "2.0"
}
leaveRoom 🔗
Disconnect a client from a session. The equivalent method in OpenVidu Browser is Session#disconnect
Method sent by client
{
"jsonrpc": "2.0",
"method": "leaveRoom",
"params": {},
"id": 7
}
Response from OpenVidu Server
{
"id": 7,
"result": {
"sessionId": "lu7h4for17svik11aum6qqi9v1"
},
"jsonrpc": "2.0"
}
sendMessage 🔗
Send a signal to the session. The equivalent method in OpenVidu Browser is Session#signal
Method sent by client
{
"jsonrpc": "2.0",
"method": "sendMessage",
"params": {
"message": "{\"to\":[],\"data\":\"Test message\",\"type\":\"signal:chat\"}"
},
"id": 8
}
Response from OpenVidu Server
{
"id": 8,
"result": {
"sessionId": "nqo83ml4kc2kgaoe65311n7in0"
},
"jsonrpc": "2.0"
}
forceUnpublish 🔗
Force another client to unpublish its stream from the session. Only possible for clients with role MODERATOR inside the session. The equivalent method in OpenVidu Browser is Session#forceUnpublish
Method sent by client
{
"jsonrpc": "2.0",
"method": "forceUnpublish",
"params": {
"streamId": "ydqsx1r7jp3zmduf_CAMERA_MLMZG"
},
"id": 9
}
Response from OpenVidu Server
{
"id": 9,
"result": {
"sessionId": "rh75l2dg35v9pqsrsbi5n09p72"
},
"jsonrpc": "2.0"
}
forceDisconnect 🔗
Force another client to disconnect from the session. Only possible for clients with role MODERATOR inside the session. The equivalent method in OpenVidu Browser is Session#forceDisconnect
Method sent by client
{
"jsonrpc": "2.0",
"method": "forceDisconnect",
"params": {
"connectionId": "4v8cftv2zylhkjvd"
},
"id": 10
}
Response from OpenVidu Server
{
"id": 10,
"result": {
"sessionId": "6f0djrngic4ed49ov0poesp3f4"
},
"jsonrpc": "2.0"
}
applyFilter 🔗
Apply a filter to a published stream. The equivalent method in OpenVidu Browser is Stream#applyFilter
Method sent by client
{
"jsonrpc": "2.0",
"method": "applyFilter",
"params": {
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"type": "GStreamerFilter",
"options": "{\"command\":\"videobalance saturation=0.0\"}"
},
"id": 11
}
Response from OpenVidu Server
{
"id": 11,
"result": {
"sessionId": "iege6n3t7c3oj8ilj91hgaktp6"
},
"jsonrpc": "2.0"
}
removeFilter 🔗
Removed an applied filter from a stream. The equivalent method in OpenVidu Browser is Stream#removeFilter
Method sent by client
{
"jsonrpc": "2.0",
"method": "removeFilter",
"params": {
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF"
},
"id": 12
}
Response from OpenVidu Server
{
"id": 12,
"result": {
"sessionId": "iege6n3t7c3oj8ilj91hgaktp6"
},
"jsonrpc": "2.0"
}
execFilterMethod 🔗
Execute a method offered by an applied filter. The equivalent method in OpenVidu Browser is Filter#execMethod
Method sent by client
{
"jsonrpc": "2.0",
"method": "execFilterMethod",
"params": {
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"method": "setElementProperty",
"params": "{\"propertyName\":\"saturation\",\"propertyValue\":\"1.0\"}"
},
"id": 13
}
Response from OpenVidu Server
{
"id": 12,
"result": {
"sessionId": "iege6n3t7c3oj8ilj91hgaktp6"
},
"jsonrpc": "2.0"
}
addFilterEventListener 🔗
Add a listener to an applied filter. The equivalent method in OpenVidu Browser is Filter#addEventListener
Method sent by client
{
"jsonrpc": "2.0",
"method": "addFilterEventListener",
"params": {
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"eventType": "CodeFound"
},
"id": 14
}
Response from OpenVidu Server
{
"id": 14,
"result": {
"sessionId": "iege6n3t7c3oj8ilj91hgaktp6"
},
"jsonrpc": "2.0"
}
removeFilterEventListener 🔗
Remove a listener from an applied filter. The equivalent method in OpenVidu Browser is Filter#removeEventListener
Method sent by client
{
"jsonrpc": "2.0",
"method": "removeFilterEventListener",
"params": {
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"eventType": "CodeFound"
},
"id": 15
}
Response from OpenVidu Server
{
"id": 15,
"result": {
"sessionId": "iege6n3t7c3oj8ilj91hgaktp6"
},
"jsonrpc": "2.0"
}
reconnectStream (>= 2.12.0) 🔗
Silently re-negotiates an already established stream. This is useful for reconnecting a frozen stream, which may happen when a client loses and recovers its network connection with OpenVidu Server, but the media plane is broken. This method will recreate a new RTC peer connection in a silent manner (without triggering any events in the clients) using the properties of the previous one. Required params are the stream identifier to reconnect and the new SDP offer generated by the client (which must have created a new RTC peer connection object). The answer will bring the new SDP answer to pass it to the newly created client's peer connection.
Method sent by client
{
"jsonrpc": "2.0",
"method": "reconnectStream",
"params": {
"stream": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"sdpOffer": "v=0 ... a=rtpmap:123 ulpfec/90000\r\n"
},
"id": 16
}
Response from OpenVidu Server
{
"id": 16,
"result": {
"sdpAnswer": "v=0 ... :FD:66:54:68:B4:47:25:EF:B6:04:74:AF:7B:08:66:09:F2:7C\r\n",
"sessionId": "ajcecubc3sdcki0f6fnsefrr0t"
},
"jsonrpc": "2.0"
}
Server events 🔗
All events generated in OpenVidu Server and sent to clients are a JSON object with 3 properties:
jsonrpc
: version of JSON-RPC protocol. Always"2.0"
method
: the name of the eventparams
: a JSON object with the event properties
Complete list of server events:
- iceCandidate
- sendMessage
- participantJoined
- participantLeft
- participantEvicted
- participantPublished
- participantUnpublished
- streamPropertyChanged
- recordingStarted
- recordingStopped
- filterEventDispatched
iceCandidate 🔗
OpenVidu Server has generated an ICE candidate for certain stream. Client must process it on its proper WebRTC peer connection object.
{
"method": "iceCandidate",
"params": {
"senderConnectionId": "nflyoomouisnvvas",
"endpointName": "nflyoomouisnvvas_CAMERA_DYVFP",
"sdpMLineIndex": 0,
"sdpMid": "0",
"candidate": "candidate:1 1 UDP 2013266431 fe80::f816:3eff:fe48:cb5b 25037 typ host"
},
"jsonrpc": "2.0"
}
sendMessage 🔗
A message broadcasted to the session (can be generated by other client or by the application server).
{
"method": "sendMessage",
"params": {
"data": "Test message",
"from": "y4gsjcy37m1rcjkx",
"type": "signal:chat"
},
"jsonrpc": "2.0"
}
participantJoined 🔗
Some client has connected to the session.
{
"method": "participantJoined",
"params": {
"id": "tvwerf2quejh2vio",
"createdAt": 1568199474610,
"metadata": "{clientData: TestClient}"
},
"jsonrpc": "2.0"
}
participantLeft 🔗
Some client has disconnected from the session.
{
"method": "participantLeft",
"params": {
"connectionId": "4v8cftv2zylhkjvd",
"reason": "forceDisconnectByUser"
},
"jsonrpc": "2.0"
}
participantEvicted 🔗
Some client has been forcibly disconnected from the session.
{
"method": "participantEvicted",
"params": {
"connectionId": "4v8cftv2zylhkjvd",
"reason": "forceDisconnectByUser"
},
"jsonrpc": "2.0"
}
participantPublished 🔗
Some client has published a stream to the session.
{
"method": "participantPublished",
"params": {
"id": "qpdg7gcw0vf5wb97",
"streams": [
{
"id": "qpdg7gcw0vf5wb97_CAMERA_EDGRS",
"createdAt": 1568199288275,
"hasAudio": true,
"hasVideo": true,
"audioActive": true,
"videoActive": true,
"typeOfVideo": "CAMERA",
"frameRate": 30,
"videoDimensions": "{\"width\":640,\"height\":480}",
"filter": {}
}
]
},
"jsonrpc": "2.0"
}
participantUnpublished 🔗
Some client has unpublished a stream from the session.
{
"method": "participantUnpublished",
"params": {
"connectionId": "qpdg7gcw0vf5wb97",
"reason": "unpublish"
},
"jsonrpc": "2.0"
}
streamPropertyChanged 🔗
Some client has changed a property of a stream. See StreamPropertyChangedEvent
{
"method": "streamPropertyChanged",
"params": {
"connectionId": "lnek7tftxofol1ie",
"streamId": "lnek7tftxofol1ie_CAMERA_JVBHX",
"property": "videoActive",
"newValue": "false",
"reason": "publishVideo"
},
"jsonrpc": "2.0"
}
recordingStarted 🔗
The recording of a session has started.
{
"method": "recordingStarted",
"params": {
"id": "lnek7tftxofol1ie",
"name": "MyLastRecording"
},
"jsonrpc": "2.0"
}
recordingStopped 🔗
The recording of a session has stopped.
{
"method": "recordingStopped",
"params": {
"id": "lnek7tftxofol1ie",
"name": "MyLastRecording",
"reason": "recordingStoppedByServer"
},
"jsonrpc": "2.0"
}
filterEventDispatched 🔗
A filter applied to a stream by this client has dispatched an event. This can only happen if the client has previously called methods applyFilter
and addFilterEventListener
{
"method": "filterEventDispatched",
"params": {
"connectionId": "wzvwjiise4lfbhvp",
"streamId": "wzvwjiise4lfbhvp_CAMERA_MCLFF",
"filterType": "ZBarFilter",
"eventType": "CodeFound",
"data": "{timestampMillis=1568204832456, codeType=EAN-13, source=3972c92d-a489-47ae-92f8-13ea6d0e72eb_kurento.MediaPipeline/fdb2f5-19a4-47c2-a27a-705fb277_kurento.ZBarFilter, type=CodeFound, value=0092000001927}"
},
"jsonrpc": "2.0"
}