Video¶

Capabilities¶

Capability	Support	Comment
WebRTC
Transcoding codec
One to many stream		A single video stream is received by the video server and subsequently transmitted to all consumers, resulting in reduced bandwidth usage.
Video server connection monitoring		See server connection monitoring
Stream connection monitoring		See stream connection monitoring
Connect external stream (ex: camera)		See connect to streaming
Connect to dynamic URL stream (ex: ONVIF camera)		See connect to streaming
External stream connection monitoring		See connect to streaming
Manage multiples rights		Not yet implemented. See rights
Enable stream on condition		See enable a stream on condition
Recording		This feature is currently not supported. In case of interest please contact us at info@swissdotnet.ch
PTZ		See ONVIF PTZ controller
Network access (TURN/STUN/ICE)		See Configure network

Concept¶

OnSphere dedicated the transcoding and collect of stream to a software named Kurento. This server is controlled by the osp-video module.

See kurento official documentation for details.

Known bug and troubleshooting¶

Input encoding - Kurento¶

Note

By input we mean the stream from video to Kurento.

See the Kurento documentation for up-to-date documentation. See the documentation extract below :

List of kurento compatibilities from official website.

Output encoding - WebRTC¶

Note

By output we means the stream from Kurento to Browser

The web page video widget uses the WebRTC protocol, as indicated by the WebRTC official<https://webrtc.org/>. This implies there are slight differences in encoding and support depending on user’s browser (version and software editor).

As WebRTC is built for negotiation and the Kurento server can dynamically re-encode the stream based on the browser’s capabilities, there is no configuration needed on the user’s end.

To access the latest information on WebRTC codec support, please consult: WebRTC codec support<https://developer.mozilla.org/en-US/docs/Web/Media/Formats/WebRTC_codecs>.

Note

The H265 is not present in the WebRTC standard, but there is an experiment in progress for some browser.

Server connection monitoring¶

Concept¶

The connection between osp-video and the Kurento allows OnSphere to manage pipeline on the Kurento server. This link can be monitored.

Usage¶

The connection state between the osp-video module and the kurento server can be read as a BOOLEAN value in the OnSphere hierarchy (i.e. root.video.controller for example). If the connection is not working the state will be set to false.

Use-case¶

Detect network failure between the osp-video and the server

Connect a stream¶

Concept¶

Each video stream is associated with a value representing the state of the stream (i.e., ACTIVE or INACTIVE).

A video stream can be accessed either by

Its Value (i.e., the Value associated with the stream in the hierarchy)
A Value that has a video controller referencing the video stream

Here is an hierarchy example (using owner.video, owner.scripts, controller.video, value.ospp) :

Video stream access can thus be configured with great flexibility, from simple right-access checks to complex conditional evaluations computed by scripts.

Internally, the video module will keep a map of enabled/disabled video streams links that will be updated with controllers execution when their associated Value changes. It will also use controllers for resolving links to video streams when the video stream’s Value is not directly used.

Note

The Value associated with a video controller must be of BOOLEAN type for the moment.

Usage¶

Connect a camera
Connect to a video provider

Example¶

Connect to a dynamic URL¶

Concept¶

Video streams can use urlProviders to establish a connection with a dynamically configured URL. This provider will publish a value and the video server will connect to it.

Usage¶

Use the urlProviders field to incorporate a string type value. When this value is updated, the URL stream will be automatically updated accordingly.

Use-case¶

Create a rotating video (changing the source) with a script
Use ONVIF to publish URL

Stream connection monitoring¶

Concept¶

The stream’s status can be monitored and corresponding actions can be taken.

Usage¶

Stream state is associated with a boolean value.ospp linked to controller.video file. The boolean status true means the flux is currently streamed and the false status means the stream is not updated.

Manage multiples rights¶

Concept¶

Not yet implemented. Rights are managed by standard system. If there is a need to have multiple rights for the same camera, the system supports a reference. A camera can be referenced by multiple ITEM(s) linked to the mainstream with the controller.

Enable stream on condition¶

Concept¶

Use the controller reference inside the video widget and add a conditional boolean value.

Warning

Do not forget to block the main camera ID from unauthorized users (never trust client information)

Network configuration - TURN/STUN/ICE¶

TURN Server

A TURN server is used to allow access between consumers/producers and the Kurento server. This is necessary in 99% of cases. See the TURN manual installation.

Video to Kurento

The video server can connect to multiple Kurento servers (see kurento installation). This can be a solution to dispatch highly intensive media encoding tasks.

The video server must access the Kurento API. This connection is configured inside the owner-server.video file.

Note

Currently, only ws (not wss) socket is supported. Therefore, it is highly recommended to monitor access within a trusted network. (The support of wss is in the development pipeline.)

Widget to Kurento

Widgets must access the Kurento server from UDP/TCP ports defined inside the Kurento configuration. These ports are used to transport the video stream.

Resume:

TURN port must be reachable to all peers and Kurento.
Kurento administration TCP port must be reachable from the video module.
Kurento media ports must be reachable.

About NAT, ICE, STUN, TURN¶

To use Kurento servers it is mandatory to understand and configure the network to allow connection between each peer.

The video module must access the Kurento API port (by default 8888)
The video module must have access to rabbit-mq
Kurento must have access to the camera and consumers
The consumers (widget) must have access to osp-web and Kurento
Turn server must be reachable from outside and from Kurento (both will use this TURN server to connect on peer)

One of the most difficult problem is to give access between the Kurento server and the consumers/producers for the RTPS(s) flux because of the NAT and the mDNS which is not well supported in Docker.

About mDNS¶

mDNS resolves hostname to IP address in local networks without the use of a nameserver. This service is not well interoperable with Docker. But it is always possible to create a non Docker version of Kurento service (beware to use the same configuration as the current Kurento docker used by OnSphere).

About performances¶

Media encoding is very intensive and needs a lot of CPU/RAM. This is why it’s necessary to take the time to check the need and the configuration of the different streams. It’s not a bad idea to have a reflection about where the Kurento server must be installed and why.

Below are some key points necessary to make proper choices for performances :

It’s possible to disable transcoding in flux, thus avoiding a very cost extensive task but since it disables the transcoding for the consumer, there could be some incompatibility
Buffering and GRID are expensive tasks
When two consumers use the same codecs, the Kurento server will transcode only once
Keeping the flux open allows buffering (feature not yet implemented) but it consumes a stream 24/24

Warning

Keep in mind :

Docker uses a lot of RAM to map a big range of ports if not bound as host :

This means it’s best to use Kurento and TURN servers as “host” bound services (with direct network access of the host) for performances purpose. If no possible, do not use too much ports, but only a number in correlation with the number of consumers/producer configured/active at the same time.

Network configuration¶

How to configure network for Video streaming.

TURN server : manual installation¶

If there is already one TURN server available, the best option is to use it. Otherwise a TURN server must be installed and available from all the consumer/producer and Kurento server.

Simple example of server¶

Create a new module inside the OnSphere configuration :

coturn:
    image: "instrumentisto/coturn:latest"
    ports:
        - "3478:3478/tcp"
        - "3478:3478/udp"
        - "16000-16100:16000-16100/udp"
    command: '--log-file=stdout -c /tmp/turnserver.conf'
    configs:
        - source: turnconfig.conf
        target: /tmp/turnserver.conf
        mode: 444

This configuration is naive : 1. Only 100 ports available 2. Ports are not bound as host (there is no host option for ports range) (very memory expensive)

Then add a configuration file inside the portainer session and adapt the ports and the user account. (Do not forget to expose the same port in the service and to replicate.)

Warning

Do not forget to add the turnconfig.conf inside the stack.config file as external resources

# This server's external/public address, if Coturn is behind a NAT.
# It must be an IP address, not a domain name.
external-ip=10.110.0.120

# STUN listener port for UDP and TCP.
# Default: 3478.

#listening-port=<CoturnPort>

realm=swissdotnet.ch

min-port=16000
max-port=16100

verbose

# Use fingerprints in the TURN messages.
fingerprint

# Use long-term credential mechanism.
lt-cred-mech

# 'Static' user accounts for long-term credentials mechanism.
user=swissdotnet:swissdotnet
user=swissdotnet1:swissdotnet1

# Disable log file rollover and use log file name as-is.
simple-log

Warning

Do not forget to set the TURN access inside the Kurento configuration and the server configuration

Resources : * official manual

Kurento server and Video¶

The Kurento server is configured from the default docker provided in docker hub.

Configuration is straightforward :

Step 1 : Deploy a Kurento server where it makes the most sens (could be in the stack)

Below is a “naive configuration” :

Only 100 ports. It means 50 consumer/producer at the same times.
Use “overlay” ports instead of host port (there is currently no range configuration possible for host port in docker-compose)
No wss configured (not an issue if your swarm is encoded)

kurento:
  image: kurento/kurento-media-server:6.14.0
  networks:
    back:
    aliases:
      - kurento
    outside_access:

  environment:
    - KMS_MIN_PORT=15000
    - KMS_MAX_PORT=15100
    - KMS_TURN_URL=swissdotnet1:swissdotnet1@10.110.0.120

  ports:
    - "8888:8888/tcp"
    - "15000-15100:15000-15100/udp"

There are a lot of possible configurations (even not to using a Docker but a native installation with better support of mDNS (see below)).

Step 2 : Configure the link between the module video and Kurento (can have multiple Kurento servers)

owner-server.video :

{
    "moduleId": "modules.video.video-1",
    "url": "ws://kurento:8888/kurento"
}

Requirement¶

Module osp-video
Kurento : https://www.kurento.org/
Explanation of NAT transversal : https://anyconnect.com/stun-turn-ice/