--- title: "AWS Elemental Integration" description: "This guide explains how to integrate with MediaConvert or MediaPackage service." --- > For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt). DoveRunner KMS supports [SPEKE](https://docs.aws.amazon.com/en_US/speke/latest/documentation/what-is-speke.html) (Secure Packager and Encoder Key Exchange), which issues the keys required for Multi DRM packaging in AWS Elemental MediaConvert and MediaPackage. You can easily integrate DoveRunner Multi-DRM with AWS Elemental Media Services by setting DoveRunner KMS URL to `DRM encryption` setting of MediaConvert or MediaPackage. ## MediaConvert integration ### MediaConvert Tutorial Video This video is a tutorial for enabling DRM encryption on VOD content packaging with AWS Elemental MediaConvert. [Video: YouTube](https://www.youtube.com/watch?v=msldnXgAptU) > **Learn it in DoveRunner Lab**: Step-by-step lesson [Multi-DRM packaging with AWS Elemental MediaConvert](https://lab.doverunner.com/academy/courses/drm-packaging-tutorials/package-with-aws-mediaconvert) ### Create MediaConvert IAM role Please refer to [IAM Settings AWS Guide Document](https://docs.aws.amazon.com/mediaconvert/latest/ug/iam-role.html) and proceed as follows. 1. In the AWS Console, select the IAM service. 2. Click the `Roles` tab and select `create role`. 3. Select `AWS service` as the trusted entity type, choose `MediaConvert` as the use case, and click `Next`. 4. The `MediaConvert` use case attaches the `AmazonS3FullAccess` and `AmazonAPIGatewayInvokeFullAccess` policies and sets `mediaconvert.amazonaws.com` as the trusted entity. You don't need to select any policy. Click `Next`. 5. Set RoleName to `MediaConvert-role` and click the `create role` button. ### Create MediaConvert job and set IAM role 1. In the AWS Console, select the MediaConvert service. 2. Click the `create job` button on the Jobs tab to start job creation. 3. In `AWS integration` of the Job settings screen, select `Use an existing service role` under `Service role control`, and then select the `MediaConvert-role` created in the previous step. ### Set MediaConvert Input 1. In the Input field, enter the content path to be packaged in s3. ### Set MediaConvert Output groups 1. Add the ouptput to the output groups by pressing the Add button. (DASH ISO for PlayReady and Widevine, Apple HLS for FairPlay and NCG-HLS, or CMAF for DASH and HLS output in one group) 2. In Custom group name, enter a name that is easy for you to identify. 3. In the Destination field, type the path on s3 that contains the package-completed file. 4. Turn on the `DRM encryption` toggle of the output group, and then enter the Resource ID, System ID, and URL. `DRM encryption` is set for each output group. - Resource ID: It is a value corresponding to the content ID (CID) in the integration specification in [DRM Token Guide](https://docs.doverunner.com/content-security/multi-drm/license/license-token/). - System ID: The DRM-specific system id value specified in [Dash System ID](http://dashif.org/identifiers/content_protection). You need to set PlayReady and Widevine ID for DASH output(as shown below). Enter one System ID per line, up to two. The DASH ISO output group is encrypted with CENC. Refer to the next sections for HLS output configuration. - PlayReady: `9a04f079-9840-4286-ab92-e65be0885f95` - Widevine: `edef8ba9-79d6-4ace-a3c8-27dcd51d21ed` - Key Provider URL: Enter the following KMS URL. The `KMS Token` at the end of the URL is an API authentication token that is generated when you sign up DoveRunner service, and can be found on the [DoveRunner Console](https://console.doverunner.com) site. - KMS URL format: `https://drm-kms.doverunner.com/v1/cpix/getKey?enc-token=YOUR-KMS-TOKEN` - Certificate ARN: leave it blank - Play device compatibility: CENC v1 5. Set the Outputs and click the Create button. - In case of widevine, it is mandatory to create the video and audio track separately because there are clients that can not play if you do not divide video and audio tracks into output. (click 'add output' button to add track) - If you leave Width and Height empty, the output keeps the resolution and aspect ratio of the source. Set Width, Height, and the scaling behavior only if you need a fixed frame size. 6. Make public or set permission on the S3 storage to play the generated file stored on it. :::note The following validation errors may appear the first time you click Create. - `h264Settings: maxBitrate is a required property`: The default rate control mode is QVBR. Set `Max bitrate` on each H.264 output. - `nameModifier is a required property`: Set `Name modifier` on the `Apple HLS` output (for example, `_1080p`). Warnings 230001 and 230005 about missing color metadata in the input source can be ignored. The job still completes. ::: ### HLS configuration for FairPlay DRM If you want to support Apple devices as well as others, you need to create both 'DASH ISO' and 'Apple HLS' output groups for a single input. To apply FairPlay DRM to `Apple HLS` output group, set the encryption options as below. - Encryption method: `Sample AES` - Key provider type: `SPEKE` - Resource ID: the same content ID as DASH output - System ID: DRM system ID for FairPlay (`94ce86fb-07ff-4f43-adb8-93d2fa968ca2`) - Key provider URL: same as DASH output (DoveRunner KMS URL with enc token) - the other items: leave them as default The `Apple HLS` output group offers only `AES128` and `Sample AES` encryption, not CENC. HLS content packaged with FairPlay plays only on Apple devices and Safari, and requires a FairPlay certificate registered on the DoveRunner Console. ### HLS configuration for NCG-HLS You can also use the ‘Apple HLS’ output group to package HLS content with our proprietary NCG DRM instead of FairPlay DRM. For the `NCG-HLS` packaging, create an `Apple HLS` output group and set the DRM encryption options as shown below. - Encryption method: `AES128` - Key provider type: `SPEKE` - Resource ID: Enter the same content ID as the DASH output group - System ID: NCG HLS system ID (`81376844-f976-481e-a84e-cc25d39b0b33`) - Key Provider URL: DoveRunner KMS URL same as DASH output group - Other items: leave them as default :::note `NCG-HLS` packaging is a method of additionally encrypting the AES128 key file with NCG DRM to improve the security of the clear key encryption. To play `NCG-HLS` contents, NCG Client SDK provided for each OS such as Android, iOS, and Windows is required, and NCG HLS contents cannot be played in a web browser. ::: ### Notes on CMAF Packaging In addition to `DASH-ISO` and `Apple HLS`, `CMAF`(Common Media Application Format) type output can also be generated through SPEKE integration. A `CMAF` output group generates both DASH and HLS output in one group. To ensure that CMAF content is supported in as many client environments as possible, including Apple devices, the encryption method in the `DRM encryption` setting should be set to `AES-CBC subsample`. Also, the KMS URL you enter in the `Key provider URL` field must use the URL below that supports CBCS encryption and includes 'cbcs' in the path, instead of the default SPEKE v1 URL. ```sh https://drm-kms.doverunner.com/v1/cpix/cbcs/getKey?enc-token=YOUR-KMS-TOKEN ``` For SPEKE v2, you can use: ```sh https://drm-kms.doverunner.com/v2/cpix/getKey?enc-token=YOUR-KMS-TOKEN ``` SPEKE v2 uses the same `/v2/cpix/getKey` URL for CBCS encryption. The `/cbcs/` path is for SPEKE v1 only. ### Multi-key Packaging via SPEKE v2 MediaConvert service supports both `SPEKE v1`, which encrypts all output tracks including audio with one key (single-key packaging), and the [SPEKE API v2](https://docs.aws.amazon.com/speke/latest/documentation/the-speke-api-v2.html), which supports multi-key packaging. Multi-key packaging is a function that encrypts the output video and audio tracks with different keys when DRM encryption is applied, and is necessary to apply hardware DRM such as PlayReady SL3000 or Widevine L1. If you select `SPEKE Version 2.0` in the `Apple HLS`, `DASH-ISO`, or `CMAF` output group settings of the MediaConvert job, you can apply multi-key packaging by choosing the video and audio encryption presets, which set how many keys are used for the video and audio tracks. You need to input the `SPEKE v2 KMS URL` when you choose the SPEKE v2 integration. You can find your own KMS Token value on DoveRunner Console (`Content Security > Multi DRM > Settings`). ```sh SPEKE v2 KMS URL: https://drm-kms.doverunner.com/v2/cpix/getKey?enc-token=YOUR-KMS-TOKEN ``` ## MediaPackage integration AWS MediaPackage service supports real-time packaging and encryption for live or VOD content. :::note The tutorial video and guide document below are based on MediaPackage Live v1. If you are integrating with the newer version of the service, Live v2, please refer to the [related section](https://docs.doverunner.com/content-security/multi-drm/packaging/aws-elemental/#mediapackage-live-v2). ::: :::caution - When packaging live streams via MediaLive and MediaPackage integration, the Encryption setting must be turned off in the Output Group of MediaLive. - For MediaPackage v2, use the `CMAF Ingest` output group in MediaLive. (The `MediaPackage` output group type is for v1.) `CMAF Ingest` has no encryption setting, and each output can hold only one of video, audio, or captions, so add a separate output for audio. - The `Start` button of a MediaLive channel stays disabled until a channel role is set. Select a role in `Edit channel` > `Use existing role`. - Both AWS MediaPackage v1 and v2 require inputs to contain at least one video track. MediaPackage doesn't support inputs that contain no video track. Therefore, you need to use MediaConvert if you have audio-only VOD contents to package. ::: ### MediaPackage Tutorial Video This video is a tutorial for enabling DRM encryption on live stream packaging with AWS Elemental MediaPackage. [Video: YouTube](https://www.youtube.com/watch?v=lF4A7nAswP0) > **Learn it in DoveRunner Lab**: Step-by-step lesson [Live Multi-DRM packaging with AWS Elemental MediaLive and MediaPackage](https://lab.doverunner.com/academy/courses/drm-packaging-tutorials/package-with-aws-mediapackage) ### Create MediaPackage IAM role 1. Create the same as [MediaConvert IAM Authorization](#create-mediaconvert-iam-role), and create only Role Name with SPEKEAccess. 2. On the Roles tab, select SPEKEAccess role and click the Edit trust relationship button on the Trust relationships tab. 3. Set the value of Principal.Service to both mediapackage.amazonaws.com and mediapackagev2.amazonaws.com, and click the Update button. If mediapackagev2.amazonaws.com is missing, creating a MediaPackage v2 endpoint fails with an "unable to assume the IAM role" error. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "mediapackage.amazonaws.com", "mediapackagev2.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` ### Create MediaPackage Channel 1. In the AWS Console, select the MediaPackage service. 2. Create a channel. 3. At the endpoints, press the Add button to set the endpoint. 4. Set the endpoint name, packager settings, etc. according to the desired content specification. 5. Configure Encryption and Outputs in the same way as [MediaConvert Output groups setting no. 4](#set-mediaconvert-output-groups). 6. Enter the SPEKEAccess Role created in Role ARN. 7. Click the Save button. :::note For information on various input values used for Encryption setting of MediaPackage Endpoint, refer to the `MediaConvert Integration` guide(the previous section). ::: ### Multi-key Packaging via SPEKE v2 The MediaPackage service supports multi-key packaging based on [SPEKE API v2](https://docs.aws.amazon.com/speke/latest/documentation/the-speke-api-v2.html) for live DASH or CMAF output. Multi-key packaging is a function that encrypts the output video and audio tracks with different keys when DRM encryption is applied, and is necessary to apply hardware DRM such as PlayReady SL3000 or Widevine L1. If you select `SPEKE Version 2.0` in the DASH or CMAF Endpoint settings of the MediaPackage live channel, you can apply multi-key packaging by choosing the video and audio encryption presets, which set how many keys are used for the video and audio tracks. You need to input the `SPEKE v2 KMS URL` when you choose the SPEKE v2 integration. You can find your own KMS Token value on DoveRunner Console (`Content Security > Multi DRM > Settings`). ```sh SPEKE v2 KMS URL: https://drm-kms.doverunner.com/v2/cpix/getKey?enc-token=YOUR-KMS-TOKEN ``` ### MediaPackage Live v2 `MediaPackage Live v2` is a new version of the AWS MediaPackage service released in May 2023. This version offers improved features and UI over v1, especially support for low-latency HLS (LL-HLS), which is ideal for real-time services such as live sporting events. :::note For more information about the MediaPackage Live v2 service, please refer to the [AWS guide](https://docs.aws.amazon.com/mediapackage/latest/userguide/what-is.html). ::: Please note the following when integrating AWS MediaPackage Live v2 with DoveRunner Multi-DRM service. #### Channel and endpoint settings - In the AWS Console, open the MediaPackage service and go to `Channel groups` (`/mediapackage/home#/channel-groups`) to create a channel group and a channel. For input from MediaLive `CMAF Ingest`, set the channel input type to `CMAF`. - In the origin endpoint settings, enter the following in `Encrypt content`. - `Resource ID`: content ID (CID) - `Key server URL`: DoveRunner KMS SPEKE v2 URL - `Role ARN`: ARN of the SPEKEAccess role - SPEKE version: `SPEKE 2.0`, with the video and audio encryption presets - Set the key rotation interval in `Additional configuration` > `Key rotation interval`. #### Container Types In the `MediaPackage Live v1` channel, you could select a packaging type for the endpoint for output, such as `DASH-ISO`, `Apple HLS`, `Smooth Streaming`, or `CMAF`. Instead of a packaging type, endpoints in the MediaPackage Live v2 service channel are required to select the following container types. - `TS`: Applies MPEG-TS container. Supports AES-128 (clear-key encryption) or Sample AES (FairPlay DRM). - `CMAF`: Applies fMP4 container. Support for CENC (PlayReady, Widevine) or CBCS (PlayReady, Widevine, FairPlay). For streaming protocols that fall under the earlier `packaging type` option, v2 can generate output in the form of `DASH`, `HLS` or `LL-HLS` protocols. :::note PlayReady and Widevine DRM cannot be applied when selecting TS container, so if you want to apply DRM to various client environments with one endpoint, you must select `CMAF` container and `CBCS` encryption. You can also consider creating two endpoints (CMAF CENC + TS Sample AES, or CMAF CENC + CMAF CBCS) for one input source if you need support for clients that do not support CMAF CBCS. For CBCS encryption, use the same SPEKE v2 URL (`/v2/cpix/getKey`). With `/v2/cpix/cbcs/getKey`, the endpoint doesn't generate a manifest and returns 404. ::: #### Key rotation configuration As with MediaPackage Live v1, when applying DRM encryption to endpoints on a v2 channel, you can set the key rotation period in the Additional configuration section. (The minimum key rotation interval is `300` seconds.) Please note the following when you enable key rotation: - You need to add a key rotation parameter to the key server URL. - Add `key-rotation=true` parameter to the DoveRunner KMS SPEKE v2 URL that you enter in `Key server URL` of `Encryption` option (enter two parameters: `enc-token` and `key-rotation`). - Example: `https://drm-kms.doverunner.com/v2/cpix/getKey?key-rotation=true&enc-token=YOUR-KMS-TOKEN` :::note The `key-rotation` parameter defaults to `false` when omitted. A mismatch between the `Key rotation interval` setting in MediaPackage Live v2 and the value of the KMS URL parameter may result in errors when playing that stream. ::: - Enable key rotation in token policy when requesting DRM licenses - When generating a license token for content with key rotation, the `key_rotation` item in the token JSON specification must be set to `true`. - Enable key rotation for DoveRunner Multi-DRM service account - In order to issue DRM licenses for content with key rotation, the key rotation right must be activated in the DoveRunner service account of the site. (You can check it on the DoveRunner Console > `Content Security > Multi DRM > Settings` screen.) - Please contact Helpdesk or our business team to request key rotation activation and inquire about additional charges. :::caution Due to the nature of the DRM key rotation feature, each rotation cycle requires a new license to be issued for every client that is playing that stream. Therefore, applying key rotation to a stream that is being played by many users simultaneously may cause license issuance delays or errors due to excessive traffic. Customers considering live key rotation should consult with our Helpdesk or business team beforehand. :::