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.

Table of Contents:



Client-Server methods 🔗


All operations send by the client side must be a JSON object with these properties

  • id: an integer to identify each operation call. Must be unique with respect to any other RPC operation call for a particular WebSocket connection
  • jsonrpc: version of JSON-RPC protocol. Always "2.0"
  • method: the name of the method
  • params: a JSON object with the method parameters


All responses from OpenVidu Server to each one of these operations are a JSON object with these properties

  • id: an integer matching the id property of the operation call that generated this response. This allows pairing the operation call sent from the client with its respective server response
  • jsonrpc: version of JSON-RPC protocol. Always "2.0"
  • result: a JSON object with the operation result. Its fields are obviously dependent on the method that generated this response. Not included if error property is defined
  • error: a JSON object with information about an error triggered during the operation call. Not included if result property is defined. This JSON object has 2 properties:
    • code: a number identifying the type of error
    • message: a string with a detailed description about the error



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

{
    "id": 0,
    "jsonrpc": "2.0",
    "method": "ping",
    "params": {
        "interval": 5000 // Not necessary after first call
    }
}

Response from OpenVidu Server

{
   "id": 0,
   "jsonrpc":"2.0",
   "result":{
      "value":"pong"
   }
}

joinRoom 🔗

Join a client to an already initialized session. The equivalent method in OpenVidu Browser is Session#connect

Method sent by client

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "joinRoom",
    "params": {
        "metadata": "TestClient",
        "platform": "Chrome 99.0.4844.51 on Linux 64-bit",
        "recorder": false,
        "sdkVersion": "2.21.0",
        "secret": "",
        "session": "TestSession",
        "token": "wss://sample-ip.com?sessionId=TestSession&token=tok_V9JemXQw9n6T0LY2"
    }
}

Response from OpenVidu Server

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "coturnIp": "123.45.67.89",
        "coturnPort": 3478,
        "createdAt": 1646820441354,
        "finalUserId": "97061F3F73313C3E",
        "id": "con_BbmrLNQdb1",
        "mediaServer": "mediasoup",
        "metadata": "TestClient",
        "record": true,
        "role": "PUBLISHER",
        "session": "TestSession",
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80",
        "turnCredential": "86rwpk",
        "turnUsername": "MQLSZR",
        "value": [
            {
                "createdAt": 1646820435398,
                "id": "con_Ud1Rk3GbYu",
                "metadata": "TestClient",
                "streams": [
                    {
                        "audioActive": true,
                        "createdAt": 1646820436419,
                        "filter": {},
                        "frameRate": 30,
                        "hasAudio": true,
                        "hasVideo": true,
                        "id": "str_CAM_KDeZ_con_Ud1Rk3GbYu",
                        "typeOfVideo": "CAMERA",
                        "videoActive": true,
                        "videoDimensions": "{\"width\":640,\"height\":480}"
                    }
                ]
            }
        ],
        "version": "2.21.0",
        "videoSimulcast": true
    }
}

publishVideo 🔗

Start publishing a stream to the session. The equivalent method in OpenVidu Browser is Session#publish

Method sent by client

{
    "id": 2,
    "jsonrpc": "2.0",
    "method": "publishVideo",
    "params": {
        "audioActive": true,
        "doLoopback": false,
        "frameRate": 30,
        "hasAudio": true,
        "hasVideo": true,
        "sdpOffer": "v=0\r\no=- 9136980301272336337 2 IN IP4 [...] 0c97ae838dfa\r\n",
        "typeOfVideo": "CAMERA",
        "videoActive": true,
        "videoDimensions": "{\"width\":640,\"height\":480}",
        "filter": {
            "options": "{\"command\":\"videobalance saturation=0.0\"}",
            "type": "GStreamerFilter"
        }
    }
}

Response from OpenVidu Server

{
    "id": 2,
    "jsonrpc": "2.0",
    "result": {
        "createdAt": 1646820441733,
        "id": "str_CAM_ZHxJ_con_BbmrLNQdb1",
        "sdpAnswer": "v=0\r\no=mediasoup-client 10000 [...] a=rtcp-rsize\r\n",
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

videoData 🔗

This feature is part of OpenViduPRO tier.

Informs the server about the properties of the video being sent by the user. This method should be sent once after publishing a video stream, and every time any of the video properties change. This method is necessary for the Network Quality API to properly work.

Method sent by client

{
    "id": 19,
    "jsonrpc": "2.0",
    "method": "videoData",
    "params": {
        "audioActive": true,
        "height": 480,
        "videoActive": true,
        "width": 640
    }
}

Response from OpenVidu Server

{
    "id": 19,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

prepareReceiveVideoFrom 🔗

This method is part of OpenViduENTERPRISE tier.

When using mediasoup as media server, the subscription operation must begin with this method. Instead of the client generating an SDP offer and the server sending back an SDP answer, roles are reversed. The server must first generate an SDP offer and the client send back an SDP answer. This is why this method is needed when using mediasoup. The steps to follow are the following ones:

  1. Call prepareReceiveVideoFrom indicating with parameter sender the remote stream to subscribe to.
  2. The response will bring an SDP offer in the spdOffer attribute that must be used to generate an SDP answer in the client.
  3. The SDP answer must be sent by the client in method receiveVideoFrom, using parameter sdpAnswer.

Method sent by client

{
    "id": 3,
    "jsonrpc": "2.0",
    "method": "prepareReceiveVideoFrom",
    "params": {
        "reconnect": false,
        "sender": "str_CAM_KDeZ_con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 3,
    "jsonrpc": "2.0",
    "result": {
        "sdpOffer": "v=0\r\no=mediasoup-client 10000 [...] a=rtcp-rsize\r\n",
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

receiveVideoFrom 🔗

Subscribe to a stream being published to the session. The equivalent method in OpenVidu Browser is Session#subscribe.

The content of the operation and the response is different when using Kurento or mediasoup in OpenViduENTERPRISE . See method prepareReceiveVideoFrom.


When using Kurento 🔗

Method sent by client

{
    "id": 4,
    "jsonrpc": "2.0",
    "method": "receiveVideoFrom",
    "params": {
        "sdpOffer": "v=0 ... a=rtpmap:123 ulpfec/90000\r\n",
        "sender": "str_CAM_KDeZ_con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 4,
    "jsonrpc": "2.0",
    "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": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}


When using mediasoup 🔗

Method sent by client

{
    "id": 4,
    "jsonrpc": "2.0",
    "method": "receiveVideoFrom",
    "params": {
        "sdpAnswer": "v=0\r\no=- 519458450557852 [...] apt=113\r\n",
        "sender": "str_CAM_KDeZ_con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 4,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

onIceCandidate 🔗

Send an ICE candidate to the server.

Method sent by client

{
    "id": 5,
    "jsonrpc": "2.0",
    "method": "onIceCandidate",
    "params": {
        "candidate": "candidate:3885250869 1 udp 2122260223 172.17.0.1 39933 typ host generation 0 ufrag Ie9p network-id 1 network-cost 50",
        "endpointName": "con_Ud1Rk3GbYu",
        "sdpMid": "0",
        "sdpMLineIndex": 0
    }
}

Response from OpenVidu Server

{
    "id": 5,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

unpublishVideo 🔗

Stop publishing a stream to the session. The equivalent method in OpenVidu Browser is Session#unpublish

Method sent by client

{
    "id": 6,
    "jsonrpc": "2.0",
    "method": "unpublishVideo",
    "params": {}
}

Response from OpenVidu Server

{
    "id": 6,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

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

{
    "id": 7,
    "jsonrpc": "2.0",
    "method": "unsubscribeFromVideo",
    "params": {
        "sender": "con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 7,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

leaveRoom 🔗

Disconnect a client from a session. The equivalent method in OpenVidu Browser is Session#disconnect

Method sent by client

{
    "id": 8,
    "jsonrpc": "2.0",
    "method": "leaveRoom",
    "params": {}
}

Response from OpenVidu Server

{
    "id": 576,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

sendMessage 🔗

Send a signal to the session. The equivalent method in OpenVidu Browser is Session#signal

Method sent by client

{
    "id": 9,
    "jsonrpc": "2.0",
    "method": "sendMessage",
    "params": {
        "message": "{\"to\":[],\"data\":\"Test message\",\"type\":\"signal:chat\"}"
    }
}

Response from OpenVidu Server

{
    "id": 9,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

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

{
    "id": 10,
    "jsonrpc": "2.0",
    "method": "forceUnpublish",
    "params": {
        "streamId": "str_CAM_KDeZ_con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 10,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

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

{
    "id": 11,
    "jsonrpc": "2.0",
    "method": "forceDisconnect",
    "params": {
        "connectionId": "con_Ud1Rk3GbYu"
    }
}

Response from OpenVidu Server

{
    "id": 11,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

applyFilter 🔗

Apply a filter to a published stream. The equivalent method in OpenVidu Browser is Stream#applyFilter

Method sent by client

{
    "id": 12,
    "jsonrpc": "2.0",
    "method": "applyFilter",
    "params": {
        "options": "{\"command\":\"videobalance saturation=0.0\"}",
        "streamId": "str_CAM_SB57_con_Hr6uUWKHiT",
        "type": "GStreamerFilter"
    }
}

Response from OpenVidu Server

{
    "id": 12,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

removeFilter 🔗

Removed an applied filter from a stream. The equivalent method in OpenVidu Browser is Stream#removeFilter

Method sent by client

{
    "id": 13,
    "jsonrpc": "2.0",
    "method": "removeFilter",
    "params": {
        "streamId": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

Response from OpenVidu Server

{
    "id": 13,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

execFilterMethod 🔗

Execute a method offered by an applied filter. The equivalent method in OpenVidu Browser is Filter#execMethod

Method sent by client

{
    "id": 14,
    "jsonrpc": "2.0",
    "method": "execFilterMethod",
    "params": {
        "method": "setElementProperty",
        "params": "{\"propertyName\":\"saturation\",\"propertyValue\":\"1.0\"}",
        "streamId": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

Response from OpenVidu Server

{
    "id": 14,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

addFilterEventListener 🔗

Add a listener to an applied filter. The equivalent method in OpenVidu Browser is Filter#addEventListener

Method sent by client

{
    "id": 15,
    "jsonrpc": "2.0",
    "method": "addFilterEventListener",
    "params": {
        "eventType": "CodeFound",
        "streamId": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

Response from OpenVidu Server

{
    "id": 15,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

removeFilterEventListener 🔗

Remove a listener from an applied filter. The equivalent method in OpenVidu Browser is Filter#removeEventListener

Method sent by client

{
    "id": 16,
    "jsonrpc": "2.0",
    "method": "removeFilterEventListener",
    "params": {
        "eventType": "CodeFound",
        "streamId": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

Response from OpenVidu Server

{
    "id": 16,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

connect 🔗

After a network loss and a WebSocket reconnection, this is the first method that the client must send to the server. It will tell if the client still belongs to the OpenVidu Session, or if it is too late and it was evicted from it. See See Automatic reconnection ➞ Signaling plane breaks.

Method sent by client

{
    "id": 17,
    "jsonrpc": "2.0",
    "method": "connect",
    "params": {
        "reconnect": true,
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

Response from OpenVidu Server

If the server did not evict the user:

{
    "id": 17,
    "jsonrpc": "2.0",
    "result": {
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80",
        "value": "reconnection successful"
    }
}

If the server evicted the user:

{
    "id": 17,
    "jsonrpc": "2.0",
    "error": {
        "code": 40007,
        "message": "reconnection error"
    }
}

reconnectStream 🔗

Silently re-negotiates an already established stream, whether it is an outgoing stream (Publisher) or an incoming stream (Subscriber). This can be helpful to reconnect a frozen stream, which may happen when a client loses and recovers its network connection with OpenVidu Server but the media plane remains broken (See Automatic reconnection ➞ Media plane breaks). 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.

When reconnecting a Subscriber stream in mediasoup (only for OpenVidu OpenViduENTERPRISE), the process is slightly different. See below

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

{
    "id": 18,
    "jsonrpc": "2.0",
    "method": "reconnectStream",
    "params": {
        "sdpString": "v=0\r\no=- 6389978899592330342 [...] -bc35-59fd59fea848\r\n",
        "stream": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

Response from OpenVidu Server

{
    "id": 18,
    "jsonrpc": "2.0",
    "result": {
        "createdAt": 1646826648338,
        "id": "str_CAM_SB57_con_Hr6uUWKHiT",
        "sdpAnswer": "v=0\r\no=- 3855815448 [...] 4E:34:0B:16\r\n",
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}


When using mediasoup to reconnect a Subscriber 🔗

Before sending method reconnectStream it is necessary to first call prepareReceiveVideoFrom with parameter "reconnect": true like this:

{
    "id": 18,
    "jsonrpc": "2.0",
    "method": "prepareReceiveVideoFrom",
    "params": {
        "reconnect": true,
        "sender": "str_CAM_SB57_con_Hr6uUWKHiT"
    }
}

... which will generate the following response from the server:

{
    "id": 18,
    "jsonrpc": "2.0",
    "result": {
        "sdpOffer": "v=0\r\no=mediasoup-client 10000 [...] a=rtcp-rsize\r\n",
        "sessionId": "4aktv8cfkhe2ooksplqg0c8v80"
    }
}

Use the resulting sdpOffer to generate an SDP answer, that must now be passed as parameter sdpString of method reconnectStream.



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 event
  • params: a JSON object with the event properties



iceCandidate 🔗

OpenVidu Server has generated an ICE candidate for certain stream. Client must process it on its proper WebRTC peer connection object.

{
    "jsonrpc": "2.0",
    "method": "iceCandidate",
    "params": {
        "candidate": "candidate:1 2 UDP 2015363326 172.17.0.2 9187 typ host",
        "endpointName": "str_CAM_GxWj_con_IoktfUp3Fr",
        "sdpMid": "1",
        "sdpMLineIndex": 1,
        "senderConnectionId": "con_BbmrLNQdb1"
    }
}

sendMessage 🔗

A message broadcasted to the session (can be generated by other client or by the application server). See Send text messages between users.

{
    "jsonrpc": "2.0",
    "method": "sendMessage",
    "params": {
        "data": "Test message",
        "from": "con_BbmrLNQdb1",
        "type": "signal:chat"
    }
}

participantJoined 🔗

Some client has connected to the session.

{
    "jsonrpc": "2.0",
    "method": "participantJoined",
    "params": {
        "createdAt": 1646834217870,
        "id": "con_PLHxdBQ6EG",
        "metadata": "TestClient"
    }
}

participantLeft 🔗

Some client has disconnected from the session.

{
    "jsonrpc": "2.0",
    "method": "participantLeft",
    "params": {
        "connectionId": "con_PLHxdBQ6EG",
        "reason": "disconnect"
    }
}

participantEvicted 🔗

Some client has been forcibly disconnected from the session.

{
  "method": "participantEvicted",
  "params": {
    "connectionId": "con_PLHxdBQ6EG",
    "reason": "forceDisconnectByUser"
  },
  "jsonrpc": "2.0"
}

participantPublished 🔗

Some client has published a stream to the session.

{
    "jsonrpc": "2.0",
    "method": "participantPublished",
    "params": {
        "id": "con_PLHxdBQ6EG",
        "streams": [
            {
                "audioActive": true,
                "createdAt": 1646834218401,
                "filter": {},
                "frameRate": 30,
                "hasAudio": true,
                "hasVideo": true,
                "id": "str_CAM_PBjN_con_PLHxdBQ6EG",
                "typeOfVideo": "CAMERA",
                "videoActive": true,
                "videoDimensions": "{\"width\":640,\"height\":480}"
            }
        ]
    }
}

participantUnpublished 🔗

Some client has unpublished a stream from the session.

{
    "jsonrpc": "2.0",
    "method": "participantUnpublished",
    "params": {
        "connectionId": "con_PLHxdBQ6EG",
        "reason": "unpublish"
    }
}

streamPropertyChanged 🔗

Some client has changed a property of a stream. See StreamPropertyChangedEvent

{
    "jsonrpc": "2.0",
    "method": "streamPropertyChanged",
    "params": {
        "connectionId": "con_PLHxdBQ6EG",
        "newValue": "false",
        "property": "audioActive",
        "reason": "publishAudio",
        "streamId": "str_CAM_PBjN_con_PLHxdBQ6EG"
    }
}

connectionPropertyChanged 🔗

This feature is part of OpenViduPRO tier.

The local client has changed some of its Connection properties. See connectionPropertyChanged.

{
    "jsonrpc": "2.0",
    "method": "connectionPropertyChanged",
    "params": {
        "newValue": "MODERATOR",
        "property": "role"
    }
}

recordingStarted 🔗

The recording of a session has started.

{
    "jsonrpc": "2.0",
    "method": "recordingStarted",
    "params": {
        "id": "TestSession",
        "name": "MyLastRecordings"
    }
}

recordingStopped 🔗

The recording of a session has stopped.

{
    "jsonrpc": "2.0",
    "method": "recordingStopped",
    "params": {
        "id": "TestSession",
        "name": "MyLastRecordings",
        "reason": "recordingStoppedByServer"
    }
}

networkQualityLevelChanged 🔗

This feature is part of OpenViduPRO tier.

The network quality level of a client has changed. See Network quality.

{
    "jsonrpc": "2.0",
    "method": "networkQualityLevelChanged",
    "params": {
        "connectionId": "con_PLHxdBQ6EG",
        "newValue": 5,
        "oldValue": 4
    }
}

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": "con_PLHxdBQ6EG",
    "streamId": "str_CAM_PBjN_con_PLHxdBQ6EG",
    "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"
}

forciblyReconnectSubscriber 🔗

This method is part of OpenViduENTERPRISE tier.

A Subscriber stream must be forcibly reconnected:

  1. Use the parameter value sdpOffer to generate an SDP answer.
  2. Call method reconnectStream. Use the SDP answer as parameter sdpString.

This is only necessary when using mediasoup as media server.

{
    "jsonrpc": "2.0",
    "method": "forciblyReconnectSubscriber",
    "params": {
        "connectionId": "con_Y6vGaAmYkz",
        "sdpOffer": "v=0\r\no=mediasoup-client 10000 [...] a=rtcp-rsize\r\n",
        "streamId": "str_CAM_GZ8F_con_Y6vGaAmYkz"
    }
}