API Reference

Get Studio DRM Policy Configuration

Retrieves a specific Studio DRM policy configuration.

Request

Request syntax:

GET /drm/policy/[Policy ID](#PolicyID2)

Define the following variable when submitting the above request:

VariableDescription
Policy ID (Required)Replace this variable with the system-defined ID assigned to the desired Studio DRM policy configuration.

Response

The response for a successful request contains the following parameters:

NameData TypeDescription
configsList of dictionariesContains the requested Studio DRM policy configuration.
errorIntegerIndicates whether an error occurred. Learn more.

Sample Request/Response

Update the get_studio_drm_pc module to identify the policy that will be retrieved by its system-defined ID.

policy_id = 'abcdef123456ghijkl7890123mno789'

Call the get_studio_drm_pc module (Python 3) to retrieve a specific Studio DRM policy configuration. This module imports names from the api_auth module.

import requests
from api_auth import APICredentials, APIParams

class DRMPolicy:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Retrieve a DRM policy.
        """
        self._get_drm_policy()

    def _get_drm_policy(self):
        policy_id = 'abcdef123456ghijkl7890123mno789'
        url = "{}{}{}".format(self.host, "/api/v3/drm/policy/", policy_id)

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

DRMPolicy().run()

Response:

{
    'configs': [{
            '_id': 'abcdef123456ghijkl7890123mno789',
            'created': 1558566151978,
            'policy_name': 'My First Policy',
            'fairplay': {
                'key_duration_seconds': 0,
                'hd': {
                    'hdcp_enforcement': -1,
                    'allow_airplay': False,
                    'allow_av_adapter': False
                },
                'persistence_duration_seconds': 0,
                'rental_duration_seconds': 0,
                'lease_duration_seconds': 0,
                'uhd2': {
                    'hdcp_enforcement': -1,
                    'allow_airplay': True,
                    'allow_av_adapter': True
                },
                'uhd1': {
                    'hdcp_enforcement': -1,
                    'allow_airplay': True,
                    'allow_av_adapter': True
                },
                'playback_duration_seconds': 0,
                'sd': {
                    'hdcp_enforcement': -1,
                    'allow_airplay': True,
                    'allow_av_adapter': True
                },
                'rental': False,
                'persistence': False,
                'lease': False
            },
            'lmsig': '1538693547862491_10735_4271',
            'widevine': {
                'content_key_specs': [{
                        'track_type': 'ALL',
                        'security_level': 1,
                        'required_output_protection': {
                            'hdcp_srm_rule': 'HDCP_SRM_RULE_NONE',
                            'hdcp': 'HDCP_NONE',
                            'cgms_flags': 'CGMS_NONE',
                            'disable_analog_output': False
                        }
                    }
                ],
                'policy_overrides': {
                    'renewal_retry_interval_seconds': 0,
                    'can_renew': True,
                    'can_persist': True,
                    'license_duration_seconds': 86400,
                    'always_include_client_id': False,
                    'can_play': True,
                    'rental_duration_seconds': 0,
                    'renewal_delay_seconds': 0,
                    'renewal_recovery_duration_seconds': 0,
                    'playback_duration_seconds': 0,
                    'renew_with_usage': False
                }
            },
            'owner': 'abc33864a92c46a1a286cdd49b0a9123',
            'playready': {
                'license_duration_seconds': 86400,
                'can_persist': False,
                'can_play': True,
                'uhd2': {
                    'digital_video_protection_level': 250,
                    'security_level': 2000,
                    'play_enabler': False,
                    'require_hdcp_type_1': True
                },
                'uhd1': {
                    'digital_video_protection_level': 250,
                    'security_level': 2000,
                    'play_enabler': False,
                    'require_hdcp_type_1': True
                },
                'playback_duration_seconds': 0,
                'hd': {
                    'digital_video_protection_level': 250,
                    'security_level': 2000,
                    'play_enabler': False,
                    'require_hdcp_type_1': True
                },
                'sd': {
                    'require_hdcp_type_1': False,
                    'security_level': 2000,
                    'play_enabler': False,
                    'digital_video_protection_level': 100
                }
            },
            'lastmod': 1558566152020
        }
    ],
    'error': 0
}

configs List

The configs list describes one or more Studio DRM policy configurations using the following parameters:

NameData TypeDescription
_idStringIdentifies a policy by its system-defined ID.
createdIntegerIndicates the policy's creation date in Unix time (milliseconds).
fairplayDictionaryContains Studio DRM policy settings for Apple FairPlay Streaming.
lastmodIntegerIndicates the policy's last modification date in Unix time (milliseconds).
lmsigStringThis parameter is reserved for future use.
ownerStringIdentifies the CMS user associated with the policy by user ID.
playreadyDictionaryContains Studio DRM policy settings for Microsoft PlayReady.
policy_nameStringIdentifies a policy by its name.
widevineDictionaryContains Studio DRM policy settings for Google Widevine DRM.

Apple FairPlay Streaming

The fairplay dictionary describes Apple FairPlay Streaming DRM policies.

NameData TypeDescription
hdDictionaryContains the DRM policy for high definition (720p and 1080p) tracks.
key_duration_secondsIntegerDetermines the length of time, in seconds, for which the Content Key will be valid. Default value: 0
leaseBooleanDetermines whether a client may renew a lease. Playback is only allowed while the lease is valid. Default value: False
lease_duration_secondsIntegerDetermines the length of time, in seconds, during which playback will be allowed. Playback will stop upon the expiration of the lease. Default value: 0
persistenceBooleanDetermines whether offline playback is allowed. Default value: False
persistence_duration_secondsIntegerDetermines the length of time, in seconds, during which offline playback is allowed. Default value: 0
playback_duration_secondsIntegerDetermines the length of time, in seconds, for which playback will be valid. Default value: 0
rentalBooleanDetermines whether offline rental is allowed. Default value: False
rental_duration_secondsIntegerDetermines the length of time, in seconds, during which the Content Key is valid prior to initial playback. Default value: 0
sdDictionaryContains the DRM policy for standard definition (576p or less) tracks.
uhd1DictionaryContains the DRM policy for 4K ultra-high-definition video tracks.
uhd2DictionaryContains the DRM policy for 8K ultra-high-definition video tracks.

Resolution Dictionary

Each of the above dictionaries contains the following parameters that describe the Apple FairPlay Streaming DRM policy for that resolution:

NameData TypeDescription
allow_airplayBooleanDetermines whether playback will be allowed over AirPlay. Default value: True
allow_av_adapterBooleanDetermines whether playback may be mirrored via an Apple Lightning AV Adapter. Default value: True
hdcp_enforcementIntegerDetermines whether High-bandwidth Digital Content Protection (HDCP) enforcement is required. Default value: -1

Google Widevine DRM

The widevine dictionary contains the following parameters that describe a Google Widevine DRM policy:

NameData TypeDescription
content_key_specsList of dictionariesDetermines which content keys should be returned. This parameter must be specified for all tracks and should be used to define a policy when a pre-existing one has not been associated with the content. Default content key policy: [{'track_type': 'ALL', 'required_output_protection': {'hdcp_srm_rule': 'HDCP_SRM_RULE_NONE', 'hdcp': 'HDCP_NONE', 'cgms_flags': 'CGMS_NONE', 'disable_analog_output': False }, 'security_level': 1 }]
policy_overridesDictionaryDetermines the policy for the current license. The specified policy will override one assigned directly to an asset. Default policy overrides: { 'can_renew': False, 'renewal_retry_interval_seconds': 0, 'always_include_client_id': False, 'license_duration_seconds': 86400, 'can_persist': False, 'can_play': True, 'rental_duration_seconds': 0, 'renewal_delay_seconds': 0, 'renewal_recovery_duration_seconds': 0, 'playback_duration_seconds': 0, 'renew_with_usage': False }

policy_overrides Dictionary

The policy_overrides dictionary defines the Studio DRM policy that will be used instead of policies assigned directly to an asset.

NameData TypeDescription
always_include_client_idBooleanReserved for future use.
can_persistBooleanDetermines whether offline playback is allowed. Default: False.
can_playBooleanDetermines whether playback is allowed. Required. Default: True.
can_renewBooleanReserved for future use.
license_duration_secondsIntegerDetermines the length of time (in seconds) that content playback is allowed. Default: 86400.
playback_duration_secondsIntegerDefines how long a license is valid after its initial use. Used for offline or license renewal scenarios. Default: 0.
renew_with_usageBooleanReserved for future use.
renewal_delay_secondsIntegerReserved for future use.
renewal_recovery_duration_secondsIntegerReserved for future use.
renewal_retry_interval_secondsIntegerReserved for future use.
renewal_server_urlStringReserved for future use.
rental_duration_secondsIntegerDetermines how long a license remains valid before its initial use. Default: 0.

content_key_specs List

The content_key_specs list defines Studio DRM policy on a per-track basis.

NameData TypeDescription
required_output_protectionDictionaryContains key-value pairs defining protection requirements for the output. The values are case-sensitive.
security_levelIntegerDetermines the minimum security level for cryptography, content decoding, and media operations. Default: 1.
track_typeStringDefines the scope of the policy by track type. Default: ALL.

Microsoft PlayReady

The playready dictionary describes resolution-specific Microsoft PlayReady DRM policies.

NameData TypeDescription
can_persistBooleanDetermines whether offline playback is allowed. Default: False.
can_playBooleanDetermines whether playback is allowed. Default: True.
hdDictionaryContains the DRM policy for high-definition (720p and 1080p) tracks.
license_duration_secondsIntegerDetermines how long content playback is allowed before expiration. Default: 86400.
playback_duration_secondsIntegerDefines the time (in seconds) for which playback will be valid after initial playback. Default: 0.
realtime_expirationBooleanDetermines whether the current playback session stops upon license expiration. Default: True.
sdDictionaryContains the DRM policy for standard definition (576p or less) tracks.
uhd1DictionaryContains the DRM policy for 4K ultra-high-definition video tracks.
uhd2DictionaryContains the DRM policy for 8K ultra-high-definition video tracks.

Resolution Dictionary

Each of these dictionaries contains parameters describing the Microsoft PlayReady DRM policy for that resolution.

NameData TypeDescription
analog_video_protection_levelIntegerDefines minimum security requirements for analog video outputs. Default: 100.
compressed_digital_audio_protection_levelIntegerDefines security requirements for passing compressed digital audio. Default: 100.
digital_video_protection_levelIntegerDetermines digital video protection level. Default: 100.
play_enablerBooleanDetermines if playback is allowed on a VM (for testing only). Default: False.
require_hdcp_type_1BooleanEnforces HDCP content type 1 (HDCP 2.2 or later). Default: False.
security_levelIntegerDefines the minimum security requirement for client devices. Default: 2000.
uncompressed_digital_audio_protection_levelIntegerDefines security for uncompressed digital audio output. Default: 100.

Default Policy

Policy settings that are not explicitly set are defined according to the following default Studio DRM policy:

{
    "fairplay": {
        "key_duration_seconds": 0,
        "hd": {
            "hdcp_enforcement": -1,
            "allow_airplay": true,
            "allow_av_adapter": true
        },
        "persistence_duration_seconds": 0,
        "rental_duration_seconds": 0,
        "lease_duration_seconds": 0,
        "uhd2": {
            "hdcp_enforcement": -1,
            "allow_airplay": true,
            "allow_av_adapter": true
        },
        "uhd1": {
            "hdcp_enforcement": -1,
            "allow_airplay": true,
            "allow_av_adapter": true
        },
        "playback_duration_seconds": 0,
        "sd": {
            "hdcp_enforcement": -1,
            "allow_airplay": true,
            "allow_av_adapter": true
        }
    },
    "widevine": {
        "content_key_specs": [{
                "track_type": "ALL",
                "required_output_protection": {
                    "hdcp_srm_rule": "HDCP_SRM_RULE_NONE",
                    "hdcp": "HDCP_NONE",
                    "cgms_flags": "CGMS_NONE",
                    "disable_analog_output": false
                },
                "security_level": 1
            }
        ],
        "policy_overrides": {
            "can_renew": false,
            "renewal_retry_interval_seconds": 0,
            "always_include_client_id": false,
            "license_duration_seconds": 86400,
            "can_persist": false,
            "can_play": true,
            "rental_duration_seconds": 0,
            "renewal_delay_seconds": 0,
            "renewal_recovery_duration_seconds": 0,
            "playback_duration_seconds": 0,
            "renew_with_usage": false
        }
    },
    "playready": {
        "license_duration_seconds": 86400,
        "can_persist": false,
        "realtime_expiration": true,
        "can_play": true,
        "uhd2": {
            "require_hdcp_type_1": false,
            "security_level": 2000,
            "play_enabler": false,
            "analog_video_protection_level": 100,
            "compressed_digital_audio_protection_level": 100,
            "uncompressed_digital_audio_protection_level": 100,
            "digital_video_protection_level": 100
        },
        "uhd1": {
            "require_hdcp_type_1": false,
            "security_level": 2000,
            "play_enabler": false,
            "analog_video_protection_level": 100,
            "compressed_digital_audio_protection_level": 100,
            "uncompressed_digital_audio_protection_level": 100,
            "digital_video_protection_level": 100
        },
        "playback_duration_seconds": 0,
        "hd": {
            "require_hdcp_type_1": false,
            "security_level": 2000,
            "play_enabler": false,
            "analog_video_protection_level": 100,
            "compressed_digital_audio_protection_level": 100,
            "uncompressed_digital_audio_protection_level": 100,
            "digital_video_protection_level": 100
        },
        "sd": {
            "require_hdcp_type_1": false,
            "security_level": 2000,
            "play_enabler": false,
            "analog_video_protection_level": 100,
            "compressed_digital_audio_protection_level": 100,
            "uncompressed_digital_audio_protection_level": 100,
            "digital_video_protection_level": 100
        }
    }
}