HTTP Proxy

Dynamic manifests

Specify a proxy for Unified VOD/LIVE for fetching the server manifest file. This is useful for dynamically updating options like DRM settings, encryption keys, enable/disable play-out that are managed by your CMS.

Schematically:

          GET
  [CMS]   <--   [origin]  <-- client request
video.ism     IsmProxyPass

Apache

For Apache the IsmProxyPass configuration key is specified in a Directory tag.

<Directory "/var/www/video/proxy" >
    IsmProxyPass http://other-server/
</Directory >

Nginx

For Nginx the ism_proxy_pass configuration key is specified in a location:

location ^~ /video/proxy/ {
  ism_proxy_pass http://other-server/;
  usp_handle_ism;
}

Warning

Please note that when using Nginx, the 'other-server' may not be Nginx as well: Nginx will 'hang' waiting for the request to itself to finish - which never will happen. See What is the preferred webserver for media delivery? for further background.

How it works

When the IsmProxyPass configuration is present, then the webserver module requests the server manifest file from the server specified by the URL.

For example, a request for:

http://www.example.com/video/proxy/alvin/alvin.ism/alvin.m3u8

would normally read the server manifest file from:

/var/www/video/proxy/alvin/alvin.ism

but with the IsmProxyPass enabled it fetches it from:

http://other-server/alvin/alvin.ism

instead: all urls with 'proxy' in the path will map to the other-server.

Please note the trailing / in the URL used for IsmProxyPass, this is mandatory.

The directive should be in the vhost config: /etc/apache2/sites-enabled/vhost.conf and not the global webserver config, /etc/apache2/apache2.conf.

The 'proxy' directory (or any other name used) should not exist on the webserver: it's a virtual path.

For example using /etc/apache2/sites-enabled/usp-evaluation.conf:

<Directory "/var/www/usp-evaluation/proxy">
  IsmProxyPass http://other-server/
</Directory>

So the '/var/www/usp-evaluation' directory exists but the '/var/www/usp-evaluation/proxy' directory does not and maps to http://other-server.

This applies to all examples on this page.

When query parameters are part of the url that is proxied, the query parameters are passed on to the upstream server.

Playback content from other domains

Time for a more elaborate example. Let's say the content (an MP4 video) is hosted at: http://content.bitsontherun.com/videos/3XnJSIm4-kNspJqnJ.mp4 and we want to make this available in the HTTP Smooth Streaming format.

The first step is to set up the IsmProxyPass since we want to create a server manifest file dynamically for any given audio/video URLs.

<Directory "/var/www/usp/ism">
  IsmProxyPass http://demo.unified-streaming.com/smil.php/
</Directory>

The webserver module now requests the server manifest file using the given smil.php script for any URL that starts with http://demo.unified-streaming.com/ism.

Say you are requesting the Smooth Streaming client manifest file for the MP4 video. The URL in this case is:

http://demo.unified-streaming.com/ism/CACHE_ID.ism/Manifest?url=http%3A%2F%2Fcontent.bitsontherun.com%2Fvideos%2F3XnJSIm4-kNspJqnJ.mp4

The internal URL that the webserver uses to fetch the server manifest file becomes:

http://demo.unified-streaming.com/smil.php/CACHE_ID.ism?url=http%3A%2F%2Fcontent.bitsontherun.com%2Fvideos%2F3XnJSIm4-kNspJqnJ.mp4

The following PHP script generates a smil file with the audio/video tracks pointing to the original content:

<?php
error_reporting(0);
$url = $_GET["url"];
Header('Content-Type: text/xml');
echo "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
?>
<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
  <head>
  </head>
  <body>
    <switch>
      <audio src="<?=htmlspecialchars($url, ENT_QUOTES, 'UTF-8')?>" systemBitrate="1"/>
      <video src="<?=htmlspecialchars($url, ENT_QUOTES, 'UTF-8')?>" systemBitrate="1"/>
    </switch>
  </body>
</smil>

Please note that the string 'CACHE_ID' in the above example is just a place holder, it can be anything (or even removed) and may be used for internal tracking (session id etc).

Re-stream content from any domain

A generic setup to re-stream any content from any domain.

This allows you to make any content available in all the playout formats, without any requirements on the webserver running on the proxied domain (i.e. it can be a plain webserver, without support for HDS, HSS or HLS playout capabilities).

The first step is to set up the IsmProxyPass to proxy any content that USP can ingest, e.g. MP4 (.mp4/.smil), HDS (.f4m) or HSS/MPEG-DASH (.ism).

<Directory "/var/www/usp/direct">
  IsmProxyPass http://
</Directory>

Say you are requesting the Smooth Streaming client manifest file for the MP4 video. The URL in this case is:

http://demo.unified-streaming.com/direct/content.bitsontherun.com/videos/3XnJSIm4-kNspJqnJ.mp4/Manifest

The webserver running at http://content.bitsontherun.com is a plain webserver and the USP origin running at http://demo.unified-streaming.com uses the URL http://content.bitsontherun.com/videos/3XnJSIm4-kNspJqnJ.mp4 to create the manifest file.

Since USP ingests .mp4, .ism, .smil and .f4m you can ingest all these different formats from any webserver without having to run any additional media server side components on the proxied servers.

Another example would for instance be using content from S3:

http://demo.unified-streaming.com/direct/s3-eu-west-1.amazonaws.com/usp-proxy/oceans.mp4/manifest

for Smooth, or

http://demo.unified-streaming.com/direct/s3-eu-west-1.amazonaws.com/usp-proxy/oceans.mp4/.m3u8

for HLS - other formats can be reached similarly. See Player URLs for the supported urls.

Follow this link for a working proxy example where you can use your own audio/video URLs - and where the USP instance could be EC2 as well.