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”.
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 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.
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
For version 1.1 and later, videobitratemode will give MBR. For version 2.0 and later, videobitrate will be ignored.