Playback URLs

• Generate playback URLs for:
  • Assets
  • Virtual linear playlists
  • Live channels
  • Live events
• Sign playback URLs with a token
  • Basic Setup
    • Core identification parameters
    • Signature parameter
  • Encrypt query strings
• Validate playback URLs using application keys

Assets #

• Asset ID (GUID): Identifies an asset for playback by its system-defined ID.
• External ID (Asset): Identifies an asset for playback by its external ID.

• By default, the above playback URLs play an entire asset from start to finish. Alternatively, playback may be restricted to a portion of an asset.
• A media player may play multiple assets within a single viewing experience by identifying each desired asset within the playback URL.

Asset ID #

Find Asset ID #

1. Navigate to the CMS library by clicking the Content tab.
2. Select the desired asset.
3. The asset ID corresponding to the selected asset is listed under the GUID label.

External ID (Asset) #

• User ID: Specify the user ID that corresponds to the owner of the content.
  • Your CMS Libraries: Specify your user ID.
  • Shared CMS Libraries: Specify the user ID corresponding to the user that shared the library.
• External ID (Asset): A custom ID, known as an external ID, may be assigned to an asset. Typically, this ID reflects a unique value defined in an external database.
  • An external ID may only consist of alphanumeric characters, dashes, and underscores. All other characters, including spaces, are disallowed.
  • External IDs are not tested for validity or uniqueness. An arbitrary matching asset will be played back when multiple assets within a single CMS account have been assigned the same external ID.
  • Use the _replace: prefix while slicing to reuse an external ID when re-encoding a new version of an existing asset.
• HLS Syntax: https://content.uplynk.com/ext/{User ID}/{External ID}.m3u8
• DASH Syntax: https://content.uplynk.com/ext/{User ID}/{External ID}.mpd
• Sample Playback URL (HLS): Use the following playback URL to stream an asset with an external ID of promo_video_12 that is owned by a user whose ID is f8c29a5f6c4e229c20f7307f8c3122ab.
  https://content.uplynk.com/ext/f8c29a5f6c4e229c20f7307f8c3122ab/promo_video_12.m3u8

Find an Asset’s External ID #

1. Navigate to the CMS library by clicking the Content tab.
2. Select the desired asset.
3. The external ID corresponding to the asset selected in the previous step is listed under the External ID option.

Segment (Ad Breaks) #

• Server-side ad insertion ensures seamless ad integration. As a result, this type of playback URL is typically reserved for legacy client-side ad integrations or non-video ad integrations in which video playback is temporarily suspended.
• Typically, the use of this type of playback URL for assets undergoing slicing or encoding is strongly discouraged.
• Playback by segment is only supported for assets that contain ad breaks.
• This type of playback URL is only supported for HLS playback.
• An asset that contains one or more ad breaks will be split into segments.

  

• Segments are identified by a 0-based sequential number. This means that the index number for the first segment will be 0, the second segment will have a value of 1, the third segment will have a value of 2, etc.

Sample Playback URLs #

Start/Stop Playback by Time or Slice #

• Starting Point: Specify a starting time for playback in seconds (start) or slice numbers (sstart).
• Stopping Point: Specify a stopping time for playback in seconds (stop) or slice numbers (sstop).

Play Multiple Videos #

• Both asset ID and external ID playback URLs may point to multiple assets by adding a comma-delimited list of each desired asset and then setting the file name to /multiple.m3u8 (HLS) or /multiple.mpd (DASH).
  • Asset ID-based playback URL syntax:
    https://content.uplynk.com/{Asset ID 1},{Asset ID 2},{Asset ID n}/multiple.{Extension}
    (e.g., https://content.uplynk.com/7731125f336c4e229c20f7307f8c3122,6eb8d50020884a1c8bd4c11a38406f14/multiple.m3u8)
  • External ID-based playback URL syntax:
    https://content.uplynk.com/ext/{User ID}/{External ID 1},{External ID 2},{External ID n}/multiple.{Extension}
    (e.g., https://content.uplynk.com/ext/357c9b19d40447989389e6a20f19d55e/pre-show,show,post-show/multiple.m3u8)
  • Sample asset ID-based playback URL: The following sample playback URL demonstrates the proper syntax for the playback of two assets whose IDs are 7731125f336c4e229c20f7307f8c3122 and 6eb8d50020884a1c8bd4c11a38406f14.
    https://content.uplynk.com/7731125f336c4e229c20f7307f8c3122,6eb8d50020884a1c8bd4c11a38406f14/multiple.m3u8
  • Sample external ID-based playback URL: The following sample playback URL demonstrates the proper syntax for the playback of three assets whose external IDs are pre-show, show, and post-show. This example assumes that these assets belong to a user whose user ID is 357c9b19d40447989389e6a20f19d55e.
    https://content.uplynk.com/ext/357c9b19d40447989389e6a20f19d55e/pre-show,show,post-show/multiple.m3u8
• The specified assets will be played back-to-back in the listed order. Ad breaks associated with each asset will behave as expected.
• The total duration of the assets requested using a single playback URL must be less than 16 hours.
• All assets defined within a single playback URL must be owned by the same account.
• Do not specify an asset more than once per playback URL.
• Assets that are in the process of being sliced or encoded cannot be combined and therefore should not be included in a playback URL that points to multiple assets.
• Use the ad.caid query string parameter to define the asset ID that will be sent to an ad server.

Virtual Linear Playlists #

• Use the virtual linear playlist’s skip_drm property to determine whether a digital signature is required. This property overrides an asset’s Require a token for playback setting.
• Use the virtual linear playlist’s studio_drm_required property to determine whether it will be protected by Studio DRM. This property overrides an asset’s Require studio approved DRM for playback setting.
• If you plan on implementing a timeline within your player, use the dmm.schemas.top and pltl query string parameters to include timeline data within the manifest. Learn more.
  The pltl query string parameter is optional for Smartstart-enabled assets.
• Learn more about virtual linear playlists and Smartstart.

Live Channels #

• Channel ID (GUID): Identifies a live channel for playback by its system-defined ID.
• External ID (Channel): Identifies a live channel for playback by its external ID.

Channel ID (GUID) #

1. From the CMS, click the Live Channels tab.
2. Select the desired live channel. Basic options and live channel information will be displayed on the Details tab.
3. Find the live channel’s system-defined ID under the GUID label.

External ID (Channel) #

• User ID: Specify your user ID.
  Find my user ID:
  1. Load the User Settings page via Settings > User Settings.
  2. Your user ID is listed under the User ID label.
• External ID (Channel): This external ID is a custom ID that may be assigned to a live channel. Typically, this ID reflects a unique value defined in an external database.
  Key information:
  • An external ID may only consist of alphanumeric characters, dashes, and underscores. All other characters, including spaces, are disallowed.
  • External IDs are not tested for validity or uniqueness. An arbitrary matching live channel will be played back when multiple live channels within the same account have been assigned the same external ID.

1. From the CMS, click the Live Channels tab.
2. Select the desired live channel. Basic options and live channel information will be displayed on the Details tab.
3. The live channel’s external ID is listed under the External ID option.

Live Events #

• Event ID (GUID): Identifies a live event for playback by its system-defined ID.
• External ID (Event): Identifies a live event for playback by its external ID.

Event ID (GUID) #

1. Navigate to the Live Events page via Events > Live Events.
2. Select the desired live event.
3. Verify that the Details tab is selected.
4. Find the live event’s system-defined ID under the GUID label.

External ID (Event) #

• User ID: Specify your user ID.
  Find my user ID:
  1. Load the User Settings page via Settings > User Settings.
  2. Your user ID is listed under the User ID label.
• External ID (Event): This external ID is a custom ID that may be assigned to a live event. Typically, this ID reflects a unique value defined in an external database.
  Key information:
  • An external ID may only consist of alphanumeric characters, dashes, and underscores. All other characters, including spaces, are disallowed.
  • External IDs are not tested for validity or uniqueness. An arbitrary matching live event will be played back when multiple live events within the same account have been assigned the same external ID.

1. Navigate to the Live Events page via Events > Live Events.
2. Select the desired live event.
3. Verify that the Details tab is selected.
4. Find the live event’s system-defined ID under the External ID label.

Sign Playback URLs with a Token #

1. From the CMS, perform one of the following:
   • Asset: Select the desired asset from the Content tab and then click the Playback tab.
   • Live Channel: Select the desired live channel from the Live Channels tab and then click the Playback tab.
   • Live Event: Open the desired live event from the Live Events page and then click the Config tab.
2. Toggle the state of the Require a token for playback option to determine whether the playback URL must be signed.
3. Click Save.

Exceptions #

• Test players
• HTML embed code

• Please take care when distributing or sharing test players or HTML embed code. Either one may be used to play your content without restrictions.
  Playback via HTML embed code may be restricted to specific domains via the Allowed Domains option.
  Test players are designed to facilitate testing and demos.
• A test player may be invalidated by clicking the icon that appears next to it, while HTML embed code may be expired by clicking Expire. Upon saving your changes, a new test player or HTML embed code may be automatically generated.
  Prevent test players from being automatically generated by marking the Enable option under the Prevent Auto Creating Test Players section of the Test Player Restrictions page.

Basic Setup #

• Core identification parameters: Include these required parameters in order to identify playback content, its owner, and the playback window.
• Customization parameters: Include these optional parameters to customize how content playback is handled.
• Signature parameter: Append the sig parameter to the end of the query string to digitally sign the playback URL based off of the specified core identification and customization parameters.

Core Identification Parameters #

Core Identification Parameter Examples #

Digital Signature #

• Generate a hash-based message authentication code (HMAC) under the following conditions:
  • Algorithm: SHA-256
  • Secret Cryptographic Key: Your API key (Integration Keys page > Settings > Integration Keys > API Keys)
• Data: All core identification and customization query string parameters defined in the playback URL. Do not include the question mark that delimits the base URL from the query string.
  Use a server-side script to generate an HMAC. Otherwise, your API key will be exposed and potentially allow your content to be played back without restrictions.
• Set the sig parameter to the hashed message generated for the current playback URL and then append it to the query string. The sig query string parameter must be the final parameter in the playback URL’s query string.

• Core identification parameters:
  tc=1&exp=1358341863&rn=4114845747&ct=a&cid=ea10fa402fec4bbe996019a0827e6c38
• Customization parameter: ray=abc
  This parameter restricts playback to rays A, B, and C.
• API key: WxQpQhHFmE4hTWA4TGLu6rYeNuKgYrWwlCLmSKRb

Sample Code #

1import hashlib, time, hmac, urllib.parse, random
2
3# Update to your API key.
4apiKey = 'WxQpQhHFmE4hTWA4TGLu6rYeNuKgYrWwlCLmSKRb'
5
6# Set to all of the playback URL's query string parameters except the signature.
7queryStr = urllib.parse.urlencode({
8    'tc': '1', # token check algorithm version
9    'exp': int(time.time()) + 60, # expire 60 seconds from now
10    'rn': str(random.randint(0, 2**32)), # random number
11    'ct': 'a', # an asset
12    'cid': 'ea10fa402fec4bbe996019a0827e6c38', # the asset's ID
13    'rays': 'dcba', # customization parameter
14})
15
16# Compute the signature and add it to the *end*
17sig = hmac.new(apiKey.encode('utf-8'), queryStr.encode('utf-8'), hashlib.sha256).hexdigest()
18
19queryStr = queryStr + '&sig=' + sig
20
21# Add the query string to the playback URL.
22url = 'https://content.uplynk.com/ea10fa402fec4bbe996019a0827e6c38.m3u8'
23url = url + '?' + queryStr

1<?php
2// inputs
3$apiKey = "WxQpQhHFmE4hTWA4TGLu6rYeNuKgYrWwlCLmSKRb" // from the CMS UI
4
5// combine all of the parameters
6$msg = array();
7$msg["tc"] = "1"; // token check algorithm version
8$msg["exp"] = time() + 60; // expire 60 seconds from now
9$msg["rn"] = rand(); // random number
10$msg["ct"] = "a"; // an asset
11$msg["cid"] = "ea10fa402fec4bbe996019a0827e6c38"; // asset ID
12$msg["rays"] = "dcba"; //customization parameter
13
14// Calculate signature
15$msg["sig"] = hash_hmac("sha256", http_build_query($msg), $apiKey);
16
17// Add the query string the playback URL.
18$url = 'https://content.uplynk.com/ea10fa402fec4bbe996019a0827e6c38.m3u8'
19return $url . '?' . http_build_query($msg);

Encrypt Query Strings #

1. Generate a Query String Value that signs your playback URL.
2. Copy an API Key. Find your API key via Integration Keys page > Settings > Integration Keys > API Keys.
3. Generate an MD5 Hash of your chosen API key. This hash should be exactly 16 bytes (128 bits) long.
4. Encrypt the Query String:
   • Use AES-128 in CBC mode for encryption.
   • Use the MD5 hash as the key for this operation.
   • Use 16 null bytes as the initialization vector.
5. Base64 Encode the Encrypted Result:
   • Perform URL-safe Base64-encoding on the encrypted result.
   • This typically involves replacing all + characters with - and all / characters with _. Some languages and libraries have URL-safe-specific functions for this purpose.
6. Set the Playback URL’s Query String:
   • Syntax:

     1?cqs=Base64EncodedQueryString&kid=APIKeyID

   • API keys and their IDs are listed next to each other within the CMS.
   • If a playback URL contains both cqs and kid parameters, our system will:
     • Decrypt the value assigned to cqs using the API key identified by the kid parameter.
     • Establish a normal playback session using the information from the decrypted string.

Sample Code #

1import base64
2import hashlib
3
4from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
5from cryptography.hazmat.primitives.padding import PKCS7
6from cryptography.hazmat.backends import default_backend
7
8API_KEY = b'cL8Z0+DHCJZqpsN6/tlB01oyxFfeElj3t7PnwWRI'
9KEY_ID = 'ad5ba943177f4a1587795a9ee8d47293'
10
11MD5_KEY = hashlib.md5(API_KEY).digest()
12
13# This query string is signed for an asset with an asset ID of 340ca73eb07c4f4ca08b804c47a91f1b,
14# owned by a user with a user ID of ba8cb548202840d48d1255885d7bb2f3
15SIGNED_QUERY_STRING = b'ad=fwvod&cid=340ca73eb07c4f4ca08b804c47a91f1b&oid=ba8cb548202840d48d1255885d7bb2f3&exp=1492596978713&test=1&rn=310292100&tc=1&ct=a&sig=2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f'
16
17def encrypt_aes_128_cbc(key, data):
18    backend = default_backend()
19    aes = algorithms.AES(key)
20    iv = b'\x00' * 16  # Initialization vector of 16 null bytes
21    cbc = modes.CBC(iv)
22    padder = PKCS7(aes.block_size).padder()
23    padded_data = padder.update(data) + padder.finalize()
24
25    encryptor = Cipher(aes, cbc, backend).encryptor()
26    result = encryptor.update(padded_data) + encryptor.finalize()
27    return result
28
29# Encrypt the query string using the MD5 hash of the selected API key
30crypted_qs = encrypt_aes_128_cbc(MD5_KEY, SIGNED_QUERY_STRING)
31
32# Encode the encryption result as URL-safe base64
33encoded_qs = base64.urlsafe_b64encode(crypted_qs).decode("utf-8")
34
35new_params = {'cqs': encoded_qs, 'kid': KEY_ID}
36
37# This will be the new playback URL to request from our system.
38url_with_crypted_qs = 'https://content.uplynk.com/340ca73eb07c4f4ca08b804c47a91f1b.m3u8?cqs={cqs}&kid={kid}'.format(**new_params)
39
40print(url_with_crypted_qs)
41
42### Value of `url_with_crypted_qs` is:
43### https://content.uplynk.com/340ca73eb07c4f4ca08b804c47a91f1b.m3u8?cqs=gYXTAVtWRvk0qCs8pM9CmgprLvyQt9jNDETBL4ApLCqf2iFh-c9tXSk2Q_EbAAFc4q19KTikvqx8-StlruVaLafXU2NciESn-ZNPa-thp8UXSWwKszIp8oBjx8SJr9fcwUmu9El-w2q9lQ61nu1pk1JxomEraZAtfie9k8f5vAklpyYg5Ejd6i7iokxFO1XflOJFkhnDHp1ozCXVgh-rYKuCbbOEUwAaGYgd4zjn88GBgO1ZY8Jn3OFyGssvOydsPAnRjQmPsfFE24wYsp1Mlg==&kid=ad5ba943177f4a1587795a9ee8d47293

Scheme (HTTP vs HTTPS) #

Application Keys #

1. Add an Application Key:
   • Navigate to the Integration Keys page.
   • Go to the Application Keys section.
   • In the Key Name option, assign a name to the application key.
   • Click + Add to generate a value for the application key.
2. Update Your Application:
   • Pass the application key to our client SDK.
   • Although application keys are displayed in the CMS as a string value, they should be treated as binary data. For example, if the CMS shows an application key of "88051e9b", the actual value is the following sequence of bytes: 0x88 0x05 0x1E 0x9B. Take steps to protect your application against reverse engineering.
3. Enable Application Keys:
   • Include the ak configuration parameter in the playback URL’s query string.
   • Upon including this parameter, the signed playback URL will only work with an application key.
4. Modify the Playback URL: Change the file extension defined in the playback URL from "m3u8" to "json".
   Sample Playback URL: https://content.uplynk.com/channel/ext/8bb3fcf33d134160848b3051fa15ea21/live_feed_east.json?tok=...

How It Works #

More Information #