How to Configure (Unified Remix)

Running Unified Remix statically (as a command-line tool)

To run Remix statically, as a command-line tool, no specific configuration is necessary. Simply follow the installation instructions as detailed in How to Install.

When you run Unified Remix as a command-line tool you specify a playlist as your input (like playlist.smil in the example below) and an MP4 as your output (like remixed.mp4 in the example below).

In the playlist you define the stream that you want to create, then from it Remix will generate the remixed MP4 that Unified Packager or Unified Origin can use to package and deliver the actual stream:

#!/bin/bash

unified_remix -o remixed.mp4 playlist.smil

For further documentation about the different Unified Remix use cases and how to set them up, please refer to Unified Remix.

Note

Running Unified Remix statically is easier to set up than running Unified Remix dynamically. A static setup is ideal when you can process your content beforehand (e.g., when you know which clips to add as a pre-, mid- or postroll, or when you know where and what type of SCTE 35 markers to add). However, if you want Remix to personalize a stream based on requests, or if you in any other way require a more flexible setup where Remix processes your content on-the-fly, running Remix dynamically is what you need (see below).

Running Unified Remix dynamically (as an Apache module)

Running Remix dynamically is very powerful, as it allows for much more personalization than when running it statically. In a static approach you process all content beforehand, while you can process content on-the-fly in a dynamic setup, based on incoming requests.

A full dynamic Remix setup looks like below. To deliver the remixed content, you need to run Unified Origin VOD, too. And to dynamically generate the SMIL playlists that specify the content of a stream, you'll need to run a server that will generate those playlists (e.g., based on information contained in the request, certain rule sets, and information available from ad networks and a broadcast EPG).

../_images/vod_overview.svg

In a sequence diagram, it looks like this:

../_images/vod_sequence1.svg

To run Remix dynamically (i.e., as a module for Apache, similar to Origin) you first need to install Apache and the Unified Remix module. This is detailed in How to Install. Then you need to complete the following steps:

Note

  • To stream content that is dynamically remixed by Unified Remix, you need to run Unified Origin VOD, too. Installing and configuring Origin, works similar to Remix, see How to Install and How to Configure (Unified Origin).
  • Putting a caching proxy in front of Remix is highly recommend. It ensures that Remix needs process identical requests only once, as subsequent requests of the same type will be handled by the caching proxy.

Enable correct Apache modules for Remix

Enabling the correct Apache modules for Remix works similar to configuring Origin.

Like Origin, Remix requires Apache's MPM model to be set to 'worker' (or 'prefork') instead of the default 'event' (for more information on MPM models, see the Apache documentation).

The difference is that mod_headers is not the only default Apache module that you need to enable, but also mod_ext_filter, mod_proxy, mod_rewrite. And, of course, instead of mod_smooth_streaming you need to enable mod_unified_remix.

For more info on loading modules into Apache, please see LoadModule.

In short, you can run the following on Debian / Ubuntu:

# Disable the default MPM module 'event'
sudo a2dismod mpm_event

# Enable MPM module 'worker' and other necessary modules
sudo a2enmod mpm_worker \
  headers \
  ext_filter \
  proxy \
  proxy_http \
  rewrite \
  mod_unified_remix

# Restart Apache to reload and check configuration
sudo service apache2 restart

And, to check whether all required modules have indeed been enabled, you can run (works on all Linux distributions):

sudo apache2ctl -M | sort

Note

refer to the Origin related instructions for Basic Apache configuration on Linux to see how and where you can enable (or disable) Apache modules on other Linux distributions, or for Windows: Basic Apache configuration on Windows.

Configure virtual host for Remix

The configurations below apply to both the Windows and the Linux platform, though the exact location of the virtual host configuration will differ for both of these platforms and between different Linux distributions. For more information on configuring virtual hosts, please consult Apache's official documentation on the VirtualHost directive.

Specify license key

To specify your license key on Linux, add the UspLicenseKey directive to the file containing your virtual host configuration, but add it outside of the configuration of the virtual host itself. Use the directive to point to the file in which you have stored your license key as shown below (where </path/to/usp-license.key> should be replaced to point to the correct location):

UspLicenseKey </path/to/usp-license.key>

<VirtualHost *:80>

  # Rest of config

</VirtualHost>

Note

Specifying your license key on Windows works slightly different, see: Specifying your license key.

Pass on requests to SMIL origin using ProxyPass

In a fully dynamic setup, Remix will fetch the SMIL playlist that it uses as input from a SMIL origin that generates these playlists. In order to make this work, a ProxyPass directive is configured to pass on the incoming request to the SMIL origin.

Therefore, add the following to your virtual host, where {{SMIL_URL}} needs to be replaced by the actual URL of your SMIL origin, and the configuration options can be specified according to your prefences:

# This specifies the address to fetch the .smil file from.
ProxyPass / {{SMIL_URL}} connectiontimeout=5 timeout=30 disablereuse=on retry=0

Rewrite requests before passing them on to SMIL origin

In order for the SMIL origin to receive a request for a .smil instead of a .mp4 file, the incoming request that Remix will pass on based on the configuration of the ProxyPass directive, must be rewritten to change the extension.

To do this, Apache's RewriteEngine must be enabled and the following RewriteRule must be added (if necessary, adjust it according to your exact setup):

# Change the extension of the request from .mp4 to .smil before handling the
# request with ProxyPass.
RewriteEngine On
RewriteRule "^(.*)\.mp4$" "$1.smil" [PT,L,QSA]

Remove byte ranges from incoming requests

An incoming request may contain a byte range header, but for Remix to work and generate a correct remixed MP4, that header needs to be unset using the RequestHeader directive, as shown below:

# Do not get byteranges from the backend as Remix requires an entire, unbroken
# response from the backend.
RequestHeader unset Range

Enable Unified Remix to generate remixed MP4 from SMIL

Finally, now the virtual host for Remix is set up to correctly pass on incoming requests so that a SMIL playlist will be returned, the actual Remix functionality needs to be enabled so that SMIL playlist will be transformed into a remixed MP4.

This is done by setting a SetOutputFilter to REMIX on with a LocationMatch to extension .smil:

# Transform the SMIL into a remixed MP4.
<LocationMatch "\.smil$">
  SetOutputFilter "REMIX"
</LocationMatch>

Example of fully configured virtual host

And, to give you an idea of how a completely configured virtual host looks like, see the following example:

UspLicenseKey /etc/usp-license.key
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %D" log_format

<VirtualHost *:80>
    DocumentRoot "/var/www"
    ServerName remix.example.com

    ProxyPass / http://smil-proxy/ connectiontimeout=5 timeout=30 disablereuse=on retry=0

    RewriteEngine On
    RewriteRule "^(.*)\.mp4$" "$1.smil" [PT,L,QSA]

    RequestHeader unset Range

    <LocationMatch "\.smil$">
      SetOutputFilter "REMIX"
    </LocationMatch>

    CustomLog /var/log/remix-origin-access.log log_format
    ErrorLog /var/log/remix-origin-error.log

    LogLevel warn

</VirtualHost>