VoD Ingest (esb3021)

• 1: Introduction
• 2: Installation
• 3: Tools
• 4: Convoy integrating
• 5: Performance
• 6: SMIL manifest
• 7: Supported codecs
• 8: HDR10 support
• 9: AWS S3 Cloud Usage
• 10: Releases
• 10.1: Release 1.12.0
• 10.2: Release 1.10.0
• 10.3: Release 1.8.0
• 10.4: Release 1.6.0
• 10.5: Release 1.4.0
• 10.6: Release 1.2.0
• 10.7: Release 1.0.0
• 10.8: Release 0.6.2
• 11: Licensing

1 - Introduction

The ew-vodingest command may be used to perform either VoD ingest or to perform live recordings from an ew-live-ingest (esb3003) circular buffer.

VoD ingest

ew-vodingest (ESB3021) reads and ingests an MP4/ts audio and video + subtitles asset defined by a SMIL file into an ESF (Edgeware Storage Format) asset in a way that is compatible with the DASH OnDemand profile. A corresponding DASH MPD file is generated. The SMIL-file syntax and usage is explained in the SMIL section.

It is also possible to specify a .ts-file, an .mp4-file or a directory-path as input.

For example:

ew-vodingest --input hitchcock/vertigo/index.smil --output esf/vertigo

Note: A main focus of this tool is to ingest VoD content that can be used to generate live content by combining VoD assets using ESB3019 ew-vod2cbm. There is therefore a restriction on the ingested content that it must be possible to discover a common constant GoP duration (sync-frame distance) for all video tracks, and that all sample durations are exactly the same in their respective timescales. The timescales may differ, but only by integer factors, for example 50 for 50Hz video and 25 for 25Hz video.

Codec and input format

Please refer to Supported codecs to get more information.

Input locations

This tables shows the possible combinations of input types and locations:

For ingesting large assets (or for slow locations) the --maxtime command-line parameter can be used to increase the timeout threshold.

Output locations

Output locations can always be local filesystem, or network locations, as above. By default the content_id in content_info.json of the output asset will equal the output directory. This can be overridden by specifying any other ID with the --content-id command-line parameter.

Temporary storage

The temporary storage, specified by --local-storage, is used to store the input files from NAS (HTTP, FTP, S3, etc) VOD to reduce overhead, and output files of recording, VOD before uploading to reduce the stress on remote file system.

For those reasons, it is recommended to set it to local filesystem on SSD. The default value is /tmp, which is a RAM disk, best for speed, but has limited capacity.

Live recordings

The input for live recordings is an ew-live-ingest (esb3003) with a circular buffer available on the instance specified by --host and --port (default localhost:8090). The output locations are the same as for VoD ingest above.

The --cbm flag triggers a live recording (and cannot be combined with --i). The start/stop times are specified in epoch seconds, and must be in the past. The recording will consist of integral segments, matching the specified time range as closely as possible. The time-stamps in the resulting VoD will be shifted to start from zero. Any “holes” in the specified intervals will be removed, thus resulting in a recording shorter than the specified interval.

SCTE-35 markers are transferred from the CBM interval and stored in a separate file.

For example:

ew-vodingest --cbm --start-epoch 1678190071 --stop-epoch 1678190099 --channel tv1 -o tv1-mar-7-2023

Note: VCP Origin is end of support. No longer supported by ew-vodingest.

Usage

ew-vodingest is a command-line tool that is run as:

ew-vodingest [options]

Run as ew-vodingest [options]

  -i, --input string               SMIL file, dir or file pattern defining the asset (mandatory). Can't be used with --cbm.
  -o, --output string              output directory (mandatory)
  -w, --minseg int                 minimum output segment duration (milliseconds) (default 4000)
  -y, --maxseg int                 maximum output segment duration (milliseconds) (default 12000)
      --cbm                        set to use esf export from cbm. Can't be used with --input.
      --start-epoch uint           recording start time given in epoch seconds. Only works with --cbm
      --stop-epoch uint            recording stop time given in epoch seconds. Only works with --cbm
      --channel string             channel name to record from. Only works with --cbm
      --drop-non-aligned-track     drop track with abnormal segment duration. Only works with --cbm
  -c, --content-id string          explicit content-id (instead of ingest path)
  -m, --maxtime int                maximal execution time to ingest asset (seconds) (default 1800)
      --hls                        output HLS playlists (experimental)
      --slim                       only output content_info and dat files
      --leavepartial               leave partial ingested content on failure
      --s3file string              path to S3 credentials file
  -t, --template string            path to content template file, for asset comapatibility verification
      --licensefile string         license file path (default "/etc/edgeware/ew-vodingest/license.json")
  -l, --logfile string             log file [default stdout]
      --log-file string            see above
      --logformat string           format and type of log: [consolejson consolepretty discard] (default "consolepretty")
      --loglevel string            initial log level (default "info")
  -v, --version                    print version and date
      --host string                cbm host to connect to. Only works with --cbm (default "localhost")
      --port uint16                cbm port to connect to. Only works with --cbm (default 8090)
      --source-rate-limit uint32   maximum read rate in Mbps from source. Only works with --cbm. Setting 0 will disable source rate limiting
      --local-storage string       Destination for storing input temporarily when ingesting from HTTP(s), S3 or FTP. Also store output temporarily when uploading to S3 or FTP. If empty, use '/tmp'. When being used with --cbm, it is used for storing the recorded content from CBM before uploading.
      --thumbnails                 enable thumbnail generating, requires command 'ffmpeg' to work
      --thumbnails-sizes string    comma separated list of thumbnail sizes width[xheight],...If only widths are provided, the height will be calculated to keep aspect ratio, nothing provided, auto generate a thumbnails with 240 as width
      --help                       extended tool help

The following options -i, -o, -w, -y, --cbm, --start-epoch, --stop-epoch, --channel, -l, --source-rate-limit are the same as for the ESB3005 ew-recorder.

To enable DASH thumbnails generation, add flag --thumbnails. About --thumbnails-sizes, it acts like --sizes in ew-thumbnails-generator tool, please refer to Tools for more information. These options are available from version 1.12.0.

2 - Installation

The command line tool ew-vodingest and the other tools can be installed on a Linux distribution compatible with RedHat Enterprise Linux 8 with:

$ sudo dnf install ew-vodingest-x.y.z-1.x86_64.rpm

To uninstall:

$ sudo dnf remove ew-vodingest.x86_64

3 - Tools

The ew-vodingest rpm also contains number of tools that can be used to investigate and manipulate ESF format (CMAF + metadata) made by the VoD Ingest.

All utilities will print a usage help message if you specify the -h flag.

ew-check-variant-alignment

The tools lists the start and stop times of every variants of the output recording or managed VOD. In the strict check mode, it fails with non-zero exit code if there is unalignment found.

usage: ew-check-variant-alignment [-h] [-v] [-s] content_path

Check ESF variant alignment

positional arguments:
  content_path

optional arguments:
  -h    Show help message
  -s    Run in 'strict check mode'
  -v    Enable verbose output

ew-vod-modify-subtitles

This tool can modify subtitle and caption tracks of ingested assets.

It only works on ESF assets that are available as a mounted file directory. If the asset was ingested with ew-vodingest and has a DASH MPD file, it will also be updated. Other features from ew-vodingest like storing original subtitle files with a BaseURL link in content_info.json are also implemented.

The tool has commands like add, delete, modify, etc to allow changes to the asset. Each command has its own flags. To get help for a command, use the –help flag with the command, like $ ew-vod-modify-subtitles add --help or simply type ew-vod-modify-subtitles add.

Usage:
  ew-vod-modify-subtitles [command]

Available Commands:
  add         Add a new subtitle track to an asset
  completion  Generate the autocompletion script for the specified shell
  delete      Delete an existing subtitle track
  help        Help about any command
  list        Lists available subtitle tracks
  modify      Modify attributes of an existing subtitle track
  rename      Rename an existing subtitle track
  replace     Replace an existing subtitle track

Flags:
  -h, --help                help for ew-vod-modify-subtitles
      --log-file string     log to specified file instead of standard output
      --log-format string   format and type of log: [consolejson consolepretty discard] (default "consolepretty")
      --log-level string    log level (trace|debug|info|warn|error|fatal|panic) (default "info")
  -v, --version             version for ew-vod-modify-subtitles

ew-thumbnails-generator

This tools is only available from version 1.12.0 and used to generate DASH thumbnails tracks for existing ESF asset:

Basic usage of ew-thumbnails-generator:
  ew-thumbnails-generator -i /path/to/esf --sizes "width[xheight[,width[xheight]]]"


Generate thumbnails for video in the source directory. Requires command 'ffmpeg' to be available"

Run ew-thumbnails-generator with options:

  -i, --input string       source directory
  -l, --logfile string     log file [default stdout]
      --logformat string   format and type of log: [consolejson consolepretty discard] (default "consolepretty")
      --loglevel string    Initial logging level: debug, info, warn, error, fatal, panic (default "info")
  -r, --remove             remove existing thumbnails instead of generating (base on the sizes)
  -s, --sizes string       comma separated list of thumbnail sizes 'width[xheight],...'If only widths are provided, the heights will be calculated to keep aspect ratio. In case nothing provided, auto generate a thumbnails with 240 as width (default "240")
  -t, --tmpdir string      temporary working directory (default "/tmp")

How does it work?

The tool will execute ffmpeg for generating images by extracting first IDR frame of segments. The maximum number of thumbnails will be 500, that means, if there are more than 500 segment in the video, this tool will just only generate 500 thumbnails. This is for better performance and the fact that 500 images is a reasonable ammount of images to display on scrub bar. The tool will automatically pick the reasonable segments from which IDR frames will be extracted.

The thumbnails will be resized base on the --sizes argument. You can enter only width for size, or widthxheight or mixed, the sizes must be seperated by comma. Below are acceptable inputs:

--size "240,320"
--size "240x120,320x150"
--size "240x120,320"

In case only width known, the height will be calculated base on video resolution.

height = videoHeight * (width / videoWidth)

The number of generated thumbnails track will equal with the number of sizes.

The thumbnails will be combined into a single image and will be served as a tile in a SegmentNumber AdaptationSet by repackager to reduce the number of requests toward repackager.

Notes:

• Because this tool base on ffmpeg, ffmpeg and its license should be installed and managed by user, the rpm package will not install it by default. And please make sure all necessary codec libraries are installed. For example, if the system is only using H264, only H264 codec libraries must be installed, H265 codec libraries can be skipped. Refer to Supported codecs for more information about current supported codecs of ew-vodingest.
• Only jpeg is supported by now.
• This tool only compatible with the output of ew-vodingest and ew-recorder. The output of old convoy-live-ingest is not supported.

4 - Convoy integrating

Currently Convoy, a product that managed the streamers and origins, is using the tool named ew-recorder for recording and uploading VoD. That tool was written in python and not so good in performance and resource usage. ew-vodingest tends to resolve these problems.

This document’s purpose is to make to integrating process between ew-vodingest and Convoy becomes clear.

How to install ew-vodingest in Convoy?

From Convoy version 2.30, it has already been installed along when installing Convoy.

Installing or upgrading ew-vodingest on Convoy by:

yum install -y <path to ew-vodingest RPM>

Integrating for recording

For using ew-vodingest for recording on Convoy, ingest script for recorder must be changed to ew-vodingest

...
ccmi.webtv_recorders {
  liveingest1 {
    host = 1.2.3.4
    port = 8090
    live_buffer = 600
    storage = storage1
    ingest_script = /usr/bin/ew-vodingest
    channel_groups = { swlive }
  }
}
...

Then, recording will be handled by ew-vodingest.

DASH thumbnails for recordings

To generate DASH thumbnails, an option must be added when executing ew-vodingest. Unfortunately, this option cannot be added directly into ingest_script configuration above, so we should use this script:

#!/bin/bash
set -e
export PATH="$PATH:/usr/bin"
/usr/bin/ew-vodingest --thumbnails "$@"

The change in PATH variable above means to allow ew-vodingest to search for ffmpeg command. /usr/bin can be changed to wherever ffmpeg is placed.

Put this script into any bash script file, for example /usr/bin/ew-custom-recorder, and the configuration will look like this

...
ccmi.webtv_recorders {
  liveingest1 {
    host = 1.2.3.4
    port = 8090
    live_buffer = 600
    storage = storage1
    ingest_script = /usr/bin/ew-custom-recorder
    channel_groups = { swlive }
  }
}
...

Notes:: The above script is just a simple example and can be modified for more purposes.

Integrating for uploading

From Convoy 2.30, you can change the configuration of Convoy to change the uploading script:

upload.repackager_bin = /usr/bin/ew-vodingest

For older Convoy, you should change the symlink /usr/bin/recorder, and make it point to ew-vodingest.

ln -sf /usr/bin/ew-vodingest /usr/bin/recorder

DASH thumbnails for uploadings

Because ew-check-variant-aligment, a legacy tool of ew-recorder, are still being used for checking the asset before uploading it, a similar solution with recording above cannot be used since thumbnails tracks are not accepted by that tool.

Thus, thumbnails generating has to be executed after the checking step, and that can be achieved by using this script:

#!/bin/bash
set -e
/usr/lib64/ew-repackaging-recorder/bin/ew-check-variant-alignment "$@"
/usr/bin/ew-thumbnails-generator -i "$2"

Put above script into a file, for example /usr/bin/ew-custom-checker, and change the symlink:

ln -sf /usr/bin/ew-custom-checker /usr/bin/ew-check-variant-alignment

Notes::

• The above script is just a simple example and can be modified for more purposes.

• ew-check-variant-aligment are going to be replaced in the future.

5 - Performance

This is the performance report for the vodingest tool. The results are affected by i/o capacity of the system and the system load. The results are not absolute and should be used as a reference only since the input from customer can be vary in codec, combination of tracks and so on. All of this results are measured with the input data is on local file system, not mounted or from external backend like nfs, s3 or http since the throughput of the backend can affect the results.

The scenarios are now run with the following formats: MP4 progressive, TS and Fragmented MP4 (fMP4) as DASH On-Demand. All other formats like SMIL or HLS are just the manifest in text, the base containers are still MP4, TS or fMP4.

Manifest text and subtitles tracks are not included in the results since their cost to be processed is too small compare to the video and audio tracks.

The results are based on the average of the runs.

CPU information: Intel(R) Xeon(R) CPU E31220 @ 3.10GHz

MP4 progressive

TS

DASH On-Demand (fMP4)

6 - SMIL manifest

Input SMIL syntax

SMIL is an XML format for multimedia presentation. It can be used instead of an HLS master playlist or DASH Media Presentation File to tell what media files should be combined into an asset and some associated metadata parameters. The level of detail, however, is much lower than in the other formats. ew-vodingest supports the import of MP4 files for video and audio, in connection to subtitle files.

Our usage of SMIL follows legacy format of Wowza, but we have added some parameters, such as displayName for HLS and role for subtitles.

Basic structure

SMIL files should specify all relevant media files in a switch block in the body:

<?xml version="1.0" encoding="UTF-8"?>
<smil>
    <body>
        <switch>
            <video src="movie1.mp4" ... />
            <video src="audio.mp4" ... />
            <textstream ... />
            <srt ... />
        </switch>
    </body>
</smil>

Stream types

The supported stream types are <video> which either means video, audio or both, <texstream> that is a subtitle file or <srt> which is a subtitle file in SRT format.

Video/Audio streams

Audio and video streams are identified by the video tag.

Minimal configuration

The simplest variant is to just give a src attribute:

<video src="videoAndAudio.mp4"/>

If this is the only information give, all video and audio tracks will be extracted and given names following the patterns

depending on what tracks and codecs are available. The bitrate is calculated from the file size and duration and the language is extracted from the mp4 file if available in an elng, of in the mdhd box as a fallback.

If multiple files are specified in the SMIL file, tracks will be extracted from all of them, but if the resulting names (mediatype_codec_bitrate_language) coincide, only one copy will be kept. This makes it possible to import files which all include the same audio bitrate and language, but different video bitrates.

Specifying the bitrate

The system-bitrate attribute is used to specify the bitrate for the stream.

<video src="video.mp4" system-bitrate="2500000" />

Optionally it is possible to specify bitrates as <param> values as

<video src="videoAndAudio.mp4">
    <param name="videoBitrate" value="2500000"/>
    <param name="audioBitrate" value="128000"/>
</video>

Track selection and track-specific parameters - mp4

To achieve higher control over the extraction of tracks, and their parameters, it is possible to add extra parameters.

In particular, one can use the audioOnly and videoOnly keys to specify that only one type of media track should be extracted.

To extract audio and video in this way, one could use the following snippet:

<video src="videoAndAudio.mp4" system-bitrate="2500000">
    <param name="videoOnly" value="TRUE"/>
</video>
<video src="videoAndAudio.mp4" system-bitrate="128000">
    <param name="audioOnly" value="TRUE"/>
</video>

In addition, one can add an audioindex query index to extract a specific audio track. The audioindex value relates to the track ID inside an mp4 file, but is zero-based. The mapping is that ?audioindex=0 refers to the audio track with the lowest track ID, ?audioindex=1 to the second, and so on.

Here is an example that extracts the first two audio tracks, and gives them different parameters for language, bitrate, and displayName:

<video src="hev1_aac_mc.mp4?audioindex=0" system-language="dk" audio-bitrate="256000">
<param name="audioOnly" value="TRUE"/>
<param name="displayName" value="Danish 6ch"/>
</video>
<video src="hev1_aac_mc.mp4?audioindex=1" system-language="dk" audio-bitrate="192000">
<param name="audioOnly" value="TRUE"/>
<param name="displayName" value="Danish 2ch"/>
</video>

Track selection and track-specific parameters - ts

For multiplexed .ts-files the audio tracks are selected by specifying the trackID parameter corresponding to the PID, as follows:

      <video src="0.ts" audio-bitrate="94000" systemLanguage="spa">
        <param name="audioOnly" value="TRUE" />
        <param name="trackID" value="482"/>
        <param name="displayName" value="español"/>
      </video>

Audio Language

The language for an audio stream can be set using the system-language attribute:

<video src="mp4:video3.mp4?audioindex=0" system-language="eng">

For legacy reasons, one can alternatively use the attribute systemLanguage or language.

If the language is not specified, 3-letter language code in the mdhd box will be used. It will in turn be overridden by the optional elng box that can contain any language code.

Subtitle input

The supported input subtitle formats are TTML, WebVTT, STL, SRT. In all cases, a complete side-loaded file is expected. As part of the ESF format, the subtitles will be transformed into segmented wvtt. A complete WebVTT file will also be generated and referred to in the generated DASH manifest. The name of the output subtitle tracks are of the form

The role can be either caption or subtitle. If not specified, the role will be not be in the track name.

Subtitle streams in TTML, WebVTT, STL, or STT files are specified with the <textstream> or <srt> tags. The language can be specified with language attribute, or, for textstream, with the system-language attribute like:

<textstream src="subtitles.ttml" system-language="en" />
<srt src="swedish.srt" language="se"/>

The format is auto-detected from the file extension, which must be one of:

 .ttml, .webvtt, .vtt, .stl, .srt

The case of multiple languages in the same TTML file is not supported.

There is no bitrate specified for text streams. It will always be set to 1kbps.

Extracting language from subtitle file name

For the case where the SMIL-file is missing or there is no language attribute for the subtitle files, ew-vodingest will try to extract a language from the file name. The language extraction algorithm works like this:

1. the file extension is removed
2. split the name on “-” characters
3. if the last part is at most three characters, use it as a language code

If a language is not found, the subtitle languages will be denoted “und”, “und1”, “und2” etc.

Example SMIL files

In the following, we give examples to show some possible variations of supported SMIL files.

Example 1 - video and audio from all files

This example has width and height for the video. That information will be discarded. There are only two distinct combinations of language and bitrate for audio, so only two variants audio_aac_eng_128kbps and audio_aac_eng_192kbps will be generated.

<?xml version="1.0" encoding="UTF-8"?>
<smil>
    <body>
    <switch>
        <video height="360" src="profile1.mp4" systemLanguage="eng" width="480">
        <param name="videoBitrate" value="500000"/>
        <param name="audioBitrate" value="128000"/>
        </video>
        <video height="480" src="profile2.mp4" systemLanguage="eng" width="720">
        <param name="videoBitrate" value="800000"/>
        <param name="audioBitrate" value="128000"/>
        </video>
        <video height="540" src="profile3.mp4" systemLanguage="eng" width="960">
        <param name="videoBitrate" value="1300000"/>
        <param name="audioBitrate" value="128000"/>
        </video>
        <video height="720" src="profile4.mp4" systemLanguage="eng" width="1280">
        <param name="videoBitrate" value="2300000"/>
        <param name="audioBitrate" value="192000"/>
        </video>
        <video height="1080" src="profile5.mp4" systemLanguage="eng" width="1920">
        <param name="videoBitrate" value="5000000"/>
        <param name="audioBitrate" value="192000"/>
        </video>
    </switch>
    </body>
</smil>

Example 2 - audioindex queries

This example shows extraction of audio tracks using the audioindex query parameter. The mp4: “scheme” is not needed, but supported for legacy reasons. The mp4:/// scheme is also supported for the same reason.

<?xml version="1.0"?>
<smil>
    <body>
    <switch>
        <video src="mp4:video1.mp4?audioindex=0" system-language="eng" audio-bitrate="96000">
        <param name="audioOnly" value="TRUE"/>
        </video>
        <video src="mp4:video1.mp4?audioindex=1" system-language="ger" audio-bitrate="96000">
        <param name="audioOnly" value="TRUE"/>
        </video>
        <video src="video2.mp4" system-bitrate="2000000">
        <param name="videoOnly" value="TRUE"/>
        </video>
        <video src="video1.mp4" system-bitrate="5000000">
        <param name="videoOnly" value="TRUE"/>
        </video>
        <textstream src="subtitles.ttml" system-language="eng">
        </textstream>
    </switch>
    </body>
</smil>

Notes: audioindex cannot be used when ingesting VOD over HTTP/FTP server.

Example 3 - displayName and role parameters

This example uses parameters for displayName for audio and subtitles, and role for subtitles.

<?xml version="1.0" encoding="utf-8"?>
<smil>
  <body>
    <switch>
      <video src="video800.mp4" system-bitrate="800000">
        <param name="videoOnly" value="TRUE"/>
      </video>
      <video src="video400.mp4" system-bitrate="400000">
        <param name="videoOnly" value="TRUE"/>
      </video>
      <video src="audio.mp4?audioindex=0" system-language="eng" audio-bitrate="256000">
        <param name="audioOnly" value="TRUE"/>
        <param name="displayName" value="English 6ch"/>
      </video>
      <video src="audio.mp4?audioindex=1" system-language="eng" audio-bitrate="192000">
        <param name="audioOnly" value="TRUE"/>
        <param name="displayName" value="English 2ch"/>
      </video>
      <srt src="swe.srt" language="swe">
        <param name="displayName" value="svenska"/>
        <param name="role" value="subtitle"/>
      </srt>
      <srt src="swe_cc.srt" language="swe">
        <param name="displayName" value="svenska (CC)"/>
        <param name="role" value="caption"/>
      </srt>
      <textstream src="eng.stl" system-language="eng">
        <param name="displayName" value="English"/>
        <param name="role" value="caption"/>
      </textstream>
    </switch>
  </body>
</smil>

Example 4 - The simplest possible - same as no SMIL

This example shows a SMIL file where all parameters are extracted automatically. In this case all video sources contain audio with language set to engin the mdhd box in the mp4 files, and the subtitle languages can be extracted from the file names.

<?xml version="1.0" encoding="UTF-8"?>
<smil>
  <body>
    <switch>
      <video src="0.mp4"/>
      <video src="1.mp4"/>
      <video src="2.mp4"/>
      <video src="3.mp4"/>
      <srt src="xyz-eng.srt"/>
      <srt src="xyz-spa.srt"/>
    </switch>
  </body>
</smil>

The generated tracks are:

• 4 video tracks with different bitrates
• 2 audio track with different bitrates, but the same language “eng”
• 2 subtitle tracks with language codes “eng” and “spa”

In this particular case, the SMIL file just provides a list of files and no extra parameter. Therefore, it is also possible to specify the directory of this file as input to ew-vodingest and get exactly the same result.

7 - Supported codecs

Progressive MP4

An MP4 file contains all video and audio tracks. All the tracks in that MP4 will be extracted except subtitle.

Video

H.264/AVC and H.265/HEVC with multiple bitrates.

For H.264/AVC, both avc1 and avc3 are accepted, but the result always be stored with avc1 type of video sample entry box.

For H.265/HEVC, both hev1 and hvc1 are accepted, but the result will always be stored with hev1 type of video sample entry box.

In case a common GoP duration of all video tracks can be found, one or more common GoP will be combined to form a segment that has duration --minseg to --maxseg, if we have more than one segment durations that satisfy the range, the lowest one will be chosen. Then, all output video tracks will be segmented with the same segment duration.

On the other hand, if a common GoP duration among video tracks cannot be found, the segments will be formed base on the sync-frames distances of each video track. Segment will begin with a sync-frame, it can contain one or more sync-frames in it and will end right before a sync-frame (end sync-frame). The DTS diff between begin sync-frame and end sync-frame is segment duration and will be from --minseg to --maxseg. In this case, the segment duration can be vary, but the duration of corresponding segments within tracks will be the same.

Video track timescales, as defined in mdhd box, need to be the same among videos, or differ by an integer factor like 50 and 25 with factor is 2, or 60000 and 20000 with factor is 3.

Audio

AAC, HE-AACv1, HE-AACv2, AC3, Enhanced AC3, and MP4 with multiple bitrates and languages. Language will be gotten from mdhd box.

Subtitle

Embedded subtitle are not supported.

Note: you can add subtitle track later by this tools. Or you can use Directory input method by putting MP4 files and subtitle files into the same directory.

SMIL + progressive MP4

In this case, the assets have a SMIL file describing the Progressive MP4 video, audio and text stream.

Video

The same with Progressive MP4

Audio

The same with Progressive MP4

Subtitle

The SMIL-file syntax and usage is explained in the SMIL section. In that section, you can also find the subtitle specification at Subtitle input.

MPEG2-TS

A TS file contains all video and audio tracks, and them all will be extracted except subtitle track.

Video

H.264/AVC and H.265/HEVC with multiple bitrates.

In case a common GoP duration of all video tracks can be found, one or more common GoP will be combined to form a segment that has duration --minseg to --maxseg, if we have more than one segment durations that satisfy the range, the lowest one will be chosen. Then, all output video tracks will be segmented with the same segment duration.

On the other hand, if a common GoP duration among video tracks cannot be found, the segments will be formed base on the sync-frames distances of each video track. Segment will begin with a sync-frame, it can contain one or more sync-frames in it and will end right before a sync-frame (end sync-frame). The DTS diff between begin sync-frame and end sync-frame is segment duration and will be from --minseg to --maxseg. In this case, the segment duration can be vary, but the duration of corresponding segments within tracks will be the same.

The timescale in TS file must be standard, 90000.

Audio

AAC, HE-AACv1, HE-AACv2, AC3, and Enhanced AC3 with multiple bitrates and languages. Language will be gotten from stream descriptors in PMT.

Subtitle

Embedded subtitle are not supported.

Note: you can add subtitle track later by this tools. Or you can use Directory input method by putting TS files and subtitle files into the same directory.

Directory

A directory contains all the input TS, MP4 and subtitle files. ew-vodingest will scan and extract all the media tracks from the media files in that directory.

Video

The same with Progressive MP4 and MPEG2-TS sections, duplicated tracks are going to be dropped.

Audio

The same with Progressive MP4 and MPEG2-TS sections, duplicated tracks are going to be dropped.

Subtitle

Side-loaded subtitle text files are supported.

Supported formats: ttml, webvtt, srt, stl. Subtitle format will be detected by the file extension: .ttml for ttml format. .vtt and .webvtt for webvtt format. .srt for srt format. .stl for stl format.

MPEG DASH On-Demand Profile

A DASH On-Demand MPD file describes the asset.

Video

H.264/AVC and H.265/HEVC with multiple bitrates.

For H.264/AVC, both avc1 and avc3 are accepted, but the result always be stored with avc1 type of video sample entry box.

For H.265/HEVC, both hev1 and hvc1 are supported, but the result always be stored with hev1 type of video sample entry box.

All video tracks need to have the same timescale as defined in mdhd box.

Audio

AAC, HE-AACv1, HE-AACv2, AC3 and Enchaned AC3 with multiple bitrates and languagues.

Subtitle

Side-loaded subtitle text files are supported under formats: ttml, webvtt, srt.

Side loaded subtitle fragmented mp4 files is supported under formats: stpp and fragmented webvtt.

CEA608 Closed Captions is preserved from MPD manifest file.

Apple HLS

A Master Playlist file describes the asset. Multiplexed and isolate video and audio tracks are both supported in individual segment files or a concatenated files.

Video

H.264/AVC in TS encapsulation.

H.264/AVC and H.265/HEVC are supported in fMP4 encapsulation.

Audio

AAC, HE-AACv1, HE-AACv2, AC3 and Enhanced AC3 in fMP4 and TS encapsulation.

Subtitle

HLS WebVTT as side loaded, complete or segmented text files.

HLS stpp as fragmented files.

CEA608 Closed Captions are preserved from master playlist (.m3u8 file).

Microsoft Smooth Streaming

The MSS manifest file is used to define the asset.

Video

H.264/AVC with multiple bitrates.

Although it is not standard, H.265/hevc with muiltiple bitrates is supported.

Audio

AAC and HE-AAC with multiple bitrates and languages.

Subtitle

TTML as side-loaded complete files.

IIS Smooth Streaming

The ISM manifest file is used to define the asset.

Video

H.264/AVC with multiple bitrates. The codec string of video tracks must be AVC1, even H264 is not supported.

Audio

AAC and HE-AAC with multiple bitrates and languages.

Subtitle

TTML as side-loaded complete files.

8 - HDR10 support

When ingesting TS streams, HDR10 is detected by parsing SPS. If the HDR10 info is included in the TS streams, the VUI part of SPS will contain colour_primaries with value 9, matrix_coeffs with value 9 and transfer_characteristics with value 16. If ew-vodingest detects exactly HDR10 info with these values, it will do following things:

• Add new hdr field to video variant in content_info.json. This field currently supports only one value hdr10. The video variant info will look like this:

  "variants": [
    {
      "media_type": "video",
      "subtype": "hevc",
      "name": "video_hevc_886kbps",
....
      "hdr": "hdr10",

• Add compatible brand “chd1” to ftyp box of video file .cfmv

[ftyp]
 - majorBrand: mp42
 - minorVersion: 512
 - compatibleBrand: chd1

Beside the VUI part of SPS, the following SEI NAL units may be present in the TS streams: Mastering display colour volume (SEI payload type 137) and Content light level information (SEI payload type 144). But this signal is optional, ew-vodingest doesn’t rely on them to detect HDR10. If these SEI NAL units are present, ew-vodingest will just add them to the hvcc box of video file .cfmv

For MP4 input, ew-vodingest does exactly the same behaviours, but the behaviour which add above SEI NAL units to hvcc box has not been tested.

9 - AWS S3 Cloud Usage

To ingest to or from S3, the path is specified with s3://. For example:

ew-vodingest --input s3://mybucket/dir1 --output /home/myhome/esf1 --s3file /home/myhome/.aws/credentials.json

S3 credentials file

You must create a JSON file for the credentials. (The credentials file used by the AWS CLI is not used.) For example:

{
    "profile": "default",
    "region": "eu-north-1",
    "id": "AKIAQWERTYQWERTY",
    "key": "qwerty123+QWERTY123&qwerty"
}

The actual values must be obtained from the AWS administration console. Here id and key correspond to "Access key ID" and "Secret access key".

10 - Releases

ESB3021 - ew-vodingest releases

10.1 - Release 1.12.0

Change log

• NEW: Generate DASH image-based thumbnails for recording and VoD [ESB3021-165]
• NEW: Detect recording GoP duration for better integration with ew-vod2cbm [ESB3021-159]
• NEW: Support recording for low-latency channels [ESB3021-161]
• NEW: Support --local-storage option for recording, input and temporary output [ESB3021-171]
• IMPROVED: Better --source-rate-limit handling. Improve accuracy in checking used bandwidth [ESB3021-96]
• FIXED: Fail to get inband codec information for DASH On-Demand [ESB3021-168]
• FIXED: All audios tracks extracted, even though audioindex is defined in SMIL [ESB3021-175]

Known limitations:

• Does not preserve TTML subtitle styling
• VoD ingest of SMIL over HTTP/FTP, does not work with query parameter audioIndex

Compatibility has been verified with the following products:

• Sw Repackager: 1.50.3
• Sw Live Ingest: 1.40.1
• Convoy: 3.2.1
• Sw Streamer: 1.34.0
• Orbit TV Server: 3.4.1

Release information

• Date: 2024-10-23
• Type: Production release

10.2 - Release 1.10.0

Change log

• NEW: New subtitle format support. cmft for HLS/DASH and stpp for DASH [ESB3021-129]
• NEW: Preserve SCTE35 information for HLS input [ESB3021-130]
• NEW: Support FTP ingest [ESB3021-151]
• NEW: Allow repackager to output VOD DASH SegmentNumber [ESB3021-160]
• IMPROVED: Better command line help [ESB3021-131]
• FIXED: Missing original subtitle after ingestion. Problem in 1.8.0 with lost subtitles [ESB3021-136]
• FIXED: Broken AC3/E-AC3 sample data lead to broken audio data. Audio will be muted [ESB3021-137]
• FIXED: Newline tag in ttml is not preserved [ESB3021-147]
• FIXED: Missing space characters when preserving styling in webvtt [ESB3021-149]
• FIXED: Crash on empty line of m3u8 files [ESB3021-153]
• FIXED: Cannot download input from external servers. this happens when the manifest (includes MPD and M3U8) contains absolute URL for media segments/files [ESB3021-154]
• FIXED: Multiple languages TTML subtitle is not supported [ESB3021-158]

Known limitations:

• Does not preserve TTML subtitle styling
• VoD ingest of SMIL over HTTP/FTP, does not work with query parameter audioIndex

Compatibility has been verified with the following products:

• Sw Repackager: 1.48.2
• Sw Live Ingest: 1.38.2
• Convoy: 3.0.1
• Sw Streamer: 1.34.0
• Orbit TV Server: 3.2.1

Release information

• Date: 2024-06-25
• Type: Production release

10.3 - Release 1.8.0

Features:

• New: Support for HLS VOD input
• New: Support for unencrypted ISM/MSS
• New: Support for irregular sample duration VODs (TS and MP4)
• New: Preserve WebVTT styling
• New: Support Audio Descriptions in VOD ingestion
• Fix: Missing CUE-IN for one segment ad break
• Fix: Average segment duration appears in content_info.json when common GoP cannot be detected
• Fix: Incorrect audio language
• Fix: Incorrect audio codec
• Fix: Duplicate track name for HEVC HDR and SDR tracks
• Fix: Ingest stops due to unrecognized tag in smil
• Fix: Missing role for subtitle track
• Fix: Cannot parse PES packet containing more than one AAC frame, causing silent audio output
• Fix: Incorrect maximum segment duration in content_info.json
• Fix: Redundant HLS target duration in content_info.json

Known limitations:

• Does not preserve TTML subtitle styling
• VoD ingest of SMIL over HTTP, does not work with query parameter audioIndex

Compatibility has been verified with the following products:

• Sw Repackager: 1.46.2
• Sw Live Ingest: 1.38.0
• DRM Gateway: 2.30.1
• Convoy: 2.36.0

Release information

• Date: 2023-11-29
• Type: Production release

10.4 - Release 1.6.0

Features:

• New: Support for DASH On-Demand
• New: Option to throttle the reading rate from local storage
• Fix: Incorrect subtitles timing
• Fix: Ingestion failed when missing some samples at the end of tracks
• Fix: Cannot stream MSS throught ew-repackager
• Fix: Lingering .dat file after ingestion failed
• Fix: Missing field content_duration_ms for recordings
• Fix: Language code is not extracted from subtiles filename when ingesting from SMIL (if language is not defined in SMIL)

Known limitations:

• Does not preserve subtitle styling
• VoD ingest of SMIL over HTTP, does not work with query parameter audioIndex

Release information

• Date: 2023-09-18
• Type: Production release

10.5 - Release 1.4.0

Features:

• New: Support for EC-3 audio in transport streams
• New: ew-vodmod tool to modify subtitle tracks of ingested VoD assets
• New: Option to drop incompatible media tracks
• Fix: ew-vodingest did not escape special character for WVTT format
• Fix: corrected VOD-asset duration in log
• Fix: corrected dropping of too early audio samples in TS ingest (causing “Bad box size” error)

Known limitations:

• Does not preserve subtitle styling
• HDR10 has not been tested fully on MP4 file
• VoD ingest of SMIL over HTTP, does not work with query parameter audioIndex
• live-recording-asset duration is logged as zero

Release information

• Date: 2023-06-08
• Type: Production release

10.6 - Release 1.2.0

Features:

• New: Live recordings (with esb3003 CBM)
• New: Command-line content-id (esb3005 style)
• New: Content template verification, for esb3019 integration
• New: Allow non-constant GoP-durations
• New: Improved S3 and NFS failure handling
• Fix: Superfluous audio-track generation
• Fix: Confused output audio bandwidths
• Fix: ADTS headers with 2-byte CRC

Known limitations:

• Does not preserve subtitle styling
• HDR10 has not been tested fully on MP4 file
• VoD ingest of SMIL over HTTP, does not work with query parameter audioIndex

Release information

• Date: 2023-03-08
• Type: Production release

10.7 - Release 1.0.0

Features:

• Ingest single file TS
• Ingest single file MP4
• Support for HDR10
• S3 and HTTP support
• Timeout handling
• Improved logging
• Offline licensing

Known limitations:

• Require constant GoP duration and constant sample steps
• Does not preserve subtitle styling
• HDR10 has not been tested fully on MP4 file

Release information

• Date: 2022-12-02
• Type: First production release

10.8 - Release 0.6.2

Features:

• Ingest SMIL + mp4 + subtitle assets in combined ESF + DASH OnDemand format
• Support AVC, HEVC video
• Support AAC, AC-3 audio
• Support TTML, WebVTT, SRT, STL subtitles
• Support displayName parameter for audio and subtitles
• Support role (caption or subtitle) parameter for subtitles

Known limitations:

• Requires mounted file system for input and output
• Require constant GoP duration and constant sample steps
• Does not preserve subtitle styling
• Logging is not nice

Release information

• Date: 2022-03-28
• Type: Beta for testing
• Expiration Date: 2022-09-24

11 - Licensing

ew-vodingest requires a valid license file to operate. The license file must be obtained from Agile Content, and copied to /etc/edgeware/ew-vodingest/license.json. Note: ew-vodingest only operates with offline licenses.

See further details here.