Rate control

The API is built on the CGI param.cgi, which lets you query and set the default stream parameters, as well as the URL parameters for RTSP URLs.

The API is identified through param.cgi and the following properties:

Property

Image.IO.RateControl.Mode

Property

Image.IO.RateControl.MaxBitrate

The presence of the MBR mode in Image.IO.RateControl.Mode and the videobitratemode URL is identified by Properties.Image.RateControl.Version when it is set to 1.1 or higher.

The presence of the ABR (Average bitrate) is identified through the following property:

Property

Properties.API.ABR.ABR=yes

The CBR mode (Constant bitrate) has been deprecated and selecting it will cause MBR (Maximum bitrate) to activate instead.

The purpose of maximum bitrate is to limit the immediate network bitrate, as it is not built to regulate the expected storage of a stream. This means that if the desired maximum bitrate is set at an unrealistically low level there might be an impact on the video quality in motion heavy scenes, where high quality is important. It is therefore recommended to use variable- or average bitrate instead.

The purpose of average bitrate is to provide the best quality on the stream based on available storage.

Establishment

The average bitrate algorithm takes about 24 hours to gather data and provide the best quality level, with the bitrate adjusting according to the most recent data. Depending on the monitored scene, the establishing time may vary.

The available storage is defined by the target bitrate that measures the running time of the stream, thus the aim of the average bitrate is to not exceed the target bitrate, as this would surpass the available storage. During the initial 5 minutes of a stream, the average bitrate/second may exceed the requested target bitrate.

Margin

The average bitrate algorithm accumulates a margin between 10–30% of the available storage space and uses it during periods when the bitrate is temporarily higher. This means that not all of the storage space available will be used. How much of the margin it uses depends on the scene and when the bitrate gets more unpredictable, in which case a higher margin is used.

Bitrate histories

The camera stores the bitrate history of a stream internally. In the case when a stream is restarted, for example when the network goes down, this history is restored when an identical stream is started. The camera has allocated space for up to 10 such stories, meaning that the oldest one will be deleted when the memory gets full.

History lost due to power outage

The camera has two ways of storing bitrate histories: temporarily in the RAM and permanently on the flash memory. For continuously running streams, the bitrate history gets stored on the flash memory once every 24 hours. If a stream is closed, the bitrate history will be stored on the flash memory, but only as long as the stream has been active for more than 8 hours, otherwise it will be stored on the RAM. When the camera is rebooted in a proper way, histories will be stored on the flash memory.

The reason why there is an 8 hour minimum time limit when writing to flash is to avoid unnecessary wear on the flash memory. This does mean that in the case of a power outage, bitrate history could be lost.

Incompatible recordings

This feature is currently not compatible with event-triggered recordings, nor with continuous recordings that aren’t active 24/7. If ABR is used in conjunction with these recordings, the image quality will suffer a downgrade and all of the available storage might not be used.

Limitations

If an unreasonable low target bitrate is provided, quality may be impacted and in some cases the average bitrate/second and thus the used storage may exceed the available storage.

The purpose of variable bitrate is to guarantee that the selected compression will be used. Also, both instantaneous bitrate and storage might be unpredictable, as variable bitrate may be as large as the hardware limit. Depending on the resolution and frame rate it will be limited to what the level of that resolution and frame rate supports, however it should be at least 50 Mbits/s.

Use this example to set the rate control parameters on the stream RTSP URL to ensure that the bitrate of the stream is able to handle the network bandwidth limitations. This should be done to support a number of cameras on the network and make sure that it is not overloaded.

Set the rate control parameters in the RTSP URL

rtsp://<myserver>/axis-media/media.amp?videobitratemode=mbr&videomaxbitrate=1000&videobitratepriority=quality

rtsp://<myserver>/axis-media/media.amp?videobitratemode=vbr&videobitrate=1000
rtsp://<myserver>/axis-media/media.amp?videobitratemode=mbr&videobitrate=1000
rtsp://<myserver>/axis-media/media.amp?videobitratemode=mbr&videoabrtargetbitrate=1000

Use this example to set the default rate control settings for an image view of the camera. If you are using just a few cameras, this can be set via the web interface (Axis Camera Assistant), however, if you are using several cameras, use the Axis Device Manager.

Getting and setting the default rate control parameters for image view

http://<myserver>/axis-cgi/param.cgi?action=list&group=Image.I0.RateControl

http://<myserver>/axis-cgi/admin/param.cgi?action=update&root.ImageSource.I0.RateControl.Mode=mbr&root.ImageSource.I0.RateControl.MaxBitrate=1000&root.ImageSource.I0.RateControl.Priority=quality

Use this example to set the rate control parameters on the RTSP URL stream. This is done to ensure that the stream and network bandwidth doesn't exceed the limitations of the storage space that has been accumulated for a specific retention time.

Setting ABR parameters on the RTSP URL

rtsp://<myserver>/axis-media/media.amp?videobitratemode=abr&videoabrtargetbitrate=500&videoabrretentiontime=30&videoabrmaxbitrate=1000

Use this example to choose a default ABR setting for the image view of a camera. If you are using just a few cameras, this can be set via the web interface (Axis Camera Assistant), however, if you are using several cameras, use the Axis Device Manager.

Setting the default ABR parameters for image view

http://<myserver>/axis-cgi/admin/param.cgi?action=update&root.ImageSource.I0.RateControl.Mode=abr&root.ImageSource.I0.RateControl.ABR.TargetBitrate=500&root.ImageSource.I0.RateControl.ABR.MaxBitrate=1000&root.ImageSource.I0.RateControl.ABR.RetentionTime=30

Use this example to add an alarm for whenever an ABR stream has an abnormal status.

A stateful event is declared and sent per image source and contains information about a stream by using ABR, which is set in an error state. If at least one ABR stream is in an error state on an image source, abr_error will be set to 1. In those cases, the other properties of the event will contain the information about the stream in the worst state. Some of theses properties will identify the parameters, such as resolution or state of the stream. The states are, in order of severity:

• low_bitrate: When set to 1, the stream’s average bitrate is significantly lower than the average bitrate. The storage, defined by the target ABR multiplied by the retention time will not be filled up, however either the target average bitrate or some of the parameters can be adjusted to allow the available storage to be filled up.

• low_quality: When set to 1, the quality of the stream has been significantly lowered to keep the average bitrate below the target ABR.

• very_low_quality: When set to 1, the quality of the stream has been lowered even more to keep the average bitrate below the target ABR. Used in tandem with low_quality when both are set to 1.

• high_bitrate: When set to 1, the stream’s average bitrate is higher than the target ABR, which means that more storage than originally defined by the target ABR multiplied by the retention time will be used, alternatively be reduced, depending on how the video is stored. Implies that both low_quality and very_low_quality are set to 1.

Several different properties can help you identifying the stream, including:

• scale_width and scale_height: The resolution of the stream.

• dynamic_gop: 1 if dynamic GOP is turned on.

• dynamic_fps: 1 if dynamic GOP is turned on.

• fps: The fps (frames per second) of the stream.

• default_gop_length: The GOP length of the stream.

• frame_skip_mode: 1 with empty frames, 0 with dropped frames.

• zipstream_mode: The zipstream strength. 0 if turned off.

• max_gop_length: The maximum GOP length when dynamic GOP is turned on.

• stream_profile: The combination of codec and profile: h264_baseline, h264_main, h264_high and h265_main.

• dynamic_fps_min_num: The minimum FPS when dynamic FPS is turned on.

<wstop:TopicSet>
  <tns1:VideoSource aev:NiceName="Video source">
    <tnsaxis:ABR wstop:topic="true" aev:NiceName="Average bitrate degradation">
      <aev:MessageInstance aev:isProperty="true">
        <aev:SourceInstance>
          <aev:SimpleItemInstance aev:NiceName="Video source configuration token" Type="xsd:int" Name="VideoSourceConfigurationToken">
            <aev:Value>1</aev:Value>
            <aev:Value>2</aev:Value>
            <aev:Value>3</aev:Value>
            <aev:Value>4</aev:Value>
            <aev:Value>5</aev:Value>
            <aev:Value>6</aev:Value>
            <aev:Value>7</aev:Value>
            <aev:Value>8</aev:Value>
          </aev:SimpleItemInstance>
        </aev:SourceInstance>
        <aev:DataInstance>
          <aev:SimpleItemInstance isPropertyState="true" aev:NiceName="abr error" Type="xsd:boolean" Name="abr error">
          </SimpleItemInstance>
        </aev:DataInstance>
      </aev:MessageInstance>
    </tnsaxis:ABR>
  </tns1:VideoSource>
</wstop:TopicSet>

Please note that the possible values of VideoSourceConfigurationToken will vary between products due to the different number of image sources.

Parameters set with param.cgi enable default parameters to be set for each image view. # is 0–N, where N is Properties.Image.NbrOfViews.

1. Variable bitrate
2. Maximum bitrate
3. Average bitrate

The MaxFrameSize parameter is used to limit the size of the I- and P-frames in a video stream. This means that unless no other bitrate limiting techniques are used, this parameter can be used to shape the network traffic and bitrate. The value can be entered in kilo bytes, for examples, if you set MaxFrameSize=85 (85kbyte/frame) to a video stream with a frame rate of 30 frames per second it will limit the overall bandwidth of the video stream to roughly 20–25 Mbit/s as the 30 frames becomes the desired maximum size of 85kbyte each translating to the corresponding network traffic.

These values can be read and written by either an administrator or an operator.

For the RTSP URL, default values from param.cgi can be overridden.

In general, when videobitratemode is set in the URL and a parameter that does not apply to that specific mode is also specified, a 400 Bad Request will be returned.