Add а stream: Stream.Add

The method and parameters

The method to add a stream for capturing and publishing.

string Stream.Add

(uid camera, uid stream, url source, number priority, bool enable, array tracks, object cluster, object dvr, object capture, object live, object access, object reconnect).

Parameters

uid camera REQUIRED – a unique camera identifier within the installation.

uid stream REQUIRED – a unique stream identifier for a camera.

number priority – the priority of a stream in the camera. It’s used when camera archive is processed.

url source – RTSP URL of the captured/published stream. When source isn’t specified, then the stream is registered but isn’t served. The following URL schemes are supported:

rtsp:// – capture the RTSP stream via the TCP protocol.
tcp:// – is the same as for rtsp://.
udp:// – capture the RTSP stream via the UDP protocol.
sink:// – creates the connection point to publish a stream.

bool enable = true – the stream is on.

array tracks = ["audio","video"] – the list of media streams to capture. If it’s not specified, the video stream will be captured.

video – capture the stream with video data. Will be constantly captured regardless the settings. Supports H.264 and H.265 codecs.
audio – capture the audio stream. If there is no stream in the initial RTSP, the stream won’t be created and captured. Supports the following codecs: PCMU, PCMA, MPA, AAC.

object cluster – the configuration of the stream capture in fault-tolerant mode.

object cluster

string cluster.primary– the hostname of the cluster primary node that constantly captures a stream.

stringcluster.secondary – the host name for the secondary cluster node that takes over the stream capture if the cluster.primary becomes unavailable or fails. The /on suffix indicates that the cluster.primary host is currently unavailable or has failed. The /off suffix indicates the primary host is currently active, and not needed for stream capture in this case.

object dvr – defines the parameters of recording and archive storage for a stream.

object DVR

bytesdvr.buffer= 1M – the size of the internal buffer for caching read and write operations. A larger size reduces the number of disk accesses but increases RAM consumption.

secondsdvr.duration=1d – specifies the DVR storage period in seconds. Once this time is over, the archive will be automatically cleaned. The storage period can be adjusted both upwards and downwards.

The following abbreviations can be used in this context: d – days (example:30d), h – hours (example:120h), m – minutes (example: 20m).

stringdvr.enable – setting of recording in the following format when: mode or week day:offset in seconds: duration in seconds:mode

when can be always, never, event:max prev secs:default post secs,
mode can be full, part.

stringdvr.locationREQUIRED – when DVR recording is enabled, this parameter is required and defines the archive storage location.

bytesdvr.quota = 0G – sets the archive storage volume limit. If the parameter isn’t specified or equals 0, the storage volume is unlimited.

The following abbreviations can be used in this context: G – gigabyte (example: 30G), M – megabyte (example: 120M), K – kilobyte (example: 20K).

In the current version, this parameter doesn't limit disk usage. When calling the API, this parameter can be used as a reference but doesn’t enforce any physical disk space constraints.

object capture – sets the capture parameters.

object capture

stringcapture.enable– set the capture in the format when: mode or week day:offset in seconds:duration in seconds:mode

when – can have the values: always, never, event:max prev secs:default post secs,
mode – can have the values: full, part.

object live – sets the streaming parameters.

object live

stringlive.enable – the streaming parameters in the format when:mode or week day:offset in seconds:duration in seconds:mode

when – can have the values: always, never, event:max prev secs:default post secs,
mode – can have the values: full, part.

object access – specifies the permission access level to Live and DVR.

object access

enumaccess.allow=private – the parameter defines the access type to a stream. The following access types are available:

public – no authorization is required to access a stream.
private – authorization is required to access a stream. Authorization by the OAuth token is always enabled. The following priority for checking access to a stream is defined:

If a whitelistis specified and the client connects from an allowed IP address – access is granted without further checks.
When user and password are set, the client is successfully authorized – access is granted.
An OAuth token is checked. If the token is valid< access is granted.

stringaccess.password – a password for authorization.

stringaccess.user – the username in the web authorization.

arrayaccess.whitelist = []– the list of IP4\IP6 addresses from which access is allowed without authorization.

object reconnect – parameters for reconnecting to a stream upon network loss or disconnect.

object reconnect

secondsreconnect.interval = 3s – a minimum timeout in seconds between attempts to connect to the camera stream.

secondsreconnect.period=5m – – a maximum time interval after which a connection to the camera will be attempted in case of consecutive failed reconnection attempts.

numberreconnect.total= 10– a number of consecutive failed connection attempts, after which the Mediaserver will stop retrying and mark the stream as invalid. You can restart a stream only via the APIStream.Update method.

The following stream reconnection scheme is defined:

If a connection break is detected, Mediaserver checks the total number of failed connection attempts. If the number equals or greater than reconnect.total, then Mediaserver marks the stream as invalid and stops reconnection attempts. If connection attempts are not exhausted, then after an interval, another connection attempt will be made. A successful connection resets any tracking of previous failed attempts. In case of a failed attempt, the counter will be incremented, and the connection interval will be changed by adding the value reconnect.interval to the current interval. With each unsuccessful consecutive connection attempt, the interval will increase up to the value of reconnect.period, after which, until reconnect.total is reached, connections will be attempted at the interval of reconnect.period.

Example:

When reconnect.interval = 3s, reconnect.period = 180s, then the connection period will be 3,6,9,12 ... 180,180 ... 180

POST /api/

JSON-RPC

JSON

{
    "jsonrpc": "2.0",
    "method": "Stream.Add",
    "params": {
        "camera": "uid",
        "stream": "uid",
        "source": "url",
        "priority": "",
        "enable": true,
        "tracks": [
            "audio",
            "video"
        ],
        "cluster": {
            "primary": "string",
            "secondary": "string"
        },
        "dvr": {
            "enable": "string",
            "location": "string",
            "duration": "1d",
            "quota": "0G",
            "buffer": "1M"
        },
        "capture": {
            "enable": "string"
        },
        "live": {
            "enable": "string"
        },
        "access": {
            "allow": "private",
            "whitelist": [],
            "user": "string",
            "password": "string"
        },
        "reconnect": {
            "interval": "3s",
            "period": "5m",
            "total": 10
        }
    },
    "id": 1
}

cURL

BASH

curl -k --request POST \
	--url 'https://your-domain/api/' \
	--header 'Content-Length: 953' \
	--header 'Content-Type: application/json' \
	--header 'Accept: application/json' \
	--header 'Authorization: Bearer <api-authorization-token>' \
	--header 'Content-Length: <Content Length>' \
	--data '{
    "jsonrpc": "2.0",
    "method": "Stream.Add",
    "params": {
        "camera": "uid",
        "stream": "uid",
        "source": "url",
        "priority": "",
        "enable": true,
        "tracks": [
            "audio",
            "video"
        ],
        "cluster": {
            "primary": "string",
            "secondary": "string"
        },
        "dvr": {
            "enable": "string",
            "location": "string",
            "duration": "1d",
            "quota": "0G",
            "buffer": "1M"
        },
        "capture": {
            "enable": "string"
        },
        "live": {
            "enable": "string"
        },
        "access": {
            "allow": "private",
            "whitelist": [],
            "user": "string",
            "password": "string"
        },
        "reconnect": {
            "interval": "3s",
            "period": "5m",
            "total": 10
        }
    },
    "id": 1
}'

PHP

$data = array (
  'jsonrpc' => '2.0',
  'method' => 'Stream.Add',
  'params' => 
  array (
    'camera' => 'uid',
    'stream' => 'uid',
    'source' => 'url',
    'priority' => '',
    'enable' => true,
    'tracks' => 
    array (
      0 => 'audio',
      1 => 'video',
    ),
    'cluster' => 
    array (
      'primary' => 'string',
      'secondary' => 'string',
    ),
    'dvr' => 
    array (
      'enable' => 'string',
      'location' => 'string',
      'duration' => '1d',
      'quota' => '0G',
      'buffer' => '1M',
    ),
    'capture' => 
    array (
      'enable' => 'string',
    ),
    'live' => 
    array (
      'enable' => 'string',
    ),
    'access' => 
    array (
      'allow' => 'private',
      'whitelist' => 
      array (
      ),
      'user' => 'string',
      'password' => 'string',
    ),
    'reconnect' => 
    array (
      'interval' => '3s',
      'period' => '5m',
      'total' => 10,
    ),
  ),
  'id' => 1,
);
$context = stream_context_create([
	'ssl'=>['verify_peer' => false],
	'http' => [
		'method' => 'POST',
		'header' => "Content-Type: application/json\r
Accept: application/json\r
Authorization: Bearer <api-authorization-token>\r
Content-Length: <Content Length>",
		'content'=>json_encode($data)
	]
]);
$result = file_get_contents('https://your-domain/api/', false, $context);

200 OK

The camera UID, the UID of the added stream.

JSON

"<camera-uid>:[<stream-uid>]"

400 Bad Request

A JSON-RPC error

JSON

{
    "error": {
        "code": -32601,
        "message": "Method not found"
    }
}

500 Internal Server Error

The server error