ATEME TITAN Products Integration Guide

Overview

PallyCon Multi-DRM service offers seamless integration with ATEME TITAN Live and TITAN File products, enabling customers to configure DRM encryption key data for VOD (Video on Demand) and live streams. This integration is based on the Content Protection Information Exchange (CPIX) API, which serves as the industry-standard interface between the DRM key server and various transcoder and packager solutions.

This guide provides step-by-step instructions and sample code to assist customers in integrating PallyCon Multi-DRM with ATEME TITAN products.

Prerequisites

  • Active accounts on PallyCon Multi-DRM service and ATEME TITAN products
  • Familiarity with ATEME TITAN Live and TITAN File solutions
  • Basic understanding of CPIX API and DRM encryption concepts

TITAN Live Integration for Live Streaming

There are two ways of configuring and staring a new live stream with DRM encryption. Please follow one of the instructions below based on your preference of web GUI and REST API provided by ATEME TITAN Live.

Live Packaging via Web GUI

Login to the TITAN Live web GUI with your TITAN account. Then create a new service and configure the service under SERVICES tab of the UI as below:

Input

Define the live stream input as below:

  • Input Type: RTMP
  • Mode: Client
  • Url: the RTMP URL of the source stream
  • Stream name: any name of your choice for the stream

Muxer

Add a muxer for DASH, HLS or FMP4, and configure the information below under DEVICE CONFIGURATION.

  • DRM Configuration
    • Choose from Multi-DRM, Widevine, PlayReady, and FairPlay options. The Multi-DRM option includes both Widevine and Playready.
  • Key Management Parameter
    • Server Type: Standard CPIX
    • Key Server URL: <PallyCon KMS URL with your KMS token>
    • Content ID: Unique ID of the live stream content. Maximum 200 bytes of alphanumeric and -(hyphen), _(underscore) characters are allowed.
    • Key ID: <CPIX request kid>
For more information about the input values such as KMS URL and Key ID, please refer to the CPIX API guide.

Output

  • Check Ignore SSL errors and Enable options
  • Url: The URL of DASH mpd or HLS m3u8 output

To configure CMAF output(1 muxer, 2 outputs), follow the steps below:

  1. Input an mpd URL to the CMAF URL field
  2. Click ADD HLS MASTER PLAYLIST button and input additional m3u8 URL

Live Packaging via REST API

You can create a new service for a live stream or manage existing one by calling the REST API URI of TITAN Live product.

https://<ID>:<PW>@<ip address>/api/v1/servicesmngt/services
You need to input the ID/password of your TITAN Live service account to the REST API URL instead of the Administrator account used for the web UI.

REST API Behaviors by the HTTP methods

  • GET method: Returns the list of existing jobs (services)
  • POST method: Creates a new job if the UUID was not used previously. Updates the existing job if there is one with the same UUID as the request.

DRM Configurations in the Request Data

Create and set a json-type request data as below example to configure the DRM integration.

  • DRM Type: Choose from Multi-DRM, Widevine, PlayReady, and FairPlay options. The Multi-DRM option includes both Widevine and Playready.
  • KeyServerParam
    • ContentID: Unique ID of the live stream content. Maximum 200 bytes of alphanumeric and -(hyphen), _(underscore) characters are allowed.
    • KID: <CPIX request kid>
    • ScramblerKeyServerUrl: <PallyCon KMS URL with your KMS token>
    • ServerType: Standard CPIX
{
  "DRMType": "Multi-DRM",
  "IVSize": "16 Bytes",
  "InternalKeySettings": {},
  "KeyServerParam": {
    "ContentID": "titanlive",
    "KID": "44bf0b6d-e751-4afb-a687-568eaec911d5",
    "KeyDuration": 0,
    "ScramblerKeyServerUrl": "https://kms.pallycon.com/v2/cpix/pallycon/getKey/eyJhY2Nlc3Nfa2V5IjoiZHNJb2xjN2gxRzhUVW1JMTdiWXd4aFV1TkZvRmNlNzJjeDllTU9rNjJ3YjhWTjJQZGdwV1lISXhTRVg5ZjBIaSIsInNpdGVfaWQiOiJERU1PIn0=",
    "ServerType": "Standard CPIX",
    "SslParameters": {
      "SslClientCertificate": {
        "Name": "filename",
        "UseCertificate": false
      },
      "SslPeerCertificate": {
        "Authority": "Default authority",
        "Name": "filename",
        "VerifyCertificate": false
      }
    }
  },
  "SetKeyServer": true,
  "WriteKey": false
}
For more information about the input values such as KMS URL and Key ID, please refer to the CPIX API guide.

Start and Play the Live Stream

After creating the service via web GUI or REST API, you can start the live stream and test its playback by following the steps below:

  1. Make sure the new service is listed in the SERVICES tab of web GUI or REST API response.
  2. Start the streaming by clicking the playback button on the GUI or using an API call.

You can check the ALARMS tab for error logs if the job is failed.

  1. Configure your output streaming server so that you can test the playback of the mpd or m3u8 output URL.

TITAN File Integration for VOD content

Similar to the TITAN Live integration, packaging VOD content through the TITAN File integration can be done through the web GUI or REST API.

VOD packaging via Web GUI

Registering Amazon S3 storage

In the web GUI of the TITAN File product, go to Credentials on the left tab and register the credentials required to access Amazon S3 as follows.

  • Choose a protocol: S3
  • Name: An arbitrary name for the credential
  • AWS Access Key: An AWS access key required to access the S3 storage
  • AWS Secret Key: An AWS secret key required to access the S3 storage
  • AWS Storage Region: Select the AWS region for this S3 storage.
  • ACL Full Control: Disable this option as it is not used.
  • Certificate Authority Bundle: This option is not used.

The Credential Name above will be used in the Input and Output URLs you enter when creating a job in the next step.

  • e.g. s3://< credential name >@s3.ap-northeast-2.amazonaws.com/< bucket name >/path/to/file/source.mp4

Creating and starting a packaging job

You can create a VOD packaging job and set up DRM through the Job Composer on the left tab of the web GUI as follows.

  • Set up each area of Assets, Inputs, Tracks, and Outputs.
    • Enter the Amazon S3 path for the Input source and Output storage fields.

On the Output tab, select DRM Type as manual and click Add DRM to enter the following values for each DRM type.

Option PlayReady Widevine FairPlay
DRM System Identifier playready widevine fairplay
Encryption Key 16 bytes key 16 bytes key 16 bytes key
Key ID 16 bytes key ID (UUID format) 16 bytes key ID (UUID format) 16 bytes key ID (UUID format)
PSSH Data PlayReady PSSH data Widevine PSSH data Not applicable
Initialization Vector Not applicable Not applicable 16 bytes IV
Key Uri Not applicable Not applicable skd://
Input values such as encryption key, key ID, PSSH data can be obtained by calling PallyCon CPIX API. Please refer to CPIX API Guide for more information such as API specifications and sample code.

After setting DRM, click Save Configuration and Run Job button in the upper right corner to run the job.

You can also create a job from the GUI by entering the JSON Body data used in the REST API integration below.

VOD packaging via REST API

You can create a VOD packaging job by calling the REST API URI supported by the TITAN File product.

Requesting a token for API authentication

Set the request data to the API URI as follows to call it to obtain an API authentication token.

API URI

https://<TITAN File server IP or domain>/titanfile/users/token

Request Body

{
  "username": <id>,
  "password": <password>
}

Response Body (example)

{
    "access_token": "e042a836c751224ca4c689d63bbd471e49a73ab7e4a7ff6e29c7496be09f8c72",
    "refresh_token": "05a8d364b730236be9f75328b43c2a053d3be8ce8b9b81d4101fcfd0c9509130",
    "expires_in": 3600,
    "token_type": "bearer"
}

Creating a job

Create a new VOD packaging job by calling the API URI with header and body data as shown below.

API URI

https://<TITAN File server IP or domain>/titanfile/api/jobs

Request Header

  • Content Type: application/json
  • Authorization: < token type > < auth token >
    • e.g. Bearer e042a836c751224ca4c689d63bbd471e49a73ab7e4a7ff6e29c7496be09f8c72

Request Body (example)

{
  "name": "pallycon-drm-integration-wv",
  "configuration": {
    "version": "1.82",
    "chunking": {
      "period": 2
    },
    "assets": {
      "first_file": {
        "uri": "s3://pallycon-titan@s3.ap-northeast-2.amazonaws.com/titan-qa-test/bbb_480p.mp4",
        "audio_composition": "mono"
      }
    },
    "inputs": [
      {
        "video": {
          "input_1": {
            "asset": "first_file"
          }
        },
        "audio": {
          "input_en": [
            {
              "asset": "first_file"
            }
          ]
        }
      }
    ],
    "track_configurations": {
      "avc": {
        "video_1": {
          "quality_speed": "ultrafast"
        }
      },
      "aac": {
        "audio_1": {}
      }
    },
    "tracks": {
      "video": {
        "video_1": {
          "configuration": "avc.video_1",
          "input": {
            "id": "video.input_1"
          }
        }
      },
      "audio": {
        "audio_1": {
          "configuration": "aac.audio_1",
          "input": {
            "id": "audio.input_en"
          }
        }
      }
    },
    "outputs": {
      "cmaf": {
        "first_hls": {
          "output": "s3://pallycon-titan@s3.ap-northeast-2.amazonaws.com/titan-qa-test/output/widevine/demo_pallycon_cpix-w.cmaf",
          "playlists": {
            "hls": {
              "HLS_Playlist_1": {
                "default_audio_track": "1",
                "profiles": {
                  "Profile 1": {
                    "tracks": [
                      "audio_1",
                      "video_1"
                    ]
                  }
                }
              }
            },
            "dash": {
              "DASH_Playlist_1": {
                "enable_segment_timeline": true,
                "tracks": [
                  "video_1",
                  "audio_1"
                ]
              }
            }
          },
          "profile": "live",
          "drms": {
            "manual": {
              "drm1": {
                "system_id": "widevine",
                "key": "af6b6f562085d36decd6d693f7e0e784",
                "key_id": "1a3a1b8d-8617-18c8-247e-908f2e436c8a",
                "pssh": "AAAAUXBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAADESEBo6G42GFxjIJH6Qjy5DbIoaDGlua2FlbnR3b3JrcyIJdGl0YW5maWxlSPPGiZsG"
              },
              "drm2": {
                "system_id": "playready",
                "pssh": "AAACYnBzc2gAAAAAmgTweZhAQoarkuZb4IhflQAAAkJCAgAAAQABADgCPABXAFIATQBIAEUAQQBEAEUAUgAgAHgAbQBsAG4AcwA9ACIAaAB0AHQAcAA6AC8ALwBzAGMAaABlAG0AYQBzAC4AbQBpAGMAcgBvAHMAbwBmAHQALgBjAG8AbQAvAEQAUgBNAC8AMgAwADAANwAvADAAMwAvAFAAbABhAHkAUgBlAGEAZAB5AEgAZQBhAGQAZQByACIAIAB2AGUAcgBzAGkAbwBuAD0AIgA0AC4AMwAuADAALgAwACIAPgA8AEQAQQBUAEEAPgA8AFAAUgBPAFQARQBDAFQASQBOAEYATwA+ADwASwBJAEQAUwA+ADwASwBJAEQAIABBAEwARwBJAEQAPQAiAEEARQBTAEMAQgBDACIAIABWAEEATABVAEUAPQAiAGoAUgBzADYARwBoAGUARwB5AEIAZwBrAGYAcABDAFAATABrAE4AcwBpAGcAPQA9ACIAPgA8AC8ASwBJAEQAPgA8AC8ASwBJAEQAUwA+ADwALwBQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEwAQQBfAFUAUgBMAD4AaAB0AHQAcABzADoALwAvAGwAaQBjAGUAbgBzAGUALgBwAGEAbABsAHkAYwBvAG4ALgBjAG8AbQAvAHIAaQAvAGwAaQBjAGUAbgBzAGUATQBhAG4AYQBnAGUAcgAuAGQAbwA8AC8ATABBAF8AVQBSAEwAPgA8AC8ARABBAFQAQQA+ADwALwBXAFIATQBIAEUAQQBEAEUAUgA+AA==",
                "key": "af6b6f562085d36decd6d693f7e0e784",
                "key_id": "1a3a1b8d-8617-18c8-247e-908f2e436c8a"
              },
              "drm3": {
                "system_id": "fairplay",
                "key": "af6b6f562085d36decd6d693f7e0e784",
                "initialization_vector": "30313233343536373839616263646566",
                "key_uri": "skd://GjobjYYXGMgkfpCPLkNsig==",
                "key_id": "1a3a1b8d-8617-18c8-247e-908f2e436c8a"
              }
            }
          },
          "tracks": {
            "audio_1": {
              "media_playlist_path": "${OUTPUT_BASE_URL}/${TRACK_NAME}.m3u8",
              "id": "audio.audio_1",
              "drms": [
                "drm1"
              ]
            },
            "video_1": {
              "media_playlist_path": "${OUTPUT_BASE_URL}/${TRACK_NAME}.m3u8",
              "id": "video.video_1",
              "drms": [
                "drm1"
              ]
            }
          }
        }
      }
    }
  }
}

Notes for TITAN File integration

  • Unlike TITAN Live, which allows simultaneous application of PlayReady and Widevine to one stream (DRM Type: Multi-DRM), VOD packaging in TITAN File can only apply one type of DRM per job.
  • When applying FairPlay DRM, the IV value must be entered correctly, and although the key ID is not used in the FairPlay specification, an error will occur if the input value is left blank when integrating TITAN File.
  • For HLS Output, the HLS Version item must be specified as 6 or higher.
Previous

Last updated on Jun 26, 2023