Controlling Archive File Size: quantizationParameter & maxBitrate Controlling Archive File Size: quantizationParameter & maxBitrate

Controlling Archive File Size: quantizationParameter & maxBitrate

Vonage API Support

Objective

Understand how to use the quantizationParameter (QP) and maxBitrate parameters to reduce the file size of composed archive recordings in the Vonage Video API.


Applies To

  • Vonage Video API

  • Composed Archive Recordings

  • REST API — Start Archive


Overview

By default, Vonage Video API composed archives are encoded using a constant quantization parameter (QP) of 19, which produces variable bitrate (VBR) video. This default setting prioritizes quality, which can result in larger file sizes — especially for high-resolution or high-motion content.

To give you more control over the trade-off between video quality and file size, two optional parameters are available when starting a composed archive:

Parameter

Type

Range

Encoding Mode

quantizationParameter

Number

15 – 40

VBR (Variable Bitrate)

maxBitrate

Number (bits/sec)

100,000 – 6,000,000

CBR (Constant Bitrate)

Important: You cannot use both quantizationParameter and maxBitrate in the same archive request. Specifying both will result in an error.


Parameter Details

quantizationParameter (QP)

The quantizationParameter controls the level of video compression applied during encoding. It uses Variable Bitrate (VBR) encoding, meaning the bitrate adjusts dynamically based on the complexity of the content — while maintaining a consistent perceptual quality level throughout the recording.

  • Lower QP value → finer compression → higher quality, larger file size

  • Higher QP value → coarser compression → smaller file size, lower quality

  • Default QP = 19 (highest quality, largest file)

  • Recommended range: 20–30 for a reasonable balance between quality and file size without a large perceptual quality difference

When to use QP: This is the recommended approach for most use cases. It is particularly well-suited for "talking heads" style recordings (e.g., video calls, interviews) where consistent quality throughout the recording is important, regardless of scene changes or motion.


maxBitrate

The maxBitrate parameter sets an upper limit on the video bitrate (in bits per second) for the archive. It uses Constant Bitrate (CBR) encoding, which enforces a fixed ceiling on the data rate.

  • Higher maxBitrate → better video quality → larger file size

  • Lower maxBitrate → smaller file size → potential quality degradation during fast motion or scene changes

  • Valid range: 100,000 to 6,000,000 bits per second

When to use maxBitrate: This is best suited when you need a hard cap on file size or have strict bandwidth/storage constraints. Be aware that CBR encoding can cause visible quality degradation during transitions and fast-moving content, as the encoder cannot allocate extra bits when needed.


File Size Reduction — Real World Results

The following results were observed using the same source video (1:1 "talking heads" session):

File

Size (MB)

Reduction

Notes

File1.mp4

19.6

0%

Default settings, VBR, QP = 19

File2.mp4

8.7

~55.6%

QP = 25, VBR

File3.mp4

9.1

~53.6%

maxBitrate = 1.2 Mbps, CBR

Note: The file size values above have been verified during internal testing conducted under specific conditions (1:1 "talking heads" session, 30 fps, best-fit layout). While these results are confirmed through testing, actual values are approximate and may vary in the course of real-world usage depending on factors such as content complexity, number of streams, motion levels, frame rate, network conditions, and available system resources. These figures should be treated as indicative estimates only and not as guaranteed outcomes.

These results demonstrate that both parameters can achieve approximately 50%+ reduction in file size with comparable perceptual quality for typical use cases.


Archive File Size by Resolution (Default Settings)

The following are approximate file sizes per minute for composed archives recorded at default settings (1:1 session, 30 fps, best-fit layout).

Note: The values in the tables below are approximate and are provided for reference purposes only. Actual file sizes may vary — either higher or lower — depending on factors such as content complexity, number of streams, frame rate, network conditions, and available system resources. These figures should not be considered as guaranteed or fixed benchmarks.

Composed Archive

Archive Resolution

Approximate Size per Minute

640x480 (SD Landscape)

~12 MB

480x640 (SD Portrait)

~7 MB

1280x720 (HD Landscape)

~40 MB

720x1280 (HD Portrait)

~10 MB

1920x1080 (FHD Landscape)

~80 MB

1080x1920 (FHD Portrait)

~28 MB

Individual Archive

Publisher Resolution

Approximate Size per Minute

640x480

~16 MB

1280x720

~50 MB

1920x1080

~85 MB

Note: Individual archives retain the original publisher stream resolution and are stored as a ZIP container with individual media files per stream.


Estimated File Size with maxBitrate Applied

Examples for a 60-minute (3,600 second) composed archive:

maxBitrate Setting

Estimated File Size (60 min)

6,000,000 bps (6 Mbps)

~2,700 MB (~2.7 GB)

3,000,000 bps (3 Mbps)

~1,350 MB (~1.35 GB)

1,200,000 bps (1.2 Mbps)

~540 MB

500,000 bps (500 kbps)

~225 MB

100,000 bps (100 kbps)

~45 MB

Note: The estimated file sizes above are approximate theoretical maximums based on the specified bitrate applied over the full duration. Actual file sizes may be lower, as CBR encoding does not always reach the configured ceiling — particularly for static or low-motion content. Results may also vary based on content type, system resource availability, and other environmental factors. These values should be used as planning estimates only and not as guaranteed storage requirements.


Key Constraints and Considerations

  • Both quantizationParameter and maxBitrate apply to composed archives only — they are not applicable to individual stream archives.

  • You cannot specify both parameters simultaneously — this will result in an error.

  • quantizationParameter and maxBitrate are optional — if neither is specified, the default behavior (VBR, QP = 19) is used.

  • The maxBitrate parameter is not available for automatically archived sessions (archiveMode: always). To use maxBitrate, you must start the archive manually via the REST API after a participant connects.

  • Values set at the Mantis (media router) configuration level act as a maximum ceiling — any value above the configured maximum for a given resolution will be ignored.

  • For FHD archives, a minimum maxBitrate of at least 2,000,000 bps is recommended to maintain acceptable quality.


Summary — Which Parameter Should I Use?

Use Case

Recommended Parameter

Reduce file size while maintaining consistent quality

quantizationParameter (QP 25–30)

Enforce a strict file size / storage budget

maxBitrate

Content with fast motion or frequent scene changes

quantizationParameter (CBR can degrade quality)

"Talking heads" / static content

Either parameter works well

Maximum file size reduction

Lower resolution + quantizationParameter


Additional Resources