License Key

Obtaining a License Key 

You can get an evaluation key by clicking the following button:

This will take you to the trial page where you can select one of the available trials for for instance for static/dynamic packaging, live streaming, virtual channels and more.

You will be asked for your name and email address (first time access), after that you can choose a trial guide or copy the license key and continue with the Docker Express Your own Video on Demand demo or the general How to Install instructions.

Using the License Key 

By default the commandline executables will look for an environment variable called UspLicenseKey and use this as input for the license key. This applies to the following executables:

mp4split
unified_capture
unified_remix

The environment variable is set as follows:

export UspLicenseKey="YmFzZTY0IGVuY29kZWQgbGljZW5zZSBrZXkgc3RyaW5nCg=="

If this variable is not present then you are required to pass the key on the command line with the --license-key option:

mp4split --license-key=/path/to/usp-license.key \
  -o oceans.ism \
  oceans.mp4

or for instance with unified_capture:

unified_capture --license-key=/path/to/usp-license.key \
  -o oceans.ismv \
  http://example.com/channel01/channel01.isml/Manifest

License key wrapper

For convenience we recommend exporting the license key string as an environment variable called UspLicenseKey which mp4split will use as default when --license-key is not used.

Its recommended to set this variable and any subsequent alias' in your .bashrc.

As an alias:

export UspLicenseKey="YmFzZTY0IGVuY29kZWQgbGljZW5zZSBrZXkgc3RyaW5nCg=="

alias mp4split="/path/to/mp4split $@"

Or a function:

export UspLicenseKey="YmFzZTY0IGVuY29kZWQgbGljZW5zZSBrZXkgc3RyaW5nCg=="

function mp4split() {
  command mp4split $@
}

Once the UspLicenseKey environment variable has been exported, it's possible to use to run one of our public container images (using Docker).

# Using our publically available container image
# run latest public mp4split release
mp4split() {
  BASE_IMAGE=docker.io/unifiedstreaming/mp4split
  case $1 in
    1.[0-9]*.[0-9]* ) IMAGE=${BASE_IMAGE}:$1; shift ;;
    * ) IMAGE=${BASE_IMAGE}:latest; docker pull $IMAGE ;;
  esac
  docker run -it -e UspLicenseKey -v ${PWD}:/data --workdir /data $IMAGE "$@"
}

It's also possible to set an environment variable as the path to your key which can then be passed to the command line using the --license-key option.

As an alias:

# Alternative option
USP_LICENSE_KEY="/path-to/usp-license.key"

function mp4split() {
  command mp4split --license-key=${USP_LICENSE_KEY} $@
}

Or a function:

# Alternative option
USP_LICENSE_KEY="/path-to/usp-license.key"

alias mp4split="/path/to/mp4split --license-key=${USP_LICENSE_KEY} $@"

Apache License Key

For Apache, the UspLicenseKey server directive must be used which may be placed in the vhost conf file before the actual virtual host:

UspLicenseKey /path/to/usp-license.key

<VirtualHost *:80>

  # Rest of config

</VirtualHost>

Note

A single license allows for ten (10) live channels per origin, there is no limit on the number of bitrates in the license key.

Installation Check 

After (re)starting Apache you should see the following in the Apache error.log (/var/log/apache2/error.log on Ubuntu):

License key found: /path/to/usp-license.key
Apache/2.4.7 (Ubuntu) IISMS/4.0 configured -- resuming normal operations

To check your license using mp4split, use the --license-key option together with the --show-license option described in the section below.

Features and Expiry 

To show which features are supported for a certain license key or to check when the license will expire, use the --license-key option together with the --show-license option, and no other command line arguments:

#!/bin/bash

mp4split --license-key=/path/to/usp-license.key --show-license

If the license is valid, and not expired, this will print feature information in a format similar to:

mp4split version=1.10.11 (18541)    Copyright 2007-2019 CodeShop B.V.

Product name: Unified Streaming Platform
License type: production
License email: license@unified-streaming.com
Starting at: 2021-01-30 00:00:00 UTC
Expiring at: 2022-02-01 00:00:00 UTC
Supported features:
  Packaging: DASH, HDS, HLS, ISS, MP4, CMAF
  Capturing: DASH, HDS, HLS, ISS, Decryption
  Verifying: Media, URLs, Sitemap
  Streaming: VOD, Live, MPEG-TS
  Remixing: VOD
  Encoding: AAC, AVC, HEVC
  Decoding: AAC, AVC, HEVC
  Metadata: Timed Metadata
  DRM: AES, DXDRM, FAXS, Marlin, PlayReady, Sample_AES, Verimatrix_HLS, Irdeto_SKE, Conax_PR_HLS, Widevine, PlayReady_Envelope, PHDS

Monitoring 

Next to the the email address used for the license email (see example above) receiving license expiry warnings 90, 60 and 30 days in advance, it is a good idea to also monitor the license key where it is used.

Options to do so are for instance the following:

run mp4split --show-license and post result to internal monitoring
restart apache periodically and check license printed in the error.log
parse license key upon arrival and track time to flag internally when expiry is near
have the webserver load the license key from another location, where expiry is checked periodically

Note

A benefit of the last is that all servers load from the same location, so license key renewal is 'replace and reload' in a specific maintenance windwow.

The first solution could look like the following:

the cronjob:

MAILTO="ops@example.com"
PATH="/usr/bin:/sbin:/bin"
HOME="/root"
SHELL=/bin/bash
@daily /root/key-check-daily 2>&1 | /usr/bin/logger -t key-check-daily

the key-check-daily script:

#!/bin/bash

/usr/bin/mp4split --license-key /etc/usp-license.key --show-license > /tmp/key-options
/usr/bin/curl curl -X POST -d @/tmp/key-options http://monitoring-server/key-check

The 'monitoring-server' mentioned above in turn can parse out the 'Starting at: ' and 'Expiring at: ' UTC timestamps present in 'key-options' string sent. Standard monitoring tools like ELK could be a good fit.

Location 

New in version 1.10.33.

An alternative to placing the license key on the instance where it is used (typically as /path/to/usp-license.key) is to use a URL.

For instance with mp4split:

mp4split --license-key https://key-store/my.key --show-license

or for Apache:

UspLicenseKey "https://key-store/my.key"

The 'key-store' mentioned can be any kind of HTTPS accessible location capable of responding to the HTTPS GET request with a key.

Warning

Please make sure such a 'key-store' is only accessible to allowed license key requests.

Setting up the license key like this seperates license from instance and as such for instance allows for simultaneous update of all instances that use the same license key, or update in batches (when the same license key is used but different URL). In short, it provides greater freedom how to manage keys.

Attention

The URL must resolve to a license key. If it does not both mp4split and Apache will not work correctly and print an error (to the console or to the error log, see Error Messages below).

Error Messages 

Errors related to the license key are described below.

'no policy for'

If a call to mp4split (or the webserver) results in for instance the following it means the required permission is not part of the license:

Status: 403 FMP4_403
X-USP-Error: drm: no policy for Widevine encryption

This message will be printed in the Apache error log or in the shell (stdout). Please contact license@unified-streaming.com.

'verify license signature not valid'

The key is meant for a different version (for instance trying a 1.6 key with a 1.7 version)

'license expired'

The license expired, please contact license@unified-streaming.com.

'base64_decode: unexpected end of file'

If you get the following error in your Apache error.log:

terminate called after throwing an instance of 'fmp4::exception'
what(): 415 FMP4_415 (base64_decode: unexpected end of file?)

please check you copied the license key correctly.

You can for instance test with

#!/bin/bash

mp4split --license-key=/path/to/usp-license.key --show-license

where YOUR_LICENSE_KEY is the key you received.

'keyfile not found'

This means the license key cannot be found. Please refer to the License Key page on how to install it:

Apache License Key

Using the License Key

Using the License Key

'could not connect to host'

Evaluation versions require internet access to the following:

Google's DNS servers (8.8.8.8:53/8.8.4.4:53)
keys.unified-streaming.com (46.23.86.208:80)

Please make sure your firewall settings allow this.

If this is not set up the resulting error will look like the following:

apache mod_smooth_streaming (version=1.7.10) failed to initialize! (error
message: could not connect to host), please contact license@unified-streaming.com