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).

In a sequence diagram, it looks like this:

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.
When using fragmented media hosted on remote storage, its recommended to generate a dref mp4 for each source file and host this alongside the fragmented media. This can greatly improve the performance and response time when either Unified Origin and/or Unified Remix are required to read the media from remote storage. As the metadata for each track is storage in the dref, its means the file needs to read fewer times then if the fragmented media was being read directly.

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 \
  mod_unified_s3_auth

# 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.

Enable Apache SubRequests

Since version 1.11.3 GA mod_unified_remix now supports Apache subrequests to handle HTTP(s) requests to remote storage similar to Origin. When enabled, significant performance and stability gains can be be achieved between the Remix server and the backend storage. cURL functionality is unchanged and backward compatibility for existing setups is maintained.

To enable this, add the following webserver directive.

<Location "/">
  UspEnableSubreq on
</Location>

Note

For more information on the benefits of Apache's SubRequests, please see our Cloud Storage Proxy.

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.
<Location "/">
  ProxyPass "${SMIL_URL}"
  ProxyPassReverse "${SMIL_URL}"
</Location>

<Proxy "${SMIL_URL}">
  ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
  RequestHeader unset Accept-Encoding
</Proxy>

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>

Configure a Proxy for accessing S3 remote storage (optional)

In case your media is hosted on remote storage it may be necessary to configure an additional Proxy directive in your virtual host configuration.

Alongside this, your storage may only be accessible using S3 authentication. Therefore it may be necessary to also install mod_unified_s3_auth and set the correct S3AccessKey, S3SecretKey and S3Region directives, and optionally S3SecurityToken directives.

<Proxy "${S3_URL}">
  ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
  RequestHeader unset Accept-Encoding
  S3AccessKey ${S3_ACCESS_KEY}
  S3SecretKey ${S3_SECRET_KEY}
  S3Region ${S3_REGION}
  S3SecurityToken ${S3_SECURITY_TOKEN}
</Proxy>

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:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule ssl_module modules/mod_ssl.so

LoadModule unified_remix_module modules/mod_unified_remix.so
LoadModule unified_s3_auth_module modules/mod_unified_s3_auth.so


ServerName remix-origin

UspLicenseKey /etc/usp-license.key

LogFormat '${LOG_FORMAT}' log_format

<VirtualHost 0.0.0.0:80>
  CustomLog /dev/stdout log_format
  ErrorLog /dev/stderr

  LogLevel ${LOG_LEVEL}

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

  # Do not get byteranges from the backend. We require an entire, unbroken
  # response from the backend.
  RequestHeader unset Range

  Header set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
  Header set Access-Control-Allow-Origin "*"

  SSLProxyEngine on

  <Location "/">
   UspEnableSubreq on
  </Location>

  # This specifies the address to fetch the .smil file from.
  <Location "/">
    ProxyPass "${SMIL_URL}"
    ProxyPassReverse "${SMIL_URL}"
  </Location>

  <Proxy "${SMIL_URL}">
    ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
    RequestHeader unset Accept-Encoding
  </Proxy>

  <Proxy "${S3_URL}">
    ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
    RequestHeader unset Accept-Encoding
    S3AccessKey ${S3_ACCESS_KEY}
    S3SecretKey ${S3_SECRET_KEY}
    S3Region ${S3_REGION}
    S3SecurityToken ${S3_SECURITY_TOKEN}
  </Proxy>


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

</VirtualHost>

How to Configure (Unified Remix)

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

Running Unified Remix dynamically (as an Apache module)

Enable correct Apache modules for Remix

Configure virtual host for Remix

Specify license key

Enable Apache SubRequests

Pass on requests to SMIL origin using ProxyPass

Rewrite requests before passing them on to SMIL origin

Remove byte ranges from incoming requests

Enable Unified Remix to generate remixed MP4 from SMIL

Configure a Proxy for accessing S3 remote storage (optional)

Example of fully configured virtual host

Enable correct Apache modules for Remix 

Configure virtual host for Remix 