DRM

To play DRM-protected content additional DRM configuration is needed and it differs based on the DRM solution you are using. Different DRM solutions are supported out of the box via so called DRM environments.

Note that to be able to play DRM-protected content your website must be served over HTTPS. For testing purposes on localhost HTTPS is not required.

DRM with DRMtoday

Our player SDK comes with a pre-configured DRMtoday environment out of the box.

To use the DRMtoday environment, set the environment field in the DrmConfiguration to DRMtoday and specify additional settings using the customData object. For example:

const playerConfiguration = {
  autoPlay: true,
  source: {
    /* ... */
  },
  drm: {
    environment: "DRMtoday",
    customData: {
      userId: "YOUR_USER_ID",
      sessionId: "YOUR_SESSIO_ID",
      merchant: "YOUR_MERCHANT",
    } as DrmTodayCustomData,
  },
};

The customData object must adhere to the DrmTodayCustomData type and is used to configure DRMtoday-specific settings. At a minimum, the userId, sessionId, and merchant fields should be provided.

Note that there are two additional environments available for the DRMtoday platform: DRMtoday_STAGING and DRMtoday_TEST. DRMtoday_STAGING points to the staging environment, and DRMtoday_TEST points to the test environment. These environments are for testing purposes and should not be used in production.

DRM with Verimatrix

Our player SDK comes with a pre-configured Verimatrix environment out of the box.

To use the Verimatrix environment, set the environment field in the DrmConfiguration to Verimatrix and specify additional settings using the customData object. For example:

const playerConfiguration = {
  autoPlay: true,
  source: {
    /* ... */
  },
  drm: {
    environment: "Verimatrix",
    customData: {
      deviceId: "YOUR_DEVICE_ID",
      widevineLicenseUrl: "YOUR_WIDEVINE_LICENSE_URL",
      playReadyLicenseUrl: "YOUR_PLAYREADY_LICENSE_URL",
      fairPlayLicenseUrl: "YOUR_FAIRPLAY_LICENSE_URL",
      fairPlayCertificateUrl: "YOUR_FAIRPLAY_CERTIFICATE_URL",
    } as VerimatrixCustomData,
  },
};

The customData object must adhere to the VerimatrixCustomData type and is used to configure Verimatrix-specific settings. It must include a deviceId, which serves as a unique identifier for the device. Additionally, the configuration should specify the license URLs for the targeted DRM systems.

DRM with custom DRM environment

Create a custom DRM environment if you need full control over the license acquisition process.

In order to do this, you have to create your own DrmEnvironment instance, which should be configured for various DRM systems and later registered to global scope via DrmEnvironmentRepository.register.

For further explanation of possible DRM system configurations, please refer to:

Example setup of a custom DRM environment can look like this:

const myDRM: DrmEnvironment = {
    name: 'myDRM',
    widevine: {
        getLicenseUrl: () =>
        'https://lic.staging.drmtoday.com/license-proxy-widevine/cenc/',
        getCertificateUrl: () =>
        'https://lic.staging.drmtoday.com/license-proxy-widevine/cenc/',
        licenseRequest: widevineLicenseRequestModifier,
        licenseResponse: widevineLicenseResponseModifier,
        certificateRequest: widevineLicenseRequestModifier,
        certificateResponse: widevineLicenseResponseModifier,
    },
    fairplay: { ... },
    playready: { ... },

};

DrmEnvironmentRepository.register(myDRM);

To use the custom environment, set the environment field in the DrmConfiguration to the custom DRM environment name and specify additional settings using the customData object. For example:

const playerConfiguration = {
  autoPlay: true,
  source: {
    /* ... */
  },
  drm: {
    environment: "myDRM",
    customData: {
      // optional data that might be needed by custom DRM environment
    }
  },
};

Offline DRM license prefetching

When downloading DRM-protected content for offline playback, the media files are stored on the device but the DRM license must also be acquired and stored separately. Without a stored license the downloaded content cannot be played back without a network connection.

The Downloader plugin exposes two methods on Download to manage offline licenses:

Download.storeOfflineDrmLicense — acquires a license from the license server and persists it on the device.
Download.deleteOfflineDrmLicense — removes the stored license from the device.

Both methods require the download to have a DRM configuration (i.e. the content is DRM-protected). They throw a PrestoPlayError if the download has no DRM configuration or if license acquisition fails.

import { DownloadService } from "@castlabs/react-native-prestoplay-downloader";

const download = await DownloadService.getInstance().getDownload("<DOWNLOAD_ID>");

if (download) {
  // Store an offline license so the content can be played without network
  await download.storeOfflineDrmLicense();

  // Later, remove the stored license (e.g. when the user logs out)
  await download.deleteOfflineDrmLicense();
}

Tracking offline license state

Use Download.getDrmOfflineState to read the current license state, or the useDrmOfflineState hook to keep a React component in sync with state changes.

import {
  DrmOfflineState,
} from "@castlabs/react-native-prestoplay";
import {
  useDrmOfflineState,
} from "@castlabs/react-native-prestoplay-downloader";

function DownloadItem({ download }) {
  const drmOfflineState = useDrmOfflineState(download);

  if (drmOfflineState === DrmOfflineState.NoDrm) {
    return <Text>No DRM — ready for offline playback</Text>;
  }

  if (drmOfflineState === DrmOfflineState.DrmProtected) {
    return (
      <Button onPress={() => download.storeOfflineDrmLicense()}>
        Store offline license
      </Button>
    );
  }
}

The DrmOfflineState enum has two values:

Value	Description
`NoDrm`	Content is not DRM-protected. No license management needed.
`DrmProtected`	Content is DRM-protected. Use `storeOfflineDrmLicense` / `deleteOfflineDrmLicense` to manage the offline license.

Android: `forceSingleDrmSession`

Some Widevine license servers require a single DRM session to be used for both license acquisition and decryption. If offline license prefetching fails on Android, try enabling the forceSingleDrmSession flag when initializing the SDK:

import { Sdk } from "@castlabs/react-native-prestoplay";

Sdk.initialize({
  licenseKey: { /* ... */ },
  androidSdkConfiguration: {
    forceSingleDrmSession: true,
  },
});

See the Android SDK documentation for more details on this flag.

Table of contents​

DRM with DRMtoday​

DRM with Verimatrix​

DRM with custom DRM environment​

Offline DRM license prefetching​

Tracking offline license state​

Android: forceSingleDrmSession​

Table of contents