CamStreamer App 3.x functionality can be controlled using API once the application is installed and licensed. There are several parameters described below. Mind that CamStreamer App/stream is restarted every time any parameter is changed.
Read more about API licensing here
Sample API requests to Postman can be downloaded here
Global Parameters
You can get or set multiple global parameters at once usign the following calls:
http://IPADDR[:PORT]/local/camstreamer/param/set.cgi?PARAMNAME=PARAMVALUE[&PARAMNAME=PARAMVALUE]
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
PARAMNAME is a name of any parameter listed below.PARAMVALUE
is a value you would like to save to CamStreamer App. Special characters in the value has to be urlenmarkd. See URL encoding
http://IPADDR[:PORT]/local/camstreamer/param/get.cgi?list=PARAMNAME[,PARAMNAME]
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
PARAMNAME
is a name of any parameter listed below.
In CamStreamer App it is possible to set up several output streams directly by setting JSON array to StreamList parameter or by using simpler HTTP API. Every stream has its own parameters (listed below) which can be set or gained by calling HTTP API.
Parameter LiveLED
(available till version 3.8.2)
Enable LED light indication on the camera. The light is ON if the stream is established. The light is off once the CamStreamer App is not able to broadcast the video . Valid values: 0
, 1
Stream Parameters
The following HTTP API call list all streams.
http://IPADDR[:PORT]/local/camstreamer/stream/list.cgi?action=get
The following POST API call updates the whole JSON configuration of CamStreamer App.
http://IPADDR[:PORT]/local/camstreamer/stream/list.cgi?action=set
You can add / update a stream by the set.cgi HTTP API call bellow. Mind that the stream added by API is not visible in the CamStreamer App user interface. If you'd like to start a broadcast on YouTube, please use YouTube Live Streaming API. It's necessary to obtain an RTMP ingestion url / key.
http://IPADDR[:PORT]/local/camstreamer/stream/set.cgi?stream_id=STREAMID&PARAMNAME=PARAMVALUE[&PARAMNAME=PARAMVALUE]
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier (string). A new stream is created if sent stream_id does not exist. If stream_id exists current stream is modified. For API are reserved identifiers with "api" prefix.PARAMNAME
is a name of any stream parameter listed below.PARAMVALUE
is a value you would like to save to the stream. Special characters in the value has to be urlenmarkd. See URL encoding
You can get a stream parameters by the get.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/get.cgi?stream_id=STREAMID
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier.
You can remove a stream by the remove.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/remove.cgi?stream_id=STREAMID
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier.
Parameter enabled
Stop or start the stream using parameter "Enabled". Valid values: 0
, 1
Parameter mediaServerUrl
Valid values (for selected protocol):
- RTMP
rtmp://[user:pass@]server:port[/app][/stream_name]
- MPEG-TS TCP
tcp://server:port
- MPEG-TS UDP
udp://server:port[?pkt_size=XXX&ttl=XXX]
- HLS PULL
hls://
- HLS stream is available at http://IPADDR:PORT/local/camstreamer/SIGNATURE/live.m3u8
- where:
IPADDR
is an IP address of the camera.SIGNATURE
get signature at http://IPADDR:PORT/local/camstreamer/param/get.cgi?list=signature - HLS PUSH
ftp://your_ftp_server/live.m3u8
- SRT
- Mode Caller (push):
srt://:port
- Mode Listener (pull):
srt://server:port
You can stop or start the stream using parameter "Enabled". Valid values: 0
, 1
Parameter inputType
Defines what type of resource will be used.
CRS
uses RTSP camera streamCSw
uses CamSwitcher App streamRTSP_URL
uses external RTSP stream
Parameter inputUrl
EXPERIMENTAL
It is used for streaming if the inputType
is selected as an external RTSP stream (RTSP_URL
).
IMPORTANT: HLS playlist requires parameters resolution and videomaxbitrate in internalVapixParameters or userVapixParameters.
Example:
{
"3577": {
"enabled": "1",
"active": "1",
"audioSource": "default",
"avSyncMsec": "0",
"internalVapixParameters": "resolution=1920x1080&videomaxbitrate=3000",
"userVapixParameters": "",
"outputParameters": " -hls_time 2 -hls_list_size 5 -hls_wrap 10 ",
"outputType": "video",
"mediaServerUrl": "hls:\/\/",
"inputType": "RTSP_URL",
"inputUrl": "rtsp://root:pass@192.168.91.137/axis-media/media.amp?audio=1&video=1&resolution=1920x1080",
"forceStereo": "0",
"streamDelay": "",
"statusLed": "1",
"statusPort": "",
"callApi": "0",
"trigger": "none",
"schedule": "[]",
"prepareAhead": "0",
"startTime": "0",
"stopTime": "0"
}
}
Parameter userVapixParameters
Overwrite the default video parameters. See parameter description. You can e.g. choose different camera or View Area using parameter camera=2&resolution=1280x720&overlaypos=200%2C600
.
Parameter audioSource
Specify the audio channel. Available values:
none
disable the audio channel.default
use the audio channel from the camera (e.g. mic./line input), audio from CamSwitcher App or external URL (if selected in inputType
parameter)file: FILEPATH
use an audio file FILEPATH (mka/mp3) on the file system on the camera (e.g. SD card). If you want to stream to YouTube with camera without audio, use following settings "audioSource=file:/usr/local/packages/camstreamer/tools/silence.mka"url: URL
use an external (network) audio source (markc AAC or MP3). E.g. internet radio, another camera or Axis P8221 audio enmarkr. For Axis device: rtsp://root:password@IPaddress/axis-media/media.amp?audio=1&video=0 Use audio sample rate 44.1KHz and bitrate 128Kbps. CamStreamer App is not streaming once the external audio is not available.
Parameter avSyncMsec
Time offset for audio/video channel in milliseconds.
Parameter active
Pause stream – the stream will not run, but all other processes are active. Typical API server calls in callApi – the application calls server APIs (creation and ending streams on YouTube).
Parameter trigger
Determines type of automation.
none
automation offinputX (X is the input number)
the stream is turned on only if the given camera input is activetime
stream is turned on based on a time interval (startTime / stopTime parameters)recurrent
stream is turned on based on a time schedule (schedule parameter)
Parameter schedule
Valid only for trigger recurrent, schedule is represented by JSON format. Schedule contains array of intervals where day is a number in range 0-6 (0 for Monday) and time is string in format HH:MM:SS. The time gap between planned events on YouTube must be at least 15 minutes – incorrect settings can cause wrong behavior.
Example:
Two intervals: Monday 8:00 to 9:30, Tuesday 10:00 to Wednesday 10:00
[{ "day_from": 0, "day_to": 0, "time_from": "08:00:00", "time_to": "09:30:00" }, { "day_from": 1, "day_to": 2, "time_from": "10:00:00", "time_to": "10:00:00" }]
Parameter prepareAhead
(only trigger time) – prepares a stream for a given number of seconds before startTime (calls API, starts to stream).
Parameter startTime
(only trigger time) - unix timestamp for the beginning of the stream.
Parameter stopTime
(only trigger time) - unix timestamp for the end of the stream.
Parameter statusLed
Activates camera LED diode blinking during the preparation of broadcasting and lighting during streaming. If the same LED is used for more streams the LED lights after the last stream is started. Valid values: 0
, 1
Parameter statusPort
Activates camera output with LED diode and set blinking during the preparation of broadcasting and lighting during streaming. If the same output is used for more streams the LED lights after the last stream is started. Valid values: number of camera port with output.
Get the current status of a particular stream
Get the status of your stream via the following request.
http://IPADDR[:PORT]/local/camstreamer/get_streamstat.cgi?stream_id=X
where X is the Stream ID of your stream.
Response:
{"status": 200, "message": "OK", "data": {"net_stats":"110779840 1107300413","stream_bytes_time_ms":1600092179717,"stream_bytes":568335,"start_count":1,"is_streaming":1}}
Get current YouTube Live broadcast
Redirect your viewers to the current broadcast.
https://camstreamer.com/yt-broadcast-api/SECTOKEN/CSID
where SECTOKEN and CSID are used in "Permanent link" in CamStreamer App user interface. Mind that the SECTOKEN is changed once you use a different YouTube channel.
From June 2021 the SECTOKEN and CSID are replaced with unique hash in Permanent link (for streams created from this date). For such new streams use the hash (e.g. dccZkIw35I5xnZ3k650rMuvk5HuvP123456abCd) instead of a combination of SECTOKEN/CSID.
Examples:
https://camstreamer.com/yt-broadcast-api/b7133489237eee1/S-78
https://camstreamer.com/yt-broadcast-api/dccZkIw35I5xnZ3k650rMuvk5HuvP123456abCd
Response:
{"broadcast_id":"XCIfaGvbXSs"}
Status of YouTube Live broadcast
Check whether the YouTube broadcast is live and whether the you Get information from our watchdog. It is suitable for integration with monitoring systems like Nagios, Centreon...
https://camstreamer.com/api/youtubeStatus/SECTOKEN/CSID
where SECTOKEN and CSID are used in the "Permanent link" in the CamStreamer App user interface. Mind that the SECTOKEN is changed once you use a different YouTube channel.
Response HTTP code:
- 200 Stream ok
- 404 Stream not found or bad security token
- 400 Stream not checked yet
- 400 Stream interrupted
Get the list of streams for a particular camera with its details
If you need to show a list of scheduled streams on your website along with their permanent links, you can use this GraphQL application interface.
To get a list of streams, use this POST call:
https://camstreamer.com/api/Stream/graphql
Authorization via API key:
KEY: Authorization
VALUE: cameraLicenseKey
Example:
Query with serial number and license code (the same as in Authorization)
query {
GetStreamInfoList(
licenseCode: "CS-JYUHJDU6I3ABCDEFGHIJ",
serialNumber: "B8A44F0ABCDEF"
) {
streamId
title
streamType
description
platformType
cameraTimezone
startTime
stopTime
previewLink
}
}
Response with URL encoded permanent link:
{
"data": {
"GetStreamInfoList": [
{
"streamId": 36,
"title": "Title of one-time event",
"streamType": "onetime",
"description": "My description",
"platformType": "youtube",
"cameraTimezone": "Europe\/Berlin",
"startTime": 1677840720,
"stopTime": 1677844365,
"previewLink": "https%3A%2F%2Ftestingb.camstreamer.biz%2Fredirect%2FyA8T7AyGg23PrXJNI9zqZDr"
}
]
}
}
Practical Examples
When you’re creating a new stream, use a different ID than the one created by the CamStreamer App. Our application uses whole numbers higher than 10. Use a prefix like “api_01”. A YouTube stream may be controlled via an API, but YouTube authorization first has to be carried out via a user interface.
In order for the camera to stream, the following conditions must be met: parameter enabled = 1
, parameter active = 1
and parameter trigger = none
or automation was active (input on or correct time interval)
Creation / modification of a new nonstop RTMP stream
PARAMETERS:
"enabled":"1", "audioSource":"default", "mediaServerUrl":"rtmp:\/\/a.rtmp.youtube.com\/live2\/rfp-test-2926.q9yk-3wv0-4zzg-78ks"
You can change a stream parameters by the set.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/set.cgi?stream_id=STREAMID&enabled=1&audioSource=default&mediaServerUrl=rtmp://a.rtmp.youtube.com/live/rfp-test-2926.q9yk-3wv0-4zzg-78ks
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier (string). A new stream is created if sent stream_id does not exist. If stream_id exists current stream is modified. For API are reserved identifiers with "api" prefix.
Stopping an RTMP stream
PARAMETERS:
"enabled":"0"
You can stop a stream by the set.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/set.cgi?stream_id=1057&enabled=0
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier (string). A new stream is created if sent stream_id does not exist. If stream_id exists current stream is modified. For API are reserved identifiers with "api" prefix.
Creation / modification of a new RTMP stream by pressing button 1
PARAMETERS:
"enabled":"1", "audioSource":"default", "trigger":"input0", "mediaServerUrl":"rtmp:\/\/a.rtmp.youtube.com\/live2\/rfp-test-2926.q9yk-3wv0-4zzg-78ks"
Audio parameter:
- for microphone use "default"
- if the camera has no audio and you want to stream e.g. to YouTube where the audio is required, use this URL encoded value for audio "file:/usr/local/packages/camstreamer/tools/silence.mka"
You can create / modificate a stream by the set.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/set.cgi?stream_id=1057&enabled=1&audioSource=default&trigger=input0&mediaServerUrl=rtmp%3A%2F%2Fa.rtmp.youtube.com%2Flive2%2Frfp-test-2926.q9yk-3wv0-4zzg-78ks
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier (string). A new stream is created if sent stream_id does not exist. If stream_id exists current stream is modified. For API are reserved identifiers with "api" prefix.
Creation / modification of a new RTMP stream from 2019-03-04 11:10 to 2019-03-04 14:10 in UTC+01
"enabled":"1", "audioSource":"default", "trigger":"time", "startTime":"1551694200", "stopTime":"1551705000", "mediaServerUrl":"rtmp:\/\/a.rtmp.youtube.com\/live2\/rfp-test-2926.q9yk-3wv0-4zzg-78ks"
You can create / modificate a stream by the set.cgi HTTP API call bellow.
http://IPADDR[:PORT]/local/camstreamer/stream/set.cgi?stream_id=1057&enabled=1&audioSource=default&trigger=time&startTime=1551694200&stopTime=1551705000&mediaServerUrl=rtmp%3A%2F%2Fa.rtmp.youtube.com%2Flive2%2Frfp-test-2926.q9yk-3wv0-4zzg-78ks
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
STREAMID
is a stream identifier (string). A new stream is created if sent stream_id does not exist. If stream_id exists current stream is modified. For API are reserved identifiers with "api" prefix.
WebSocket API
Over the WebSocket connection, you can receive information about the statuses of streams.
Authorization
Get authorization token for WebSocket API. The token is valid only for 30 seconds or until the first connection.
Request:
http://USER:PASS@IPADDR[:PORT]/local/camstreamer/api/ws_authorization.cgi
where
USER
is a user name. E.g. root
PASS
is a password. E.g. pass
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
Response:
{ "status": 200, "message": "YZWG1nBG7HtRc8Owy61P",}
Connection to WebSocket
You must use authorization as the first message. After successful authorization, the initialization data are sent. On authorization error, WebSocket is closed.
Used protocol (Sec-WebSocket-Protocol
) is events
WebSocket address:
wss://IPADDR[:PORT]/local/camstreamer/events
where
IPADDR[:PORT]
is an IP address:port of the camera. E.g. 192.168.1.5
Request:
{
"authorization": "80aXr8Vm0iFZl3Rlo2tR"
}
Response:
{
"type": "authorization",
"state": "OK"
}
To resend initialization data user request below.
Request:
{
"command": "sendInitData"
}
Response:
{"type":"init","data":{"type":"StreamState","streamID":"117930","enabled":0,"active":1,"automationState":1,"isStreaming":0}}
{"type":"init","data":{"type":"PortChanged","port":0, "value":0}}
Type of events
StreamState - attributes: type
,streamID
, enabled
, active
, automationState
, isStreameing
{
"type": "StreamState",
"streamID": "117930",
"enabled": 0,
"active": 1,
"automationState": 1,
"isStreaming": 0
}
CS_API_SUCCESS - attributes: type
, streamID
, apiCall
, message
{
"type": "CS_API_SUCCESS",
"streamID": "117930",
"apiCall": "startBroadcast",
"message": "Broadcast started."
}
PortChanged - attributes: type
, port
, value
{
"type": "init",
"data": {
"type": "PortChanged",
"port": 0,
"value": 0
}
}