DRM Configuration

NOTE: EME and http URLs

EME requires a secure URL to use. This means you have to use https or be on localhost. Currently only Chrome enforces it, but other browsers will in the future. Also, because of mixed content requirements, if your site is using https, then your manifest and every segment will also need to use https too.

See: Chrome's announcement, Firefox's intent to remove, and how to disable for testing.

License Servers

Without DRM configuration, Shaka only plays clear content. To play protected content, the application only needs to tell Shaka one basic thing: the URL(s) of its license server(s).

We've made this simple through player.configure(). The field drm.servers is an object mapping key system IDs to server URLs. For example, to set license servers for both Widevine and Playready:

player.configure({
  drm: {
    servers: {
      'com.widevine.alpha': 'https://foo.bar/drm/widevine',
      'com.microsoft.playready': 'https://foo.bar/drm/playready'
    }
  }
});

Assuming your manifest uses the standard UUIDs for those key systems, that's all you need to do.

Choosing a Key System

Shaka Player is key-system-agnostic, meaning we don't prefer any key systems over any others. We use EME to ask the browser what it supports, and make no assumptions. If your browser supports multiple key systems, the first supported key system in the manifest is used.

The interoperable encryption standard that DRM vendors are implementing is called Common Encryption (CENC). Some DASH manifests don't specify any particular key system at all, but instead state that any CENC system will do:

<ContentProtection schemeIdUri="urn:mpeg:dash:mp4protection:2011" value="cenc"/>

If this is the only <ContentProtection> element in the manifest, Shaka will try all key systems it knows. (Based on keySystemsByURI in shaka.extern.DashManifestConfiguration.)

Through player.configure(), you can update the dash key systems mapping by scheme URI:

player.configure({
  manifest: {
    dash: {
      keySystemsByURI: {
        'urn:uuid:9a04f079-9840-4286-ab92-e65be0885f95': 'com.microsoft.playready.recommendation',
        'urn:uuid:79f0049a-4098-8642-ab92-e65be0885f95': 'com.microsoft.playready.recommendation',
      }
  }
  }
});

If the browser supports it and you configured a license server URL for it, we'll use it.

Alternative there are a config for make a mapping of keysystem if you know that is broadly supported. For example, com.microsoft.playready.recommendation:

player.configure({
  drm: {
    keySystemsMapping: {
      'com.microsoft.playready': 'com.microsoft.playready.recommendation',
    }
  }
});

With the previous configuration you will choose the recommendation keySystem when your manifest (HLS or DASH) uses PlayReady.

Clear Key

The EME spec requires browsers to support a common key system called "Clear Key". (At the time of this writing (April 2016), only Chrome and Firefox have implemented "Clear Key".) Clear Key uses unencrypted keys to decrypt CENC content, and can be useful for diagnosing problems and testing integrations. To configure Clear Key, use the configuration field drm.clearKeys and provide a map of key IDs to content keys (both in hex):

player.configure({
  drm: {
    clearKeys: {
      // 'key-id-in-hex': 'key-in-hex',
      'deadbeefdeadbeefdeadbeefdeadbeef': '18675309186753091867530918675309',
      '02030507011013017019023029031037': '03050701302303204201080425098033'
    }
  }
});

This will force the use of Clear Key for decryption, regardless of what is in your manifest. Use this when you need to confirm that your keys are correct.

Clear Key Licenses

If your manifest actually specifies Clear Key, you can also use the normal license request mechanism to retrieve keys based on key IDs. The EME spec defines a JSON-based license request format and license format for the Clear Key CDM. If you have a server that understands these, just configure a license server as normal:

player.configure({
  drm: {
    servers: {
      'org.w3.clearkey': 'http://foo.bar/drm/clearkey'
    }
  }
});

Advanced DRM Configuration

We have several advanced options available to give you access to the full EME configuration. The config field drm.advanced is an object mapping key system IDs to their advanced settings. For example, to require hardware security in Widevine:

player.configure({
  drm: {
    servers: {
      'com.widevine.alpha': 'https://foo.bar/drm/widevine'
    },
    advanced: {
      'com.widevine.alpha': {
        'videoRobustness': 'HW_SECURE_ALL',
        'audioRobustness': 'HW_SECURE_ALL'
      }
    }
  }
});

If you don't need them, you can leave these at their default settings.

Robustness

Robustness refers to how securely the content is handled by the key system. This is a key-system-specific string that specifies the requirements for successful playback. Passing in a higher security level than can be supported will cause player.load() to fail with REQUESTED_KEY_SYSTEM_CONFIG_UNAVAILABLE. The default is the empty string, which is the lowest security level supported by the key system.

Each key system has their own values for robustness.

Widevine

Chromium sources: https://cs.chromium.org/chromium/src/components/cdm/renderer/widevine_key_system_properties.h?q=SW_SECURE_CRYPTO&l=22

• SW_SECURE_CRYPTO
• SW_SECURE_DECODE
• HW_SECURE_CRYPTO
• HW_SECURE_DECODE
• HW_SECURE_ALL

PlayReady

Microsoft Documentation: https://docs.microsoft.com/en-us/playready/overview/security-level

• 3000
• 2000
• 150

com.microsoft.playready key system ignores given robustness and stays at a 2000 decryption level.

NB: Audio Hardware DRM is not supported (PlayReady limitation)

FairPlay

Based on Apple's Documentation, you should provide an empty string as robustness

Other key-systems

Values for other key systems are not known to us at this time.

Re-use persistent license DRM for online playback

If your DRM provider configuration allows you to deliver persistent license, you could re-use the created MediaKeys session for the next online playback.

Configure Shaka to start DRM sessions with the persistent-license type instead of the temporary one:

player.configure({
  drm: {
    advanced: {
      'com.widevine.alpha': {
        'sessionType': 'persistent-license'
      }
    }
  }
});

Using persistent-license might not work on every devices, use this feature carefully.

When the playback starts, you can retrieve the sessions metadata:

const activeDrmSessions = this.player.getActiveSessionsMetadata();
const persistentDrmSessions = activeDrmSessions.filter(
  ({ sessionType }) => sessionType === 'persistent-license');

// Add your own storage mechanism here, give it an unique known identifier for
// the playing video

When starting the same video again, retrieve the metadata from the storage, and set it back to Shaka's configuration.

Shaka will load the given DRM persistent sessions and will only request a license if some keys are missing for the content.

player.configure({
  drm: {
    persistentSessionOnlinePlayback: true,
    persistentSessionsMetadata: [{
      sessionId: 'deadbeefdeadbeefdeadbeefdeadbeef',
      initData: new InitData(0),
      initDataType: 'cenc'
    }]
  }
});

NB: Shaka doesn't provide a out-of-the-box storage mechanism for the sessions metadata.

Continue the Tutorials

Next, check out License Server Authentication. Or check out FairPlay support.