Getting Started with Live

The goal of this tutorial is to introduce you to working with Unified Origin Live, and to familiarize you with the workflow for setting up a livestream.

This tutorial requires you to have access to an Live encoder. If you don't have access to an encoder or if you are more interested in getting a demo up-and-running as quickly as possible, please make use of our Docker Express Live streaming demo instead.

Before you start 

Before starting please make sure that:

Origin is properly installed (How to Install)
Your encoder is compatible with Origin (Supported Encoders)

Setting up a publishing point 

With the command-lines below you will first create a Live server manifest channel1.isml that has a sensible default configuration (see below for some background), then create a directory to move this Live server manifest to, and finally make sure that Apache is the owner of the directory and channel1.isml inside it (i.e., is the owner of the publishing point).

#/bin/bash

mp4split -o channel1.isml \
  --archiving=true \
  --archive_length=1200 \
  --archive_segment_length=300 \
  --dvr_window_length=600 \
  --restart_on_encoder_reconnect \
  --hls.client_manifest_version=4 \
  --hls.no_multiplex \
  --fixed_gop=48/25

sudo mkdir -p /var/www/channel1
sudo mv channel1.isml /var/www/channel1/
sudo chown -R www-data:www-data /var/www/channel1/

Note

The file extension for a Live server manifest (.isml) differs from that of a VOD server manifest (.ism) and the name of the publishing point's directory should be the same as the name of the Live server manifest inside it (in this case, both are called channel1).

A sensible default configuration 

The configuration used above stores an archive of 20 minutes on disk (--archive_length), in 5 minutes segments (--archive_segment_length). And when a request for playout of the stream is made, the most recent 10 minutes of content are included in the dynamically generated client manifest (--dvr_window_length).

These values are kept relatively short because this tutorial is intended for demonstration purposes. They can be adjusted to your needs without problem, but do note that we recommended not to increase the archive beyond several days or configure a DVR windows length of more than several hours (also, the DVR window must be smaller than the archive).

Other than that, keep in mind the following:

The --archiving option is a legacy switch and should always be set to true, as the configuration of a publishing point's archiving behavior is much better specified using the more specific options detailed next
Each of the --archive_length, --archive_segment_length and --dvr_window_length should always be configured (all in seconds), although different values may be chosen
Using the --restart_on_encoder_reconnect is highly recommended because it allows an encoder to reconnect and continue pushing a stream after the stream was (accidentally) switched to a 'stopped' state
The default value for --hls.client_manifest_version is '1' and setting it to a value of '4' or higher is recommended because it ensures that your HLS TS stream will support relatively basic functionality like the use of multiple audio tracks and subtitles, amongst others (relevant for HLS TS only)
To ensure that Origin does not mux the default audio with each video track, and to ensure it outputs audio as elementary streams, --hls.no_multiplex should be enabled (relevant for HLS TS only)
You should configure your encoder to output video with a fixed GOP, which is something that all modern encoders support. Ideally, your chosen GOP length fits an exact multiple of audio frames (each AAC frame is 1024 audio samples long). Using the --fixed_gop option allows you to inform Origin about the GOP length that you have configured your encoder to output (the default value is '2'). Origin will use this information to set the 'TARGET-DURATION' of its HLS output to twice this value and generate its HLS segments accordingly, amongst others. When using --[iss|hls|hds|mpd].minimum_fragment_length the --fixed_gop value will be overruled

Checking your publishing point's configuration 

You can easily check the configuration of the publishing point by reading the content of the Live server manifest you have just created by using a tool like cat:

#/bin/bash

cat /var/www/channel1/channel1.isml

This should print the following configuration if you did not alter the command-line to create the Live server manifest (note that the <body> is still empty because no stream has been ingested yet, and thus no information about tracks has been stored):

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Unified Streaming Platform (version=1.10.12-18737) -->
<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
  <head>
    <meta name="clientManifestRelativePath" content="channel1.ismc" />
    <meta name="creator" content="Unified Streaming Platform (USP)" />
    <meta name="lookahead_fragments" content="2" />
    <meta name="dvr_window_length" content="600" />
    <meta name="archive_segment_length" content="600" />
    <meta name="archiving" content="true" />
    <meta name="archive_length" content="1200" />
    <meta name="restart_on_encoder_reconnect" content="true" />
    <meta name="fixed_gop" content="48/25" />
    <meta name="hls_client_manifest_version" content="4" />
  </head>
  <body>
    <switch>
    </switch>
  </body>
</smil>

Checking your publishing point's 'state'

Before you can start pushing a stream to your publishing point, you should check its 'state' to determine whether it is properly set up and 'idle' like it should be. Checking the state can be done with a simple API call that appends /state to the publishing point's URL. In the example below we use curl to make this call from the server running Origin itself, so that we can address it through localhost:

#/bin/bash

curl -v http://localhost/channel1/channel1.isml/state

This should result in the following, where state should have a value of idle, telling us that the publishing point can be addressed through Origin (otherwise the API call wouldn't return anything) and that it has not ingested a stream yet and is ready to do so.

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Unified Streaming Platform (version=1.10.12-18737) -->
<smil
  xmlns="http://www.w3.org/2001/SMIL20/Language">
  <head>
    <meta
      name="updated"
      content="2019-11-11T11:58:12.430191Z">
    </meta>
    <meta
      name="state"
      content="idle">
    </meta>
  </head>
</smil>

Note

More info on the different types of 'state' that a publishing point can be in: Retrieving additional publishing point information.

Starting your livestream 

Now that you have created a publishing point, and checked its configuration and its state Origin is ready to start your livestream. But before you start your encoder, you need to make sure that it is properly configured first.

In short, it should use UTC timing and closed GOPs of a fixed length (a length that ideally fits an exact multiple of AAC audio frames as already explained above, like 1.92 seconds for 25 FPS video with 48KHz audio). For more detailed information, please read: Content Preparation.

The URL that your encoder needs to push the stream to is that of your publishing point:

http://<hostname>/channel1/channel1.isml

Now that everything is properly configured, you can start your encoder.

When your encoder has started pushing a livestream to Origin, Origin changes the state of the publishing point and updates the Live server manifest with information about the ingested tracks. It will also store the ingested media data as .ismv files inside the publishing point and create a .db3 SQLite database there as well, which contains timing related information about the ingested media:

channel1/
  channel1.db3
  channel1.isml
  stream1.ismv

Note

When you want to reset the publishing point the encoder needs to be stopped first, because otherwise the webserver will keep a lock on the .db3 file.

Determining if your livestream works as expected 

You should now have a working livestream. To determine whether this is actually the case you can check if your livestream is set up successfully by doing the following:

Check if your publishing point's state is 'started'

Like after creating your publishing point you should also check its state after you have started pushing a livestream to it:

#!/bin/bash

curl -v http://localhost/live/channel1/channel1.isml/state

Instead of 'idle', it should now be 'started':

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Unified Streaming Platform (version=1.10.12-18737) -->
<smil
  xmlns="http://www.w3.org/2001/SMIL20/Language">
  <head>
    <meta
      name="updated"
      content="2019-11-11T11:59:32.374312Z">
    </meta>
    <meta
      name="state"
      content="started">
    </meta>
  </head>
</smil>

If the state has remained 'idle', check the access and error logs of Origin's virtual host as well as the logs of your encoder to determine what went wrong (by default, Apache's logs can be found in /var/log/httpd/ or /var/log/apache2/, depending on the exact Linux distribution that you're running).

Note

If for some reason the state of your publishing point is 'starting' or 'stopping', you can make a request to /statistics to check the state of each individual track to determine the culprit.

Inspect your publishing point's archive 

After checking your publishing point's state, you can check its archive to see if all tracks have been properly ingested and if there are any discontinuities in the stream.

#!/bin/bash

curl -v http://localhost/live/channel1/channel1.isml/archive

If everything is as it should be you should see an overview of all tracks that are part of your livestream. Each track should have one start and one end time. The latter is updated every time a new segment from the encoder is ingested, while the first is only updated once the archive is completely filled and content is purged from it to make sure it does not exceed the configured length.

Discontinuities

If one or more tracks in your archive have multiple entries with start and end times, your stream contains discontinuities (i.e., gaps). If there are no clear reasons for such gaps (like a temporary network failure) this indicates a problem at the encoder. Dedicated timed metadata tracks are the exception to this rule, as they receive only intermittent updates and contain gaps by definition.

To purposely create a discontinuity for testing purposes you can stop and restart your encoder. Stopping it should send a 'End of Stream' (EOS) signal on all tracks, which makes the state of your publishing point switch to 'stopped'. After stopping the encoder, wait a few seconds before you start it again. As the publishing point is configured with --restart-on-encoder-reconnect Origin it will now resume ingest of the stream even though its state was 'stopped', with a discontinuity for the time no ingest was taking place.

Note

Resuming ingest only works if the timestamps of the segments pushed by the encoder after its restart, are higher than those that came before. When your encoder uses UTC timing with timestamps that represent 'now' in 'wall clock' time this requirement is fulfilled automatically.

Request a client manifest for your livestream 

You still haven't seen one bit of video, but we're getting closer. The last thing to check before testing playback is Origin's response to a request for a client manifest.

Request a DASH client manifest (MPD):

#!/bin/bash

curl -v http://localhost/channel1/channel1.isml/.mpd

Request a HLS client manifest (Master Playlist):

#!/bin/bash

curl -v http://localhost/channel1/channel1.isml/.m3u8

The DASH MPD contains all your stream's information in one place, while the HLS Master Playlist is merely an index to Media Playlists that each contain a timeline for one of your livestream's tracks.

Test playback of your livestream 

To test playback, simply feed a compatible player the URL to the client manifest for the playout format that you want to test. If you're accessing the player though a browser on the server that is running Origin, using localhost as the domain name should work. In case you want to test playback on other devices it's best to configure your setup so that you can access the server through a fully qualified domain name (FQDN).

Unified Streaming hosts a web page that is specifically intended for testing streams with a variety of players:

https://unifiedstreaming.github.io/mse-toolbox/uapi/bin/

When testing playback it's a good idea to keep an eye on your browser's network tab and console log to check what is actually happening and troubleshoot potential issues.

Trying out more of Origin Live's features 

Now you should have a livestream running, it is time to look into some of Origin Live's additional functionality. To get you started, we'll walk you through the option to create virtual sub-clips below.

Create virtual sub-clips 

Another feature that adds a lot of flexibility to Origin is the capacity to dynamically generate 'virtual' sub-clips from your stream. This functionality relies on a query parameter that you use to specify the begin and end time of the clip you want Origin to generate.

Assuming your encoder is still pushing your livestream to Origin, you can request a 5 minute virtual sub-clip like so:

#!/bin/bash

start=$(date -d "15 minutes ago" +%Y-%m-%dT%H:%M:%S)
end=$(date -d "10 minutes ago" +%Y-%m-%dT%H:%M:%S)

curl -v http://localhost/channel1/channel1.isml/.mpd?t=${start}-${end}

The begin time you specify must be in the past, but the end can either be in the past or the future. It's possible to only specify a begin time as well. This allows you to configure Restart and Catch-up TV options.

Next Steps 

Having worked through this tutorial you are familiar with the basics of Origin Live now. To learn even more you can take a dive into our doucmentation for more information for Live streaming options, the Live REST API, SCTE 35-based ad insertion and how to create a redundant setup:

Or have a look at the complete overview of documentation for Unified Origin - LIVE.