Check out the Wiki for general news, guides, and other updates.

Electron for Content Security (ECS) is a fork of Electron created by castLabs to facilitate the use of Google's Widevine Content Decryption Module (CDM) for DRM-enabled playback within Electron, including support for Verified Media Path (VMP) and persistent license storage. It is intended to be used as a drop-in replacement for stock Electron and currently has full support for Windows and macOS platforms, with partial support for Linux (which lacks support for persistent licenses due to VMP limitations on the platform).

The sections below will describe the features/modifications that ECS provides, for anything else refer to the regular Electron documentation.

To achieve Widevine support the Widevine CDM will be installed on first launch and enabled as an option for playback of DRM protected content using common EME APIs. Subsequent launces will trigger a backround update check. If an update is available it will be downloaded and applied on next launch. During this process certain events are emitted, the two most important being widevine-ready and widevine-error.

The provided builds are VMP-signed for development and can be used with Widevine UAT or other servers accepting development clients. For production use you can sign up for our EVS service, to obtain production VMP signing capabilities. Previously a license agreement with Google Widevine was required to get your own VMP signing certificate, but with EVS this is no longer necessary.

To install prebuilt ECS binaries, use npm. The preferred method is to install ECS as a development dependency in your app:

npm install "https://github.com/castlabs/electron-releases#v6.0.0-wvvmp" --save-dev

Since ECS is not published in the npm package index a GitHub URL is used instead to reference a particular release, just modify the # tag at the end to the version you want to use.

Using ECS is very similar to using stock Electron, the main difference being that you should wait for the widevine-ready event, instead of using app.whenReady() or waiting for the regular ready event, before opening your BrowserWindow.

const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow()
  win.loadURL('https://shaka-player-demo.appspot.com/')
}

app.on('widevine-ready', createWindow)

Widevine CDM installation/update is ordinarily automatically triggered on startup, but if more control is necessary, facilities are provided to control this behavior.

Command line parameter that prevents ECS from automatically triggering the Widevine CDM installation, update, and registration, on startup. This requires the process to be manually triggered instead, using the verifyWidevineCdm API, which also allows extra options to be passed.

Command line parameter that prevents ECS from checking for, and installing, updates on startup. This fills the same function as the disableUpdate option of verifyWidevineCdm, but has lower precedence in case both are set.

⚠️ Disabling Widevine CDM updates for extended periods of time is not advisable since you may miss a critical update, ultimately rendering the media client unusable!

Command line parameter that overrides the base directory in which the Widevine CDM is downloaded and installed. This fills the same function as the baseDir option of verifyWidevineCdm, but has lower precedence in case both are set.

• options Object (optional)
  • session Session (optional)
  • disableUpdate boolean (optional)
  • baseDir string (optional)

Initiates asynchronous Widevine CDM installation, update, and registration, procedure and returns no value. Once initiated Widevine events will be emitted as necessary.

Unless no-verify-widevine-cdm has been set this API is automatically triggered on startup and MUST NOT be called manually. If set, this API can be used to customize the behavior of the install/update operation. It MUST be called once, very early, after the app has received the ready event, but before loading any media-related content to avoid potentially requiring a restart.

The disableUpdate controls if the CDM update check, and pending update installation, is executed. This can be used in offline, e.g. geo-blocking, scenarios to avoid pre-persisted licenses being invalidated by an untimely CDM update.

⚠️ Disabling Widevine CDM updates for extended periods of time is not advisable since you may miss a critical update, ultimately rendering the media client unusable!

The baseDir option controls the path in which the Widevine CDM is downloaded and installed. By default the user application data directory, as returned by app.getPath('userData'), is used.

const { app, session } = require('electron')

app.commandLine.appendSwitch('no-verify-widevine-cdm')

// Demonstrating with constant, but this should be set dynamically
let isOffline = false

// Demonstrating with the user data directory, which is the default
let widevineDir = app.getPath('userData')

app.on('ready', () => {
  // Demonstrating with default session, but a custom session object can be used
  app.verifyWidevineCdm({
    session: session.defaultSession,
    disableUpdate: isOffline,
    baseDir: widevineDir
  })

  // Do other early initialization...
})

app.on('widevine-ready', () => {
  // Open media browser window, etc...
})

As a part of the installation and update process for the Widevine CDM certain events will be emitted to the application. These events allow the user to monitor the Widevine status to a certain extent.

Emitted once Widevine has been properly registered and is ready to use to be used. Trying to play back protected content prior to the reception of this event will cause errors. This event is always emitted after the ready event.

Two arguments are provided indicating the current and last versions of Widevine.

If the lastVersion argument is not null and is not equal to version an update has occured, potentially rendering any persisted licenses unusable, see the CDM migration section for more information.

app.on('widevine-ready', (version, lastVersion) => {
  if (null !== lastVersion) {
    console.log('Widevine ' + version + ', upgraded from ' + lastVersion + ', is ready to be used!')
  } else {
    console.log('Widevine ' + version + ' is ready to be used!')
  }
})

Emitted when there is a Widevine CDM update available that is pending installation. This event is always emitted after the widevine-ready event. Once the application is restarted the update will be automatically applied, unless updates have been disabled.

Two arguments are provided which contains the current and pending versions of Widevine.

app.on('widevine-update-pending', (currentVersion, pendingVersion) => {
  console.log('Widevine ' + currentVersion + ' is ready to be upgraded to ' + pendingVersion + '!')
})

Emitted when there is a problem with the Widevine CDM installation that cannot be automatically handled. If there are no handlers registered for this event it will show a dialog with the error and terminate the application when it is dismissed. If this is not the desired behavior a handler needs to be registered to provide customized behavior. This event is always emitted after the ready event.

An argument is provided that contains an Error-instance describing the error that occured.

app.on('widevine-error', (error) => {
  console.log('Widevine installation encountered an error: ' + error)
  process.exit(1)
})

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. UPDATES, INCLUDING SECURITY UPDATES, WILL BE PROVIDED ON A BEST-EFFORT BASIS.