FAQ

General

Is there a Graphical User Interface (GUI)?

No, our expectation is that customers already have a scheduling system that will produce playlists and handles library management, rights etc

Do I need to create my own schedules?

Yes.

Can you support my existing playlist format?

We support SMIL, and expect that any existing playlist format will not contain the right information for us to work with, e.g. they usually reference media IDs and we need full URLs. So some integration work by customers is likely necessary.

I'm already using Remix VOD2Live; how do I get access to the other use cases?

You can use the new Unified Virtual Channel solution alongside any existing Remix use cases, but as it is a complete system it will run separately

What do you mean by 24/7 linear channel?

This is a channel that continues playing without any interruption like a traditional TV channel

Which formats are supported?

All features are supported for HLS (transport stream and fragmented mp4/CMAF) and DASH outputs.

For SmoothStreaming it is only possible to use the API to manage a simple VOD2Live channel. Transitions between playlists are not possible with SmoothStreaming.

If we don't integrate using the new API do we miss out on this new functionality?

Yes. Unless you would like to build out the new functionality yourself with the component product.

Will it be possible to do things like blackouts?

Yes, you can schedule a transition to a “blackout” playlist at the required time.

How is it licensed?

Virtual Channel is licensed based on channel count and functionality. There is a base price per channel, and add-ons to enable DRM, Timed Metadata (such as SCTE 35 for ad insertion), and stitching of Live sources.

The channel count is based on the number of output channels, i.e. a single channel that transitions to a new playlist regularly still only uses a single channel license. Multiple output formats that use the same publishing point / server manifest are also included in a single channel count, i.e. serving DASH (/.mpd), HLS transport stream (/.m3u8), and HLS fMP4 (/.m3u8?hls_fmp4), or using dynamic track selection filters are all included.

Deployment

How does it scale?

Scaling of Virtual Channel is similar to scaling of live channels for Unified Origin, so it depends on the total bitrate, number of outputs and output segment length.

For reference, we ran some tests using Apple's recommended HLS ladder which totals 82Mbit across all renditions, with a 3.2 second segment length and 3 output formats (HLS transport stream, HLS fMP4, DASH), i.e. total output ~250Mbit.

We tested on an EC2 C6g instance (specifically c6g.medium) and it ran comfortably at around 30% CPU usage. The baseline network throughput of this instance is 0.5Gbit so it can only safely run a single channel of this size.

How can I monitor the system?

All containers write log information to their STDOUT and STDERR which can be monitored with the standard Docker tools, or shipped to an external system if you configure the Docker log driver.

Resource usage metrics can be gathered using any standard tools.

How can I use a different base path for requests?

By default Virtual Channel expects requests on the root path /, for example, GET /channel_name.isml/.mpd.

If using a different path makes more sense for your environment, for example, if you have a load balancer redirecting all traffic for /fast/ to your Virtual Channel system, then you can change the base path by adjusting the Traefik configuration for the manifest-proxy and origin containers in your Docker Compose yaml file.

For example, to use /fast/ as the base path instead of /:

origin:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.origin.entrypoints=web"
    - "traefik.http.routers.origin.rule=PathPrefix(`/fast/`)"
    - "traefik.http.routers.origin.middlewares=strip"
    - "traefik.http.middlewares.strip.stripprefix.prefixes=/fast"

manifest-proxy:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.manifest-proxy.rule=Path(`/fast/{manifest:.*\\.ism[l]?/.*\\.(mpd|m3u8)}`)"
    - "traefik.http.routers.manifest-proxy.entrypoints=web"
    - "traefik.http.routers.manifest-proxy.middlewares=strip"

This configuration changes the traffic routing to direct requests with the prefix /fast/ to the right containers, and adds a middleware to strip the prefix.

How can I deploy it in a redundant / high availability setup?

The most straightforward way to run a high availability setup is to simply run two independent copies of Virtual Channel and make sure to send the exact same playlists and transitions to both systems. As long as the inputs are the same Virtual Channel will always produce an identical output with the same media timeline and segmentation, so it can easily be used in an active/active or active/passive cluster.

It is important to note that the state of the system depends on its history, so in order to create a redundant copy of an existing system it is necessary to back up the existing system and then restore it to the new instance.

How can I back up the system?

There are two components that need to be backed up: the /channels directory and the Redis database.

The /channels directory can simply be copied.

The Redis database can be backed up in 3 steps:

# Start save process:
docker compose exec -it redis redis-cli bgsave

# ​Then check for the dump.rdb file being written in /data:
docker compose exec -it redis ls -alF /data

# Once it is there, copy it out of the container:
docker compose cp redis:/data/dump.rdb .

How can I restore the system?

Warning

Restoring a backup will overwrite any existing state on the system as it overwrites the database.

Before starting the Virtual Channel system follow the steps below. If you want to restore to an already running system you must stop the running containers first.

# Stop the running containers
docker compose stop

Copy the contents of the /channels directory from the backup into the new instances.

Restoring the Redis database requires switching off appendonly mode, otherwise Redis will ignore the rdb file. This can be done by changing --appendonly yes` to --appendonly no in the redis section of the docker-compose.yaml file.

redis:
  image: redis:7.0.4
  restart: always
  entrypoint: redis-server --appendonly no
  logging: *default-logging
  volumes:
    - redis_data:/data

Once that is done you can copy the dump file into the container's storage volume:

# Copy dump.rdb from the local directory into the Redis data volume
docker compose run --rm --volume $PWD:/backup --entrypoint /bin/bash redis -c 'cp /backup/dump.rdb /data/dump.rdb'

And then start the system as usual:

# Start Virtual Channel
docker compose up -d

Once the system is running you can tell it to start writing a new appendonly file:

# create new appendonly file
docker compose exec redis redis-cli BGREWRITEAOF

Then change the docker-compose.yaml configuration back to appendonly mode:

redis:
  image: redis:7.0.4
  restart: always
  entrypoint: redis-server --appendonly yes
  logging: *default-logging
  volumes:
    - redis_data:/data

Content

Does all my content need to match encoding exactly?

No, although it does need to be broadly similar in order to meet the requirements of DASH and HLS. Virtual Channel uses Unified Remix to process VOD playlists, which has a set of heuristics to find the "best fit" matches of tracks across the scheduled source media.

Best practice is to configure a desired target encoding profile and have Virtual Channel match that as closely as possible when processing VOD. As live sources are not processed in the same way there is no fuzzy matching possible. This means that if you are using live sources you should use that exact encoding profile as the target for your VOD playlists, which can easily be done by Capturing a short clip from the live stream and using that as the target.

Is it possible to add a channel logo/bug or other dynamic graphics?

As Virtual Channel does not do any transcoding it cannot add graphics that are not already in the source media.

However, there are alternative approaches to solving this that we would be happy to discuss in further detail, for example, using timed metadata in the stream to trigger client side overlays.

Channel/transition creation

How do I use a mix of VOD and live sources in my playlist?

You can't mix VOD and Live in a single playlist, but you can trigger transitions to a different source through the API. i.e. VOD2Live playlist -> transition to Live source -> transition to VOD2Live playlist.

Can I make changes to an already running playlist?

Changes can be made by sending a new playlist along with a time that the system should switch from old to new versions. This is what we call a transition.

How do I transition from one playlist to another at a set time (e.g. after 6/12/24 hours)?

Send the new playlist along with the transition time to the API, using the PUT /channels/{channel}/transitions/{transition} endpoint, where {transition} is set to the time (UTC, ISO8601) you want the transition to happen (e.g. 2021-03-22T21:00:00Z).

How do I transition my channel to a VOD2LIVE or LIVE clip of a certain duration?

A single transition has no concept of "duration". You can achieve a desired content duration only as a difference between two consecutive transitions.

An example may help clarify the concept. Let's say you have created a channel continuously playing a certain playlist A. You now want to transition, at time T1, to playlist B for 30 minutes and then "get back" to playlist A.

You can achieve what you want by creating two transitions:

• a first transition to playlist B at time T1

• a second transition to playlist A at time T2 = T1 + 30min

How do I set start time, DRM and other options for VOD2Live playlists?

The configuration parameter vod2live_start_time is used to set the start time and is a mandatory parameter in the SMIL Head. Other configuration parameters that you would normally pass to mp4split at server manifest creation time can be passed as well to Virtual Channel in the head of the SMIL playlist.

How do I know when my channel is ready?

When you submit your SMIL for channel creation, a status URL will be returned which can be queried to view the job processing status at any time. Once the process has reached the Success status, it is available for viewers.

How long will it take, from the moment I perform a PUT operation, for my channel/transition to be available for playout?

The creation of a live channel/transition involves two basic steps:

• running Unified Remix to process the SMIL playlist and create a remixed mp4

• running mp4split to create an .isml server manifest based on the remixed mp4.

This process can take a variable amount of time, depending mainly from two factors:

• complexity of the playlist (playlist length, number of entries, media complexity all contribute to Unified Remix processing time)

• I/O speed. For a typical case when media are on a cloud storage, the network throughput to the remote storage is a key factor.

This means you can expect from a few seconds (for very simple playlists) to a few minutes (for long playlists, with many elements) of delay in the availability of your channel/transition, from the moment you perform a PUT operation to create it.

Remember that by default, after creating the remixed mp4 and the corresponding isml for a transition, Virtual Channel checks if the transition time hasn't yet

If the channel/transition creation job needs a variable amount of time, how can I proceed to be guaranteed that my channel/transition will be available for playout at a certain date/time?

The correct procedure is to create your channel/transition well ahead of time, but scheduling playout at a specific point in time. The recommended steps are the following:

• When creating channels, set the vod2live_start_time option to the point in time when you need your channel to be available for playout (do not forget to express it as an UTC time!).

• When creating transitions, set the transition time to the point in time when you need your transition to become active (do not forget to express it as an UTC time!).

• Perform your PUT operation well ahead of time to make sure Virtual Channel has the time to perform the channel/transition creation operation.

If the channel has been set up and a request is made to Origin before the specified start time, the client receives a 404 and a log message (i.e. FMP4_404 VOD2Live starts at 2021-03-22T21:00:00Z) is written to the Apache error log.

When the specified start time is reached, the Origin will just start serving requests.

What happens if I specify a transition time in the past or a few seconds in the future?

A transition time in the past will just fail. For the one a few seconds in the future, the outcome will depend on the duration of the transition creation job. In fact, transition time is checked in several points:

• at PUT time, transition time must not be in the past

• at PUT time, transition time must not be earlier than vod2live start time

• at transition job completion time, transition time must not be in the past

In our example, let's imagine that, at time T1, a job for a transition at time T1+Delta_T is submitted successfully.

If the transition creation job takes a time Tj to complete, the transition will be successful only if T1+Tj<Delta_T.

Remember that by using the force query parameter, you can disable all these checks if you know what you're doing.

So, what if I really need to schedule a complex transition a few seconds in the future? Is there a way to make it work?

If you have no alternatives the following technique allows you to pre-compute a transition and reuse it later so that its job completion time, when you will need it, is almost instantaneous.

This technique assumes that:

• you do know in advance the SMIL playlist you need to transition to

• you don't know in advance the exact time you want the transition to happen at but you can estimate that you will need it before an estimated time T in the future (e.g. no later than midnight; within the next two days)

This is the suggested workflow:

1. prepare the SMIL you need to transition to.

2. schedule a transition to the SMIL at the estimated no-later-than time T

3. wait for the transition to be successful

4. once you know the exact time for the desired transition, schedule it even if it is a few seconds in the future

5. wait for the transition to be successful

6. delete the first transition you had scheduled for time T

This technique works because the time-consuming steps (needed to compute the remixed mp4 and the isml server manifest) will be performed at step 2, that is well ahead of time. When, at step 4, you will schedule the real transition you need, submitting an identical SMIL, Virtual Channel will completely reuse the previously computed remixed mp4 and isml server manifest files, thus drastically reducing the transition job duration. In fact, in this case the job will be almost instantaneous. The last step is eventually to remove the transition for time T which you don't need to actually happen.

What should I pay attention to when providing a start time (vod2live_start_time option) for my channel?

• convert your date/time from local time to UTC

• format your time string in one of the two supported ISO8601 formats (with or without decimal digits for seconds): - 2021-03-22T21:00:00Z - 2021-03-22T21:00:00.000000Z

What should I pay attention to when providing a transition time for the transition endpoint URLs?

The recommendations are identical to the ones for the vod2live_start_time option, that is:

• convert your date/time from local time to UTC

• format your time string in one of the two supported ISO8601 formats (with or without decimal digits for seconds): - 2021-03-22T21:00:00Z - 2021-03-22T21:00:00.000000Z

• make sure your transition time is in the future, ideally at least a few minutes

What if I make a mistake in my SMIL when creating a channel/transition?

Just wait for your job status to reach the Success or Failed state and then repeat the PUT operation with a modified SMIL.

If the channel/transition is already active instead, you should DELETE your channel/transition and create a new one.

Why do I see UUIDs in my media segments path?

If you take a look at media segments URIs in DASH/HLS, you may notice that they involve a UUID, as in

initialization="9cc198d6-f951-54e0-bb9f-cc63f5913434-$RepresentationID$.dash"
media="9cc198d6-f951-54e0-bb9f-cc63f5913434-$RepresentationID$-$Time$.dash">

for DASH or

#EXTINF:1.92, no desc
../9cc198d6-f951-54e0-bb9f-cc63f5913434.isml/9cc198d6-f951-54e0-bb9f-cc63f5913434-audio_eng=128000-video=400000-11098588.ts

This UUID is computed from a full-body hash of the SMIL playlist provided at channel/transition creation time. Virtual Channel keeps an internal SMIL->UUID mapping so that it can reuse previously created isml server manifests anytime the same SMIL playlist is used for channel/transition creation.

The UUID is computed consistently based on the SMIL content hash. This means you can be guaranteed that different instances of Virtual Channel will always generate the same UUID for the same SMIL. This is a detail that can be important for cache efficiency or High Availability considerations.

Channel deletion/modification

When can I modify an existing channel/transition?

Updates are allowed specifically if all the following conditions are satisfied:

• the channel/transition creation job has terminated, either successfully or with a failure (i.e. the status is either Failed or Success).

• in case of Success, the scheduled channel/transition start time hasn't been reached yet. This check can be overridden by specifying a force query parameter. Use with extreme caution.

When can I delete a channel/transition?

Deletes are allowed specifically if all the following conditions are satisfied:

• the channel/transition creation job has terminated, either successfully or with a failure (i.e. the status is either Failed or Success).

Notice that no checks are performed: if the channel is live and you delete it, you will break playout.

If you delete a transition, any device currently playing its content will hang but the channel will keep working, using the content from previous transitions.

This is better clarified by a couple of example scenarios:

|---------------------|-------------|---------->
ch1                  tr1           tr2
                                              ^
Viewer 1:                               <-----|>
                                       ^
Viewer 2:                        <-----|>
                            ^
Viewer 3:             <-----|>

The above is a sketch of a channel with two transitions, with viewers reproducing it at different points in time. In angular brackets, their DVR window is represented. Viewer 1 is on the Live edge, while Viewer 2 and 3 are using the "restart/catch-up" functionality.

Example 1: Transition 2 is deleted From the deletion moment on, Viewer 1 and 2 will be affected and their players will hang. Viewer3 will not be affected at all. Any other viewer joining the stream at this point will experience a channel only having tr1:

 |---------------------|------------------------>
ch1                   tr1

Example 2: Transition 1 is deleted From the deletion moment on, Viewer 2 and 3 will be affected. Viewer 3's player will hang. Viewer's 2 player may hang, depending on how much it still relies on content belonging to transition 1's playlist. Viewer 1 will not be affected at all. Any other viewer joining the stream at this point will experience a channel only having tr2:

|-----------------------------------|---------->
ch1                                tr2

What happens when I delete a channel?

When you DELETE a channel, Virtual Channel's Origin service immediately stops serving the content. All transitions belonging to the channel are deleted and all the details about the channel (job statuses, logs and status details) are deleted as well.

If the channel's SMIL is not used by any other channel or transition, then the corresponding server manifest and remixed mp4 are deleted as well.

If you need to keep an history of deleted channels, you should save all the details you need before deleting it from Virtual Channels.

What happens when I delete a transition?

When you DELETE a transition, Virtual Channel's Origin service immediately removes it from the channel it belongs to. All the details about the transition (job statuses, logs and status details) are deleted as well.

If the transition's SMIL is not used by any other channel or transition, then the corresponding server manifest and remixed mp4 are deleted as well.

If you need to keep an history of deleted transitions, you should save all the details you need before deleting it from Virtual Channels.

How should I update an existing channel/transition?

Just perform a PUT operation on the same channel/transition endpoint, with a different SMIL payload.

Remember that changes are not permitted on channels/transitions whose vod2live_start_time or transition time are in the past, unless you specify the force query parameter (which is highly discouraged since it will break running streams).

Can I update a channel if it is live already?

No, Virtual Channels will prevent you from doing so. If you have made a mistake and you want to completely obliterate the existing channel, you can perform a DELETE and a subsequent PUT to recreate the channel. Notice though that this will inevitably break playout.

If you just want to switch the existing channel to new content, you should perform a transition. Notice though that viewers will still be able to access the channel content _previous_ to the transition by using the "restart/catch-up" functionality or just scrubbing back.

If you positively want to update a channel which is live already and break running streams, then you can force the operation by specifying the force query parameter.

Can I update a channel/transition if that is not yet active?

Yes, if the specified start time has not yet been reached, you can modify the channel/transition (e.g. provide a new SMIL playlist) by just performing another PUT operation. The existing channel/transition will be completely overwritten.

Manifest Edit

How do I know if Manifest Edit can perform the edits I need?

You should read the Plugins Library chapter. Look for a plugin that may cover your need and then read the details of how to configure it and if it can perform the specific edit you need.

If your use case is not yet covered, let us know by writing at support@unified-streaming.com. We are always looking for feedback and new use cases to implement to enlarge the Plugins Library.

How do I know if my yaml pipeline configuration file is correct?

When you PUT to any of the pipeline creation endpoints, either for the base channel or for a variant, the API performs all possible checks on the pipeline configuration files. If a 200 OK status is returned, your pipeline is correct and will work when the playout URI is accessed.

How can I be certain that my manifest has gone through Manifest Edit?

Each manifest that has gone through Manifest Edit has an additional comments section in its header, where the whole pipeline configuration file content is reported, i.e.

<!-- Original: Created with Unified Streaming Platform (version=1.11.22-28062) Edited by Manifest Proxy
Edited by Unified manifest-edit, using the following pipeline:
mpd:
- manifest_edit.plugins.mpd.descriptor_add:
    # This plugin will add an UTCTiming tag to manifests that do not already
    # have one. You can choose the scheme by selecting one of the following:
    # one or more of the following:
    #  http-iso
    #  http-xsdate
    #  http-ntp
    #  ntp
    #  http-head
    #  direct
    # Additionally, you must provide the value that will be used, in the
    # format required by the scheme you have selected.
    plugin_config:
      name: "UTCTiming"
      schemeIdUri: "urn:mpeg:dash:utc:ntp:2014"
      value: 'https://time.akamai.com/?ntp'

-->

If that section is present, your manifest has gone through the mentioned pipeline, otherwise it has not.

Manifest Edit seems to not change my manifest at all. What should I check ?

The recommended checklist is:

• make sure the pipeline PUT operation returns 200 OK

• make sure you are getting the manifest from the correct URI (base channel URI or URI with ?python_pipeline_config={variant} query parameter if you have used the variant PUT endpoint)

• make sure your manifest has gone through the pipeline by checking the presence of a comment header mentioning Edited by Unified manifest-edit

• if the above is true, also check that the pipeline reported in the header is the one you are expecting

• check that there are no typos/mistakes in the plugin configuration sections of your pipeline. Most plugins perform a first selection of specific elements to edit by matching an element (track, adaptation set, ...) by some of its property (i.e. language = "en"). If there are typos in the regex or the manifest just does not contain the expected element, the pipeline will have no effect on the manifest.

Should I use the base channel or the variant endpoint?

In general, variants are recommended. They do not impose any overhead and the URI query parameter univocally identifies the active Manifest Edit use case. Separating URIs for the original and edited manifest gives you also the chance to route requests to the most appropriate endpoint based on the needs of the downstream entity that will process the manifest.

The base channel endpoint is a good choice if you don't want or can't have query parameters in your playout URI. In this case your only choice is to use the base channel endpoint. Take notice that you will lose access to the origin, non-edited manifest and you will only be able to activate one single Manifest Edit use case for the channel at a time.