QualitySelector

public final class QualitySelector

QualitySelector defines a desired quality setting that can be used to configure components with quality setting requirements such as creating a Recorder.

There are pre-defined quality constants that are universally used for video, such as SD, HD, FHD and UHD, but not all of them are supported on every device since each device has its own capabilities. isQualitySupported can be used to check whether a quality is supported on the device or not and getResolution can be used to get the actual resolution defined in the device. Aside from checking the qualities one by one, QualitySelector provides a more convenient way to select a quality. The typical usage of selecting a single desired quality is: 

  QualitySelector qualitySelector = QualitySelector.from(Quality.FHD);
or the usage of selecting a series of qualities by desired order: 
  QualitySelector qualitySelector = QualitySelector.fromOrderedList(
          Arrays.asList(Quality.FHD, Quality.HD, Quality.HIGHEST)
  );
The recommended way is giving a guaranteed supported quality such as LOWEST or HIGHEST in the end of the desired quality list, which ensures the QualitySelector can always choose a supported quality. Another way to ensure a quality will be selected when none of the desired qualities are supported is to use fromOrderedList with an open-ended fallback strategy such as a fallback strategy from lowerQualityOrHigherThan: 
  QualitySelector qualitySelector = QualitySelector.fromOrderedList(
          Arrays.asList(Quality.UHD, Quality.FHD),
          FallbackStrategy.lowerQualityOrHigherThan(Quality.FHD)
  );
If UHD and FHD are not supported on the device, QualitySelector will select the quality that is closest to and lower than FHD. If no lower quality is supported, the quality that is closest to and higher than FHD will be selected.

Summary

Public methods
static @NonNull QualitySelector
from(@NonNull Quality quality)

Gets an instance of QualitySelector with a desired quality.
static @NonNull QualitySelector
from(@NonNull Quality quality, @NonNull FallbackStrategy fallbackStrategy)

Gets an instance of QualitySelector with a desired quality and a fallback strategy.
static @NonNull QualitySelector

Gets an instance of QualitySelector with ordered desired qualities.
static @NonNull QualitySelector
fromOrderedList(
    @NonNull List<Quality> qualities,
    @NonNull FallbackStrategy fallbackStrategy
)

Gets an instance of QualitySelector with ordered desired qualities and a fallback strategy.
static @Nullable Size
getResolution(@NonNull CameraInfo cameraInfo, @NonNull Quality quality)

Gets the corresponding resolution from the input quality.
static @NonNull List<Quality>

This method is deprecated.

use getSupportedQualities instead.
static boolean
isQualitySupported(
    @NonNull CameraInfo cameraInfo,
    @NonNull Quality quality
)

This method is deprecated.

use isQualitySupported instead.
@NonNull String

Public methods

from

Added in 1.1.0
public static @NonNull QualitySelector from(@NonNull Quality quality)

Gets an instance of QualitySelector with a desired quality.

Parameters
@NonNull Quality quality

the quality. Possible values include LOWEST, HIGHEST, SD, HD, FHD, or UHD.
Returns
@NonNull QualitySelector

the QualitySelector instance.
Throws
java.lang.NullPointerException

if quality is null.
java.lang.IllegalArgumentException

if quality is not one of the possible values.

from

Added in 1.1.0
public static @NonNull QualitySelector from(@NonNull Quality quality, @NonNull FallbackStrategy fallbackStrategy)

Gets an instance of QualitySelector with a desired quality and a fallback strategy.

If the quality is not supported, the fallback strategy will be applied. The fallback strategy can be created by FallbackStrategy API such as lowerQualityThan.

Parameters
@NonNull Quality quality

the quality. Possible values include LOWEST, HIGHEST, SD, HD, FHD, or UHD.
@NonNull FallbackStrategy fallbackStrategy

the fallback strategy that will be applied when the device does not support quality.
Returns
@NonNull QualitySelector

the QualitySelector instance.
Throws
java.lang.NullPointerException

if quality is null or fallbackStrategy is null.
java.lang.IllegalArgumentException

if quality is not one of the possible values.

fromOrderedList

Added in 1.1.0
public static @NonNull QualitySelector fromOrderedList(@NonNull List<Quality> qualities)

Gets an instance of QualitySelector with ordered desired qualities.

The final quality will be selected according to the order in the quality list.

Parameters
@NonNull List<Quality> qualities

the quality list. Possible values include LOWEST, HIGHEST, SD, HD, FHD, or UHD.
Returns
@NonNull QualitySelector

the QualitySelector instance.
Throws
java.lang.NullPointerException

if qualities is null.
java.lang.IllegalArgumentException

if qualities is empty or contains a quality that is not one of the possible values, including a null value.

fromOrderedList

Added in 1.1.0
public static @NonNull QualitySelector fromOrderedList(
    @NonNull List<Quality> qualities,
    @NonNull FallbackStrategy fallbackStrategy
)

Gets an instance of QualitySelector with ordered desired qualities and a fallback strategy.

The final quality will be selected according to the order in the quality list. If no quality is supported, the fallback strategy will be applied. The fallback strategy can be created by FallbackStrategy API such as lowerQualityThan.

Parameters
@NonNull List<Quality> qualities

the quality list. Possible values include LOWEST, HIGHEST, SD, HD, FHD, or UHD.
@NonNull FallbackStrategy fallbackStrategy

the fallback strategy that will be applied when the device does not support those qualities.
Throws
java.lang.NullPointerException

if qualities is null or fallbackStrategy is null.
java.lang.IllegalArgumentException

if qualities is empty or contains a quality that is not one of the possible values, including a null value.

getResolution

Added in 1.1.0
public static @Nullable Size getResolution(@NonNull CameraInfo cameraInfo, @NonNull Quality quality)

Gets the corresponding resolution from the input quality.

Possible values for quality include LOWEST, HIGHEST, SD, HD, FHD and UHD.

Parameters
@NonNull CameraInfo cameraInfo

the cameraInfo for checking the quality.
@NonNull Quality quality

one of the quality constants.
Returns
@Nullable Size

the corresponding resolution from the input quality, or null if the quality is not supported on the device. isQualitySupported can be used to check if the input quality is supported.
Throws
java.lang.IllegalArgumentException

if quality is not one of the possible values.
See also
isQualitySupported

getSupportedQualities

Added in 1.1.0
Deprecated in 1.3.0
public static @NonNull List<Quality> getSupportedQualities(@NonNull CameraInfo cameraInfo)

Gets all supported qualities on the device.

The returned list is sorted by quality size from largest to smallest. For the qualities in the returned list, with the same input cameraInfo, isQualitySupported will return true and getResolution will return the corresponding resolution.

Note: Constants HIGHEST and LOWEST are not included in the returned list, but their corresponding qualities are included.

Parameters
@NonNull CameraInfo cameraInfo

the cameraInfo

isQualitySupported

Added in 1.1.0
Deprecated in 1.3.0
public static boolean isQualitySupported(
    @NonNull CameraInfo cameraInfo,
    @NonNull Quality quality
)

Checks if the quality is supported.

Calling this method with one of the qualities contained in the returned list of getSupportedQualities will return true.

Possible values for quality include LOWEST, HIGHEST, SD, HD, FHD and UHD.

If this method is called with LOWEST or HIGHEST, it will return true except the case that none of the qualities can be supported.

Parameters
@NonNull CameraInfo cameraInfo

the cameraInfo for checking the quality.
@NonNull Quality quality

one of the quality constants.
Returns
boolean

true if the quality is supported; false otherwise.
See also
getSupportedQualities

toString

public @NonNull String toString()