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”.
We plan to simplify the API as follows:
| 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 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).
The API becomes simpler and easier to work with and to understand.
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:
videomaxbitrate=2000
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.