The new video capture constraints API allows you to specify "constraints" when capturing videos. Constraints include:

  1. Video Quality (High or Low)

  2. Maximum duration

  3. Most file size

  4. Video Resolution (that is, width and height).

Support for these constraints vary by platform and device, but the API allows you to check if your constraints are supported at runtime. Essentially, you set your "preferred" constraints, and the API will give you its best try at meeting those constraints. This is like setting a visual Component’s preferred width and height. The layout manager takes these preferred dimensions under advisement, but sets the size on its own.

Example 1: Capturing a Low-Quality 5-Second clip

Suppose you want to allow the user to capture a short (5 second) clip, in a low resolution, appropriate for sharing on a social media platform. You create your VideoCaptureConstraints object as follows:

// The original wrote "new VideoCaptureConstraint()" -- a class that does
// not exist. Corrected while restoring it: a snippet that cannot compile is
// worse than no snippet.
VideoCaptureConstraints cnst = new VideoCaptureConstraints()
    .preferredQuality(VideoCaptureConstraints.QUALITY_LOW)
    .preferredMaxLength(5);

This constraint can then be passed to Capture.captureVideo() to get the captured file:

String videoPath = Capture.captureVideo(cnst);

Not all platforms support all constraints

How do you know whether your constraints will be honored? When the platform doesn’t support the maximum length, you may want to take a different path. Ask the constraint object whether it’s supported.

For example:

if (cnst.isMaxLengthSupported()) {
    // The max length constraint we specified is supported on this platform.
} else {
    // It is not. Check the effective value to see whether it is partially
    // supported.
    int effectiveMaxLength = cnst.getMaxLength();
    if (effectiveMaxLength == 0) {
        // Not supported at all: the user can capture without a duration limit.
    } else {
        // Set to a different value than preferredMaxLength asked for, so the
        // platform is at least trying to accommodate us.
    }
}

You can probe a constraint to see whether the entire constraint is supported (that is, whether it will be obeyed), or whether any particular aspect of it will be supported using the following methods:

  • isSupported() - True if all preferred constraints are supported.

  • isQualitySupported() - True if the preferred quality setting is supported.

  • isMaxLengthSupported() - True if the max length setting is supported.

  • isMaxFileSizeSupported() - True if the max file size setting is supported.

  • isSizeSupported() - True if the specified preferred width and height constraints are supported.

Example 2: Specifying explicit width and height

Suppose you want to capture a video with resolution 320×240. You would begin with this constraint:

VideoCaptureConstraints cnst = new VideoCaptureConstraints()
    .preferredWidth(320)
    .preferredHeight(240);

Explicit width and height constraints aren’t well-supported across platforms. Android doesn’t support them at all. iOS supports 3 specific sizes. JavaScript supports it when running on a desktop browser or on Android - but not on iOS. Etc.

Find out if this constraint will be obeyed:

if (cnst.isSizeSupported()) {
    // This platform supports the constraint, so the captured video will be
    // exactly 320x240.
} else {
    // Not supported -- see whether the platform will get close.
    int effectiveWidth = cnst.getWidth();
    int effectiveHeight = cnst.getHeight();
    int quality = cnst.getQuality();
    if (effectiveWidth == 0 && effectiveHeight == 0) {
        // No control over width and height. In many cases the platform will
        // approximate with the quality setting instead.
        if (quality != 0) {
            // Quality was set for us. Since 320x240 is small, it would
            // probably be QUALITY_LOW.
        }
    } else {
        // Could not capture at 320x240, but supplied the closest size it can.
    }
}

Constraint support by platform

PlatformSizeQualityMax LengthMax File Size

iOS

Limited

Yes

Yes

No

Android

No*

Yes

Yes

Yes

Simulator/Java SE

No

No

No

No

JavaScript (Desktop)

Yes

Yes

Yes

No

JavaScript (Android)

Yes

Yes

Yes

No

JavaScript (iOS)

No

No

No

No

* If size is specified, the platform will try to translate to the appropriate quality constraint.