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).

One 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. 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
ABR videoabrtargetbitrate

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

  • If any rate control option is specified in the URL, videobitratemode also has to be specified. With no rate control options in the URL, the value of Image.I#.RateControl.Mode will be used, together with the other channel defaults.
  • 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  to 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.

The 2nd bullet above puts a new restriction on how URL options can be combined with default values from param.cgi. This is an example of a request that has previously given a stream, but that will now give an error:


The reason is that a rate control URL option is specified, but not videobitratemode.

A common requirement is to construct requests that work with earlier versions of the Rate Control API. For API versions prior to 1.1, requests such as the following can be used for VBR and MBR: 

videomaxbitrate=0&videobitrate=0 (VBR)
videomaxbitrate=1000&videobitrate=1000 (MBR)

Setting videobitrate and videomaxbitrate in the requests will make sure Image.I#.RateControl.TargetBitrate and Image.I#.RateControl.MaxBitrate will not influence the used maximum bitrate. 1.0 does not have videobitratemode, and legacy behavior affects Image.I#.RateControl.Mode. If Mode=cbr, both TargetBitrate and MaxBitrate will apply—the lowest of the non-zero values will be used. If Mode=vbr, MaxBitrate will still apply. Therefore it's necessary to set both videobitrate and videomaxbitrate to ensure the wanted mode is achieved, for both MBR and VBR.

For API versions 1.1 and later, the following requests can be used:

videobitratemode=vbr (VBR)
videobitratemode=mbr&videomaxbitrate=1000 (MBR)
videobitratemode=abr&videoabrtargetbitrate=1000&videoabrmaxbitrate=2000 (ABR)

For 1.1, setting videobitratemode on the URL will force non-legacy mode, where MaxBitrate will not affect VBR and TargetBitrate will not affect MBR, therefore it's highly recommended to use it. 2.0 altogether removes the legacy modes.

More information