Bitmovin Encoder Integration Guide

Overview

When using Bitmovin encoding service, multi DRM packaging is possible through CPIX or SPEKE API integration with DoveRunner KMS(Key Management Server).

This document explains how to create DASH/HLS content with multi-DRM using the Bitmovin Encoder SDK.

Requirements

  • Commercial account of Bitmovin Encoding service: permission required for DRM API
  • Use of Bitmovin Encoding SDK
  • DoveRunner Multi DRM service account: trial or commercial

DRM Packaging Process

Using Bitmovin SPEKE API

If you use the SPEKE API supported by the Bitmovin encoder, DRM packaging is possible with a simple setup because the API integration with DoveRunner KMS server is handled inside the Bitmovin encoder. However, the current Bitmovin encoder only supports the SPEKE API v1 specification, so multi-key packaging (supported by SPEKE v2) cannot be applied.

sequenceDiagram
    participant A as Content Service Site
    participant B as Bitmovin Encoding
    participant C as DoveRunner KMS
    A -->> A: Configure packaging job (source content and output storage)
	A ->> B: Create DRM packaging job using SpekeDrm object (with KMS URL and Content ID)
	B ->> C: Request Key and Kid to DoveRunner KMS via SPEKE API
	C -->> C: Generate and store Key/Kid for the CID
	C ->> B: Respond Key and Kid
    B -->> B: Package DASH or HLS content with DRM encryption
    B ->> A: Store the result in the output storage

Using DoveRunner CPIX API

In case of CPIX API, the API communication with DoveRunner KMS server is processed outside the Bitmovin encoder, and the results (KEY, KID, etc.) are input to the Bitmovin encoder to proceed with DRM packaging. If you use the Python version sample linked in this document, you don’t need to implement CPIX API request. If you use other programming languages, you need to implement the functions yourself by referring to Python samples and DoveRunner CPIX API specifications.

sequenceDiagram
    participant A as Content Service Site
    participant B as Bitmovin Encoding
    participant C as DoveRunner KMS
    A -->> A: Configure packaging job (source content and output storage)
	A ->> C: Request Key and Kid (Key ID) via DoveRunner CPIX API (with content ID)
	C -->> C: Generate and store Key/Kid for the CID
	C ->> A: Respond Key and Kid 
    A ->> B: Create DRM packaging job using CencDrm object (with Key and Kid)
    B -->> B: Package DASH or HLS content with DRM encryption
    B ->> A: Store the result in the output storage

Configurations by Integration Types

Type 1 - Using Bitmovin SPEKE API

This type of integration uses Bitmovin encoder’s SPEKE API instead of DoveRunner CPIX API. This type is recommended unless multi-key support is required.

Refer to the SPEKE integration documentation in the Bitmovin Developer Guide and create a SpekeDrmProvider object as shown in the following Java code.

SpekeDrmProvider spekeDrmProvider = new SpekeDrmProvider();
spekeDrmProvider.setUrl("https://kms.pallycon.com/v1/cpix/getKey?enc-token=YOUR-KMS-TOKEN");
  • Enter the DoveRunner SPEKE v1 URL as shown in the code above as the setUrl function parameter.
  • As the value of the enc-token parameter of that URL, enter the value of the KMS token issued when subscribing to the DoveRunner service replacing the YOUR-KMS-TOKEN part.
  • Since the KMS token value is used to authenticate access to the URL, you do not need to set separate authentication data such as setUsername, setPassword, and setRoleArn on the object.

Depending on the type of DRM that will be used for the encoding and packaging operation, create and set the SpekeDrm object as shown in the following example.

// one SPEKE config for Widevine and PlayReady
SpekeDrm spekeDrmCenc = new SpekeDrm();
spekeDrmCenc.setProvider(spekeDrmProvider);
spekeDrmCenc.setContentId("my-unique-content-id");
spekeDrmCenc.setSystemIds(
   Arrays.asList("edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", "9a04f079-9840-4286-ab92-e65be0885f95"));

// another SPEKE config for FairPlay
SpekeDrm spekeDrmFairplay = new SpekeDrm();
spekeDrmFairplay.setProvider(spekeDrmProvider);
spekeDrmFairplay.setContentId("my-unique-content-id");
spekeDrmFairplay.setSystemIds(
   Arrays.asList("94ce86fb-07ff-4f43-adb8-93d2fa968ca2"));
  • For the my-unique-content-id value, enter an arbitrary unique ID value for the target content.
  • The setSystemIds function parameter is a list of system ID values for each DRM.

For details on integrating the Bitmovin encoder via the SPEKE API, please refer to the Bitmovin developer documentation linked above.

Type 2 - Using DoveRunner CPIX API

This method uses the CPIX API client supported by DoveRunner.

Step 1 - Run the CPIX API client

Download the DoveRunner CPIX API client module and example from the following Github repository.

DoveRunner CPIX API client Github repository

Refer to the development language-specific examples and related guides to perform CPIX API requests and get the response data.

Step 2 - Set the API response data to Bitmovin Encoder

From the CPIX response JSON data obtained in step 1, parse the following values and enter them into the Bitmovin Encoder integration code below.

  • key_id_hex, key_hex, iv_hex: Set the Key ID (KID), Key, and IV values as 32-digit hexadecimal string.
  • pssh_payload_only: PSSH for Widevine or PlayReady, which uses payload data without headers.
private static CencDrm createDrmConfig(
    Encoding encoding, Muxing muxing, Output output, String outputPath) throws BitmovinException {
  CencDrm cencDrm = new CencDrm();
  cencDrm.addOutputsItem(buildEncodingOutput(output, outputPath));
  cencDrm.setKey("cab5b529ae28d5cc5e3e7bc3fd4a544d");
  cencDrm.setKid("08eecef4b026deec395234d94218273d");
  
  CencWidevine widevineDrm = new CencWidevine();
  widevineDrm.setPssh("QWRvYmVhc2Rmc2FkZmFzZg==");
  cencDrm.setWidevine(widevineDrm);
  
  CencPlayReady playReadyDrm = new CencPlayReady();
  playReadyDrm.setLaUrl("https://license-global.pallycon.com/ri/licenseManager.do");
  //playReadyDrm.setPssh("QWRvYmVhc2Rmc2FkZmFzZg==");
  cencDrm.setPlayReady(playReadyDrm);
  
  CencFairPlay cencFairPlay = new CencFairPlay();
  cencFairPlay.setIv("e7fada52ac654bbe80367505dceeb318");
  cencFairPlay.setUri("skd://y7w4trUNq1P4Jj4Gtzgqow==");
  cencDrm.setFairPlay(cencFairPlay);
  
  return bitmovinApi.encoding.encodings.muxings.fmp4.drm.cenc.create(
      encoding.getId(), muxing.getId(), cencDrm);
}

For details on integrating the Bitmovin encoder via the CPIX API, please refer to the Bitmovin developer documentation.

Previous
Next

Last updated on Aug 8, 2023