IP cameras 🔗



How to publish IP cameras 🔗

You can publish any IP camera sending video over RTSP. You perform this operation from your server by consuming OpenVidu Server REST API.

Events dispatched in the clients 🔗

Whenever you call this method, a new participant will join the chosen session, and a new stream will be published to it. All the expected events are triggered in every client connected to the Session, just as when a regular client joins and publishes to a session. The workflow is:

  1. Your backend publishes an IP Camera to the session as shown in the code snippets above
  2. Every client connected to that session will receive a connectionCreated event. This event will be no different to any connectionCreated event dispatched by a regular client joining the session
  3. Every client connected to that session will receive a streamCreated event. The only difference with any other streamCreated event dispatched by a regular client publishing to the session is that the Stream object returned by the event will have property typeOfVideo set to "IPCAM". Users can subscribe to this stream as any other regular stream (see Subscribe/Unsubscribe from a stream)

After unpublishing the IP camera all participants connected to the session will receive the proper streamDestroyed and connectionDestroyed events.

Events dispatched in the backend 🔗

Your backend side will also receive the expected events in the CDR and Webhook. Just as happens for the client-side events, for the backend same events will be dispatched as for any other regular user:

  • participantJoined event fot the new IP camera participant. platform property is set to "IPCAM".
{"participantJoined":{"sessionId":"MySurveillanceSession","timestamp":1582108095130,"participantId":"ipc_IPCAM_rtsp_C4CU_b1_dnsdojo_com_1935_live_sys3_stream","location":"Amsterdam, Netherlands","platform":"IPCAM","clientData":"","serverData":"Beach camera"}}
  • webrtcConnectionCreated event fot the new IP camera stream. It is actually an RTSP stream and not a WebRTC stream, but for the shake of compatibility the name of the event will remain the same for now. videoSource property is set to "IPCAM".
{"webrtcConnectionCreated":{"sessionId":"MySurveillanceSession","timestamp":1582108095351,"streamId":"str_IPC_SJmx_ipc_IPCAM_rtsp_C4CU_b1_dnsdojo_com_1935_live_sys3_stream","participantId":"ipc_IPCAM_rtsp_C4CU_b1_dnsdojo_com_1935_live_sys3_stream","connection":"OUTBOUND","rtspUri":"rtsp://b1.dnsdojo.com:1935/live/sys3.stream","adaptativeBitrate":true,"onlyPlayWithSubscribers":true,"videoSource":"IPCAM","videoFramerate":null,"videoDimensions":null,"audioEnabled":true,"videoEnabled":true}}

After unpublishing the IP camera your backend will receive the proper events webrtcConnectionDestroyed (one for the IP camera's stream itself and one for each user that was subscribed to the camera's stream) and participantLeft event (only one for the camera's connection).



How to unpublish IP cameras 🔗

To unpublish an IP camera stream you must remove the connection owning the stream. You can do it from your server:

WARNING: you cannot remove an IP camera by directly deleting its Stream. You must delete the Connection object instead. Trying to remove an IP camera by deleting its Stream instead of its Connection will result in an error. See HTTP responses of method DELETE /api/sessions/<SESSION_ID>/stream/<STREAM_ID>



Configuring IP cameras 🔗

When publishing an IP camera, you can configure 2 properties that will affect the management of the camera's media stream. These are:

adaptativeBitrate 🔗

Whether to re-encode the IP camera stream in OpenVidu, or not. Enabling this allows OpenVidu to provide a dynamic video quality that is automatically adapted to the network conditions of the Subscribers of the IP camera, which helps avoid playback issues. It is active by default, and it allows OpenVidu Server to provide a robust and reliable flow to participants that will receive the IP camera stream. But re-encoding video has a moderately high CPU cost.

When this option is disabled, the video is served as-is from the IP camera. For this to work, the source video codec must be compatible with receiving browsers; normally this means outputting either H.264 or VP8 video from the camera. OpenVidu will not adapt the video quality dynamically, which greatly reduces CPU usage on the server; however you could still change by hand the IP camera's settings in order to vary the output size or bitrate.

An example of situation where you might want to disable this setting is in environments where all Subscribers are guaranteed to have a very good network link with OpenVidu, thus network congestion is expected to be zero, and there is no need for dynamic quality adaptation.

onlyPlayWithSubscribers 🔗

Whether to enable the IP camera stream only when some user is subscribed to it or not. What this means is that OpenVidu Server will only establish the RTSP connection with the IP camera when some participant asks to subscribe to the camera's stream. The rest of the time OpenVidu Server will not be effectively receiving any packets from the IP camera, saving CPU power and bandwidth. This option is active by default.

The counterpart to this option, which in principle would always seem desirable, is that the first participant requesting to subscribe to the camera's stream will take a little longer to do so, as OpenVidu Server has to establish the RTSP connection with the camera in the first place. Just after the last participant subscribed to the camera's stream unsubscribes from it, the RTSP connection between OpenVidu Server and the IP camera will be closed again, and the cycle starts again (next first participant subscribing to the camera's stream will have to wait longer than usual to receive the video).

Generally speaking you'll want this option set to true, but if for your particular use case the response time of the first subscriber to the camera's stream is vital, you can set this option to false to never stop receiving the camera's feed.