Basic Concepts

Media Files and Streams

If you are already familiar with the structure of media files, skip ahead to the Masters and Mezzanines section.

Ingesting on-demand (as opposed to live) content begins with 1 or more Media Files.

A Media File contains 1 or more Streams. A Stream is one 'track' of media (audio, video, subtitles, or other data).

Most Media Files contain at most 1 video stream but may have more than 1 audio stream:

In the simplest case, an ingest starts with a single Media File that has 1 stereo audio stream and 1 video stream. In these cases there is no manual input needed to choose which file to use or which stream(s) to include.

Often, however, things are more complex - there may be multiple files that make up a title, or multiple streams to choose from. More on this in the Variants section.

Audio Streams are further subdivided into Channels. A channel is generally the audio to be sent to a single speaker:

In summary, a Media File contains 1 or more Streams. An audio Stream contains 1 or more Channels.

Masters and Mezzanines

In the Eluvio Content Fabric, ingesting media for streaming involves two kinds of objects, Masters and Mezzanines.

A Master organizes your original source files . A Mezzanine holds a version of your content optimized for low latency streaming, and is generated from your Master file(s) based on a stream list that is configured in the master:

Master

Mezzanine

Usually only accessible to content owners / admins

Accessible to (specified) users or the public

Not directly viewable from Content Fabric (yet)

Directly viewable from the Content Fabric, and optimized for low latency streaming

Often very high bitrate/resolution

Usually lower bitrate and/or resolution than Master

Often encoded with professional codecs (Prores / JPEG2000 / PCM-raw Audio etc.)

Encoded with h264 or h265 video and AAC audio

Media optionally stored outside of Content Fabric in S3

(Transcoded) media is stored in the Content Fabric

Offerings and ABR Profiles

The viewable / streamable item in the Mezzanine is called an Offering. It makes your media playable in various resolutions / bit rates and playout formats. These playout options are set using an ABR Profile. It is possible for a mezzanine to contain multiple Offerings ingested with different settings, for example to create a "premium" Offering with higher quality playback:

The name given to the Offering is called the offering key. This becomes part of the URL used for playout. Playout access control can be configured on a per-offering basis.

If no offering key is specified during ingest then "default" will be used.

Every ingest must use an ABR Profile. It configures the following:

  • Top resolution / bitrate
  • Additional (lower) resolutions / bitrates to make available
  • Playout protocol(s)
  • DRM type(s)
  • Watermarking

See Reference: elv-utils-js /example-files ▸ ABR Profiles for a list of ABR Profiles supplied with the elv-utils-js command line utilities.

After ingest, an Offering can be edited to change all of the above settings except "Top resolution / bitrate" and "Storage encryption". A change to either of those two settings requires re-transcoding and recreating the Offering.

Variants

The list in the Master that controls what streams to include and from which files is called a Variant.

It is possible for a Master to define multiple Variants, e.g. for internationalization:

The name given to the Variant is called the variant key. It is an internal reference, independent of the offering key. (If no variant key is specified, "default" will be used)

Each Offering makes one Variant playable in the formats specified by an ABR Profile. A Variant may have more than one Offering created from it.

Objects and Versions

The basic unit of organization in the Content Fabric is called an Object. It is a container for holding information such as files and metadata.

Every Object has a unique Object ID starting with iq__, e.g. iq__4JhZtSENmDu7hTq91LEufzDnDpj3.

Each time you save changes to an Object the Content Fabric will create a new Version of it. Every Version has a Version Hash starting with hq__ which identifies it and also acts as a signature to ensure that its contents have not been tampered with. (The Object ID remains the same when you edit an Object.)

Past Versions of an Object are kept, and you can view them in the Fabric Browser by clicking the Show Previous Versions button.

Master Version Hashes

When generating an Offering, you must specify what Version of the Master you wish to base it on. (Usually you will want to use the latest Version of the Master). This is done by specifying the Master Version Hash that you want to base your Offering on.

Version Hashes begin with hq__.

Updating the Master does not update any Offerings which have already been created, and they will continue to be based on the older Version of the Master.

This is fine if you haven't made any changes that need to be copied to the old Offering. In the example below, the Master was edited to add a French audio source file and create a Variant called "french". This is not a change that would affect the previously generated Offerings ("default-en" and "premium-en"), so they do not need to be regenerated.

On the other hand, if you discovered a problem with the English audio track and updated the Master (either replacing the original file or adding a file with a new filename) then you would need to regenerate the "default-en" and "premium-en" Offerings, using a new Master Version Hash.

Tenancies

To provide access to the Content Fabric, a Tenancy was set up for your organization. This involves creating private keys (i.e. accounts) and configuring various storage areas, permissions, and so forth. The name used when setting up your Tenancy will appear as a prefix in the names of various items such as Libraries, Content Types, and Access Groups. All of the output examples in this document use a Tenancy Name of dev-tenant.

Tenancies also control billing for the Eluvio Content Fabric.

Tenancies have Content Fabric IDs beginning with iten. While you will not usually need to refer to your Tenancy ID, you can view it by clicking on the ELUV.IO logo in the Fabric Browser, then clicking Profile and looking at the Current Tenant section.

Libraries

Content Fabric Objects are contained in Libraries (every Object belongs to one Library).

Libraries have IDs that start with ilib.

When your Tenancy was set up, the following four Libraries were created:

  • TENANCY_NAME - Properties (web sites)
  • TENANCY_NAME - Reports (usage reports)
  • TENANCY_NAME - Title Masters (media master objects)
  • TENANCY_NAME - Title Mezzanines (playable mezzanine objects)

It is possible to create additional Libraries if needed.

Content Types

Content Fabric Objects can be assigned a Content Type which adds certain capabilities. For example, generally Mezzanines are assigned a Content Type of "Title" during creation, which enables any Offerings it contains to be played in streaming format.

Content Types have IDs that start with iq__ (the same as regular Object IDs)

When your Tenancy was set up, a variety of Content Types were created, but for ingesting media we will only need to work with two:

  • TENANCY_NAME - Title (for Mezzanines)
  • TENANCY_NAME - Title Master (for Masters)