Work with MediaPlayer and Digital Rights Management (DRM)

Starting with Android 8.0 (API level 26), MediaPlayer includes APIs that support the playback of DRM-protected material. The MediaPlayer DRM APIs are similar to the low-level API provided by MediaDrm, but they operate at a higher level and don't expose the underlying extractor, DRM, and crypto objects.

Although the MediaPlayer DRM API does not provide the full functionality of MediaDrm, it supports the most common use cases. The current implementation can handle the following content types:

• Widevine-protected local media files
• Widevine-protected remote or streaming media files

The following code snippet demonstrates how to use the new DRM MediaPlayer methods in a synchronous implementation.

To manage DRM-controlled media, you need to include the new methods alongside the usual flow of MediaPlayer calls, as shown in this example:

mediaPlayer?.apply {
    setDataSource()
    setOnDrmConfigHelper() // optional, for custom configuration
    prepare()
    drmInfo?.also {
        prepareDrm()
        getKeyRequest()
        provideKeyResponse()
    }

    // MediaPlayer is now ready to use
    start()
    // ...play/pause/resume...
    stop()
    releaseDrm()
}

setDataSource();
setOnDrmConfigHelper(); // optional, for custom configuration
prepare();
if (getDrmInfo() != null) {
  prepareDrm();
  getKeyRequest();
  provideKeyResponse();
}

// MediaPlayer is now ready to use
start();
// ...play/pause/resume...
stop();
releaseDrm();

Start by initializing the MediaPlayer object and setting its source using setDataSource(), as usual. Then, to use DRM, perform these steps:

1. If you want your app to perform custom configuration, define an OnDrmConfigHelper interface, and attach it to the player using setOnDrmConfigHelper().
2. Call prepare().
3. Call getDrmInfo(). If the source has DRM content, the method returns a non-null MediaPlayer.DrmInfo value.

If MediaPlayer.DrmInfo exists:

1. Examine the map of available UUIDs and choose one.
2. Prepare the DRM configuration for the current source by calling prepareDrm().
   • If you created and registered an OnDrmConfigHelper callback, it is called while prepareDrm() is executing. This lets you perform custom configuration of the DRM properties before opening the DRM session. The callback is called synchronously in the thread that called prepareDrm(). To access the DRM properties, call getDrmPropertyString() and setDrmPropertyString(). Avoid performing lengthy operations.
   • If the device has not yet been provisioned, prepareDrm() also accesses the provisioning server to provision the device. This can take a variable amount of time, depending on the network connectivity.
3. To get an opaque key request byte array to send to a license server, call getKeyRequest().
4. To inform the DRM engine about the key response received from the license server, call provideKeyResponse(). The result depends on the type of key request:
   • If the response is for an offline key request, the result is a key-set identifier. You can use this key-set identifier with restoreKeys() to restore the keys to a new session.
   • If the response is for a streaming or release request, the result is null.

Prepare DRM asynchronously

By default, prepareDrm() runs synchronously, blocking until preparation finishes. However, the very first DRM preparation on a new device may also require provisioning, which prepareDrm() handles internally, and may take some time to finish due to the network operation involved. You can avoid blocking on prepareDrm() by defining and setting a MediaPlayer.OnDrmPreparedListener.

Set an OnDrmPreparedListener. prepareDrm() performs the provisioning (if needed) and preparation in the background. When provisioning and preparation finish, the system calls the listener. Don't make any assumptions about the calling sequence or the thread in which the listener runs (unless you register the listener with a handler thread). The system can call the listener before or after prepareDrm() returns.

Set up DRM asynchronously

You can initialize the DRM asynchronously by creating and registering the MediaPlayer.OnDrmInfoListener for DRM preparation and the MediaPlayer.OnDrmPreparedListener to start the player. They work in conjunction with prepareAsync(), as shown in this example:

setOnPreparedListener()
setOnDrmInfoListener()
setDataSource()
prepareAsync()
// ...

// If the data source content is protected you receive a call to the onDrmInfo() callback.
override fun onDrmInfo(mediaPlayer: MediaPlayer, drmInfo: MediaPlayer.DrmInfo) {
    mediaPlayer.apply {
        prepareDrm()
        getKeyRequest()
        provideKeyResponse()
    }
}

// When prepareAsync() finishes, you receive a call to the onPrepared() callback.
// If there is a DRM, onDrmInfo() sets it up before executing this callback,
// so you can start the player.
override fun onPrepared(mediaPlayer: MediaPlayer) {
    mediaPlayer.start()
}

setOnPreparedListener();
setOnDrmInfoListener();
setDataSource();
prepareAsync();
// ...

// If the data source content is protected you receive a call to the onDrmInfo() callback.
onDrmInfo() {
  prepareDrm();
  getKeyRequest();
  provideKeyResponse();
}

// When prepareAsync() finishes, you receive a call to the onPrepared() callback.
// If there is a DRM, onDrmInfo() sets it up before executing this callback,
// so you can start the player.
onPrepared() {

start();
}

Handle encrypted media

Starting with Android 8.0 (API level 26) MediaPlayer can also decrypt Common Encryption Scheme (CENC) and HLS sample-level encrypted media (METHOD=SAMPLE-AES) for the elementary stream types H.264, and AAC. Full-segment encrypted media (METHOD=AES-128) was previously supported.

Learn more

Jetpack Media3 is the recommended solution for media playback in your app. Read more about it.

These pages cover topics relating to recording, storing, and playing back audio and video:

• Supported Media Formats
• MediaRecorder
• Data Storage