Enabling Dolby Vision Capture in Android Mobile media apps

Oct 28, 2024
Knowledge

Title

URL Name

Dolby-Vision-Capture-on-Android-Mobile

Created By

kciec, 12/23/2024 8:21 PM

Last Modified By

kciec, 12/23/2024 8:29 PM

Validation Status

Validated

Publication Status

Published

Assigned To

Assigned By

Assignment Due Date

Article Content

This article provides a complete overview of how to enable Dolby Vision Capture in Android Mobile media apps.

When capturing Dolby Vision content, the process involves more than just the capture of the image. It also generates Dolby Vision metadata. This metadata, utilized during playback on Dolby Vision-enabled devices, ensures the most accurate reproduction of the original content, considering the capabilities of the specific display it's being played on.

As an Android developer, if you want to configure your application to support Dolby Vision Capture, it's important to understand the key parameters necessary to enable this workflow. The following sections outline the parameters required to set up Dolby Vision Capture within your Android app.

The following tutorial is the extension for Google's "HDR video capture" article.

Device prerequisites

To be capable of supporting Dolby Vision Capture capabilities, the device must meet the following requirements.

The device must be on Android 13 (API level 33) or later.
The device must have a video encoder that supports Dolby Vision.
The device must support the following DynamicRangeProfiles.
- any of Dolby Vision 10-bit profile (DOLBY_VISION_10B_HDR_OEM, DOLBY_VISION_10B_HDR_OEM_PO, DOLBY_VISION_10B_HDR_REF or DOLBY_VISION_10B_HDR_REF_PO).
- HLG10 profile (if 10-bit Dolby Vision profiles are unavailable).
The video preview must be displayed in SurfaceView.

Checking Dolby Vision Encoder Availability

The first step in this process is to verify if your device has a Dolby Vision encoder.

fun hasDolbyVisionEncoder(): Boolean {
    val list = MediaCodecList(MediaCodecList.ALL_CODECS)
    val format = MediaFormat()

    format.setString(MediaFormat.KEY_MIME,
                     MediaFormat.MIMETYPE_VIDEO_DOLBY_VISION)
    //Dolby Vision profile 8 
    format.setInteger(MediaFormat.KEY_PROFILE,
                      MediaCodecInfo.CodecProfileLevel.DolbyVisionProfileDvheSt)
    format.setInteger(MediaFormat.KEY_COLOR_TRANSFER,
                      MediaFormat.COLOR_TRANSFER_HLG)
    format.setInteger(MediaFormat.KEY_COLOR_STANDARD,
                      MediaFormat.COLOR_STANDARD_BT2020)
    
    if (list.findEncoderForFormat(format) != null) {
        return true
    }
    return false
}

Checking for 10-bit Dynamic Range Profile Support

Once you have confirmed your device supports Dolby Vision encoding, the next task is to see if it also supports 10-bit dynamic range profiles for the camera. Google provides a function isTenBitProfileSupported() in the "Check for HDR support" section to help you verify this.

Determining Dynamic Range Profile

Next, determine if the device supports any Dolby Vision dynamic range profiles.

fun isDolbyVisionSupported(cameraManager: CameraManager, cameraId: String): Boolean {
    if (isTenBitProfileSupported(cameraId)) {
        val dolbyVision10bitProfilesList = listOf( DynamicRangeProfiles.DOLBY_VISION_10B_HDR_OEM,
                                                   DynamicRangeProfiles.DOLBY_VISION_10B_HDR_OEM_PO,
                                                   DynamicRangeProfiles.DOLBY_VISION_10B_HDR_REF,
                                                   DynamicRangeProfiles.DOLBY_VISION_10B_HDR_REF_PO )
        val cameraCharacteristics = cameraManager.getCameraCharacteristics(cameraId)
        val availableProfiles = cameraCharacteristics.
            .get(CameraCharacteristics.REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES)!!
            .getSupportedProfiles()

        // Check for the desired profile, in this case any of DOLBY_VISION_10B_*
        if(dolbyVision10bitProfilesList.any { it in availableProfiles }) {
            return true
        }
    }
    return false
}

If no Dolby Vision 10-bit dynamic range profiles are available, check if your device supports Hybrid Log Gamma (HLG10). HLG10 can be an alternative if Dolby Vision profiles are unavailable.

Google describes the isHLGSupported() function in the "Check for HDR support" section to verify HLG10 support.

Setting Up Dolby Vision Capture

With device compatibility confirmed, you can now set up your app to capture Dolby Vision content. Refer to Google's "Set up HDR capture" section for sample code. Simply pass the correct dynamic range profile (either DOLBY_VISION_10B_* or HLG10) to the setupSessionWithDynamicRangeProfiles() method.

Encoding The Camera Stream

To finalize the process, encode the camera stream using MediaCodec. You'll need to configure encoding parameters via MediaFormat to get the Dolby Vision profile 8.4 bitstream.

val videoResolution = Size(width, height)
//create MediaFormat
val format = MediaFormat.createVideoFormat(MIMETYPE_VIDEO_DOLBY_VISION,
                                           videoResolution.width,
                                           videoResolution.height)
//set Dolby Vision profile 8
format.setInteger(MediaFormat.KEY_PROFILE,
                  MediaCodecInfo.CodecProfileLevel.DolbyVisionProfileDvheSt)
//set transfer characteristic to Hybrid Log-Gamma (HLG)
format.setInteger(MediaFormat.KEY_COLOR_TRANSFER, 
                  MediaFormat.COLOR_TRANSFER_HLG)
//set BT.2020 color space
format.setInteger(MediaFormat.KEY_COLOR_STANDARD, 
                  MediaFormat.COLOR_STANDARD_BT2020)
//set color range to limited
format.setInteger(MediaFormat.KEY_COLOR_RANGE, 
                  MediaFormat.COLOR_RANGE_LIMITED)
format.setInteger(MediaFormat.KEY_COLOR_FORMAT,
                  MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface)

//calculate Dolby Vision level based on the output video frame rate and resolution
val level
if (videoResolution.height == 1920 || videoResolution.width == 1920) {
    level = when {
        (fps <= 24)             -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelFhd24
        (fps > 24 && fps <= 30) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelFhd30
        (fps > 30 && fps <= 60) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelFhd60
        else                    -> throw IllegalArgumentException("Unsupported frame rate")
    }
} else if (videoResolution.height == 3840 || videoResolution.width == 3840) {
    level = when {
        (fps <= 24)             -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelUhd24
        (fps > 24 && fps <= 30) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelUhd30
        (fps > 30 && fps <= 48) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelUhd48
        (fps > 48 && fps <= 60) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelUhd60
        (fps > 60 && fps <= 120)-> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevelUhd120
        else                    -> throw IllegalArgumentException("Unsupported frame rate")
    }
} else if (videoResolution.height == 7680 || videoResolution.width == 7680) {
    level = when {
        (fps <= 30)             -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevel8k30
        (fps > 30 && fps <= 60) -> MediaCodecInfo.CodecProfileLevel.DolbyVisionLevel8k60
         else                   -> throw IllegalArgumentException("Unsupported frame rate")
    }
} else {
    throw IllegalArgumentException("Unsupported resolution")
}

//set Dolby Vision level
format.setInteger(MediaFormat.KEY_LEVEL, level)
//add other parameters (e.g. bit rate, frame rate, etc) depending on your needs
format.setInteger(MediaFormat.KEY_BIT_RATE, bitrate);
format.setInteger(MediaFormat.KEY_FRAME_RATE, fps);
(...)

mediaCodec.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)

Verifying of the output file

You may be wondering how to confirm whether the changes you made to adapt the application for Dolby Vision support are functioning correctly. We have prepared a guide that will assist you in verifying the processed Dolby Vision content. Check out this article to learn more.