In this guide, we’ll discuss ways to implement Dolby Vision playback in Android Mobile media apps.

For a basic understanding of the HDR video playback on Android devices, review Google's article "HDR video playback". This guide presents an overview of the general approach to HDR video playback, and although it's not Dolby Vision-specific, the principles, and techniques are also applicable to handling Dolby Vision content.

Additionally, for a better understanding of this topic, it’s worth reviewing the description of the Dolby Vision decoding pipeline on Android.

Detecting Dolby Vision Playback Capabilities on Android

There are several key elements required for successful Dolby Vision playback: 

• The device must be on Android 7.0 (API level 24) or higher.
• The video decoder must be capable of decoding a Dolby Vision bitstream.
• The display must be Dolby Vision compatible. 

Determining Dolby Vision Decoder

To determine if the Dolby Vision decoder is available on the device, you need to use the findDecoderForFormat method, which is available within the MediaCodecList class.

NOTE: While the createDecoderByType(String) method allows for decoder selection, it is not recommended due to its limited ability to specify additional parameters. It selects a decoder based on the MIME type only, which may not be sufficient to identify the appropriate decoder for HDR formats. Google recommends using  MediaCodecList.findDecoderForFormat and createByCodecName(String) methods to ensure the decoder can correctly handle the given format.

If you already have the media stream or file available, you can determine whether a decoder supporting given video format is implemented on the device. The workflow involves retrieving information about available decoders and finding one that supports the given format extracted from the Dolby Vision source file.

An example code snippet demonstrating how to determine and create a Dolby Vision decoder based on the media format can be found below.

MediaCodecList mediaCodecList = new MediaCodecList(MediaCodecList.REGULAR_CODECS);
MediaExtractor mediaExtractor = new MediaExtractor();
MediaFormat mediaFormat = null;

mediaExtractor.setDataSource(filePath);

for (int i = 0; i < mediaExtractor.getTrackCount(); i++) {
  String mimeType = mediaExtractor.getTrackFormat(i).getString(MediaFormat.KEY_MIME);
  //Check if this is a Dolby Vision track
  if (mimeType.equals(MediaFormat.MIMETYPE_VIDEO_DOLBY_VISION)) {
    //Get the complete media format from the media file
    mediaFormat = mediaExtractor.getTrackFormat(i);
    mediaExtractor.selectTrack(i);
    break;
  }
}

if(mediaFormat != null) {
  String codecName = mediaCodecList.findDecoderForFormat(mediaFormat);
  //Check if any decoder supporting Dolby Vision has been found
  //and if the display supports Dolby Vision format
  if(codecName != null && doesDisplaySupportDolbyVision()) {
    MediaCodec decoder = MediaCodec.createByCodecName(codecName);
    //Next, use standard MediaCodec playback flow
  } else {
    //The device doesn't support decoding of this Dolby Vision profile
  }
}

Checking Display Capabilities

If the device meets the decoder requirements, you can move on to the second step, which is to determine whether a display that supports Dolby Vision is available. Based on the HDR capabilities of the display, you need to verify that it supports HDR_TYPE_DOLBY_VISION.

The method below checks the display’s ability to support Dolby Vision.

public boolean doesDisplaySupportDolbyVision() {
  //Retrieve the display linked to the current context
  Display screen = this.context.getDisplay();

  // Retrieve the HDR capabilities of the display
  Display.HdrCapabilities capabilities = screen.getHdrCapabilities();

  //Check if Dolby Vision is included in the supported HDR types
  //Return true if Dolby Vision is supported, false otherwise.
  return !(Arrays.stream(capabilities.getSupportedHdrTypes()).
      filter(x -> x == Display.HdrCapabilities.HDR_TYPE_DOLBY_VISION).
      boxed().
      collect(Collectors.toCollection(ArrayList::new)).isEmpty());
}

Playback with ExoPlayer

The simplest option to enable Dolby Vision playback in your application is to use the Media3 ExoPlayer.

ExoPlayer supports Dolby Vision playback by default, but if you’ve been using it in your app so far, make sure you have configured SurfaceView as the layer for displaying video (you can find more on this topic in the "Android HDR | Migrating from TextureView to SurfaceView" article).

NOTE: If your application uses ExoPlayer version 2.x, we recommend updating it to at least version 2.18. However, keep in mind that ExoPlayer is continuously evolving along with Dolby Vision advancements, so plan an update to the latest version of Media3 to ensure the best user experience for your app. If you’re curious about how to do it, here’s the ExoPlayer Media3 migration guide from Google.

Playback with MediaCodec via SurfaceView

More advanced option with better control over the video decoding and rendering is to use MediaCodec via SurfaceView (as described in "Set up MediaCodec using SurfaceView" Google's article).

Configure the Dolby Vision playback pipeline the same way as  supporting other HDR formats.