Simplified Rate Control API

January 3, 2023

As the VAPIX Rate Control API has evolved over the years, the relationship between some of the URL options and param.cgi parameters has become complicated. In some cases, e.g. with Image.I#.RateControl.Mode, the behaviour is different if the setting is provided using the param.cgi parameter, or using the corresponding URL option (videobitratemode in this case).

An example is a request with videobitrate=2000 as the only URL option. That gives MBR, even if  Image.I#.RateControl.Mode would be set to ”vbr”.

What will change?

We plan to simplify the API as follows:

  • Mode is the primary setting. It is selected using the videobitratemode URL option. If the option is omitted in the request, the value of Image.I#.RateControl.Mode will be used.
  • The chosen mode determines what of the other URL options and parameters have effect, according to the following table:
Mode URL option param.cgi parameters
VBR None None
MBR videomaxbitrate
videobitratepriority		 Image.I#.RateControl.MaxBitrate
Image.I#.RateControl.Priority
ABR videoabrtargetbitrate
videoabrmaxbitrate
videoabrretentiontime		 Image.I#.RateControl.ABR.TargetBitrate
Image.I#.RateControl.ABR.MaxBitrate
Image.I#.RateControl.ABR.RetentionTime

In each case, the param.cgi parameter with the channel default will be used if the corresponding URL option is not provided.

  • The videobitrate URL option has no effect.
  • The Image.I#.RateControl.TargetBitrate parameter has no effect.
  • The value ”cbr” in Image.I#.RateControl.Mode continues to be deprecated and has the same effect as MBR.
     

The new API is supported by the product when Properties.Image.RateControl.Version is 2.0 and higher.

videobitrate and Image.I#.RateControl.TargetBitrate are deprecated from now on, but the changes will be made in the first release after the next LTS.

No changes are made when it comes to Average Bitrate (ABR).

What are the benefits of this change?

The API becomes simpler and easier to work with and understand.

What should be taken into consideration when doing an integration?

Clients are advised to always set the desired rate control mode, using videobitratemode or Image.I#.RateControl.Mode. Already today, that will give the expected behaviour.

For MBR, the maximum bitrate should be specified using videomaxbitrate or Image.I#.RateControl.MaxBitrate.

A common requirement is to construct a request that works with all versions of the Rate Control API. For MBR, this could be

videobitratemode=mbr&videomaxbitrate=1000&videobitrate=1000

Prior to version 1.1

  • videobitratemode is not supported. It will be ignored and not cause any error.
  • videobitrate in the request will make sure Image.I#.RateControl.TargetBitrate will not influence the used maximum bitrate. (For non-zero TargetBitrate, the maximum bitrate would otherwise be the lowest of TargetBitrate and videomaxbitrate).
     

For version 1.1 and later, videobitratemode will give MBR. For version 2.0 and later, videobitrate will be ignored.

More information

To top