RTSP Adjustable Live Stream

Description

The RTSP Adjustable Live Stream API provides the information that makes it possible to change a subset of the settings of a stream without having to restart it. Please note that videozprofile=storage is incompatible with this API and a 400 Bad Request will be returned if it is used.

Model

The API consists of two RTSP methods that should be used with the URL option adjustablelivestream=1, detailed in the table below:

Method	Description
`GET_PARAMETER` Adjustable-Stream-Settings	Retrieves a list of supported settings that can be changed.
`SET_PARAMETER` Adjustable-Stream-Configuration	Applies updated settings to an ongoing stream.

Please note that it is not recommended to increase the values above what was used when starting the stream as some video players cannot handle values above the initial SDP data.

Identification

To identify the presence of this API on your device you should use one of the two methods detailed below:

RTSP

Use the method GET_PARAMETER with the request parameter Adjustable-Stream-Settings. The request has to be made on a live stream with the URL option adjustablelivestream=1 set. The feature is supported if the response is 200 OK and one or more of the settings are listed. If, however, the response is 451 Parameter not understood, the feature is not supported.

Parameter CGI

If the property below exists and has one or more settings listed the Adjustable Stream Settings feature is supported.

Property: Properties.API.RTSP.AdjustableStreamSettings=<one or more settings>

Common examples

Adjust the stream quality

This example could be used to retrieve supported, adjustable live stream settings. This can then be used to change the quality of an ongoing live stream.

1. Request a video stream with the default settings and enable the adjustable live stream.

rtsp://<camera-ip>/axis-media/media.amp?adjustablelivestream=1

2. Retrieves the supported adjustable live settings for the stream.

GET_PARAMETER rtsp://<camera-ip>/axis-media/media.amp?adjustablelivestream=1 RTSP/1.0
CSeq: 9
Content-Type: text/parameters
Session: W1CzY9GU2dz8QMfE
Date: Fri, 19 Nov 2021 15:54:48 GMT
Content-Length: 29

Adjustable-Stream-Settings:

RTSP/1.0 200 OK
CSeq: 9
Content-Type: text/parameters
Server: GStreamer RTSP server
Session: W1CzY9GU2dz8QMfE;timeout=5
Date: Fri, 19 Nov 2021 15:54:48 GMT
Content-Length: 29

Adjustable-Stream-Settings: compression,fps,videokeyframeinterval,videomaxbitrate,videozstrength

3. Change the settings of the ongoing stream.

SET_PARAMETER rtsp://<camera-ip>/axis-media/media.amp?adjustablelivestream=1 RTSP/1.0
CSeq: 10
Content-Type: text/parameters
Session: W1CzY9GU2dz8QMfE
Date: Fri, 19 Nov 2021 15:54:48 GMT
Content-Length: 79

Adjustable-Stream-Configuration: fps=30,compression=30,videomaxbitrate=100000

RTSP/1.0 200 OK
CSeq: 10
Server: GStreamer RTSP server
Session: W1CzY9GU2dz8QMfE;timeout=5
Date: Fri, 19 Nov 2021 15:54:48 GMT

API specifications

RTSP Adjustable-Stream-Settings

This method should be used when you wish to retrieve the settings that can be applied with RTSP Adjustable-Stream-Configuration.

Request

Security level: Viewer
Method: GET_PARAMETER

Request body syntax

GET_PARAMETER rtsp://<camera-ip>/axis-media/media.amp?adjustablelivestream=1 RTSP/1.0
Content-Type: text/parameters

Adjustable-Stream-Settings

Return value - Success

Returns a comma separated list of supported adjustable stream settings.

RTSP Code: 200 OK
Content-Type: text/parameters

Response body syntax

RTSP/1.0 200 OK
Content-Type: text/parameters

Adjustable-Stream-Settings: compression,fps,videokeyframeinterval,videomaxbitrate,videozstrength

RTSP Adjustable-Stream-Configuration

This method should be used when you wish to configure the settings of an ongoing stream. This will apply to either all settings or none if the request fails. Supported settings are:

compression
fps
videokeyframeinterval
videomaxbitrate
videozstrength

Please note that the settings above will behave the same as the URL options found in the Video streaming API.

Request

Security level: Viewer
Method: SET_PARAMETER

Request body syntax

SET_PARAMETER rtsp://<camera-ip>/axis-media/media.amp?adjustablelivestream=1 RTSP/1.0
Content-Type: text/parameters

Adjustable-Stream-Configuration: fps=30,compression=30,videomaxbitrate=100000

Return value - Success

Returns 200 OK if all settings were successfully applied.

RTSP Code: 200 OK

Response body

RTSP/1.0 200 OK

Return value - Failure

Returns 400 Bad Request if the requested settings were invalid or failed to apply.

RTSP Code: 400 Bad Request

Response body

RTSP/1.0 400 Bad Request

Properties.API.RTSP.AdjustableStreamSettings

This method should be used when you wish to retrieve the supported settings that can be applied with RTSP Adjustable-Stream-Configuration.

Request

Security level: Viewer

Request body syntax

http://<camera-ip>/axis-cgi/param.cgi?action=list&group=root.Properties.API.RTSP.AdjustableStreamSettings

Return value - Success

Returns a comma separated list of supported, adjustable stream settings.

HTTP Code: 200 OK

Response body syntax

root.Properties.API.RTSP.AdjustableStreamSettings="compression,fps,videokeyframeinterval,videomaxbitrate,videozstrength"