@ExperimentalApi
class CodecDb


Recommends video encoder settings for the device your app is running on.

The same video encoder settings can produce noticeably different quality on different Android devices, because each device's chipset has its own hardware encoders. CodecDB contains measured quality data for the video encoders on many Android devices and chipsets. It uses this data to recommend a configuration (codec, encoder settings and bitrate) that meets your requirements on the current device, and to predict the quality of a configuration you already have. Quality is measured with VMAF, a score from 0 to 100 of how close the encoded video looks to the original.

To get a recommendation:

  1. Call onDevice, then forEncoding, to load the encoder data for the current device.
  2. Describe what you need with VideoEncoderConstraints: the resolution and frame rate, plus a target quality or a maximum bitrate. VideoEncoderConstraintsPresets provides starting points for common uses such as editing, camera recording, messaging and live streaming.
  3. Call findOptimalConfiguration and use the format and videoEncoderSettings of the returned configuration to configure the encoder.

CodecDB gives recommendations based on measurements of the exact device model and of the device's chipset. If those measurements can't meet the requested VideoEncoderConstraints, CodecDB falls back to measurements for devices in the same performance tier and to generic data. If none of these meet the constraints, CodecDB returns the result of the fallback passed to forEncoding.

Usage example

CodecDbEncoderDataset dataset = CodecDb.onDevice(context).forEncoding(constraints -> null);
VideoEncoderConfiguration config =
    dataset.findOptimalConfiguration(
        VideoEncoderConstraintsPresets.forEditing(1920, 1080, 30.0)
            .buildUpon()
            .setTargetQuality(VideoEncoderConstraints.QUALITY_LEVEL_GOOD)
            .build());
if (config != null) {
  // Configure the encoder with config.format and config.videoEncoderSettings.
}

Threading

onDevice and forEncoding read from and write to disk and should not be called on the main thread. A loaded CodecDbEncoderDataset doesn't change and can be queried from any thread, as long as the fallback passed to forEncoding is thread-safe.

Summary

Public functions

java-static CodecDbDatasetLoader!
onDevice(context: Context!)

Prepares the CodecDB database for the current device, returning a CodecDbDatasetLoader that can be used to load encoder datasets.

Public functions

onDevice

java-static fun onDevice(context: Context!): CodecDbDatasetLoader!

Prepares the CodecDB database for the current device, returning a CodecDbDatasetLoader that can be used to load encoder datasets.

This method performs blocking disk I/O and should not be called on the main thread.

The returned loader does not hold a database connection. Each forEncoding call opens the read-only database, loads the models it needs into memory, and closes the database before returning, so callers have nothing to clean up.

Parameters
context: Context!

The Android Context used to access application resources and database paths.

Returns
CodecDbDatasetLoader!

A CodecDbDatasetLoader configured for the current runtime device.

Throws
java.io.IOException

If the embedded database cannot be unpacked or read from disk.