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

Since version 1.18.0, ew-vod-modify-subtitles is renamed into ew-vod-modify for more suitable with new feature, adding new audio into vod.

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 add --help or simply type ew-vod-modify add.

This tool can modify subtitles or audios of an existing ESF asset.
It will also modify a manifest.mpd file if present in the asset directory.
Use the subcommands to choose the type of action desired.
To get help for a subcommand, use the --help flag with the subcommand.

Usage:
  ew-vod-modify [command]

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

Flags:
  -h, --help                help for ew-vod-modify
      --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

Use "ew-vod-modify [command] --help" for more information about a command.

Audio format that allow to be added

A progressive MP4 that contains audio with the same duration with the target VoD. Supported codecs: AAC, HE-AACv1, HE-AACv2, AC3, Enhanced AC3.

In case there is multiple audio in side the MP4 file, the first audio track will be chosen.

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, if content_info.json is not found, will descend into all subdirectories.
  -l, --log-file string          log file [default stdout].
      --log-format string        format and type of log: [consolejson consolepretty discard] (default "consolepretty")
      --log-level string         Initial logging level: debug, info, warn, error, fatal, panic. (default "info")
  -m, --mode string              action to perform on thumbnails matching the sizes: generate, remove or extract. (default "generate")
  -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")
      --sprite-max-size uint32   max pixel dimension (width or height) for thumbnail sprite sheet, range [1024, 16000]. Adjust based on your device software or hardware limitations. (default 16000)
  -t, --tmpdir string            temporary working directory. (default "/tmp")
  -w, --workers uint16           number of concurrent worker threads to use for thumbnail generation. (default 4)

Modes

The --mode (-m) option selects what the tool does with the thumbnail tracks matching --sizes. It accepts one of:

remove and extract do not require ffmpeg.

# generate 240 and 320 wide thumbnails (default mode)
ew-thumbnails-generator -i /path/to/esf --sizes 240,320

# remove the 240 wide thumbnails
ew-thumbnails-generator -m remove -i /path/to/esf --sizes 240

# extract the images of the 240 wide thumbnails
ew-thumbnails-generator -m extract -i /path/to/esf --sizes 240

Note: the deprecated -r, --remove flag is still accepted and is equivalent to --mode remove. Passing both --mode and --remove is an error.

The extract mode reads the matching multi-sprites thumbnail tracks (the .imge container and its .dat index, produced since version 1.20) and writes each image out as a standalone <segment>.jpeg file into a per-track subfolder of the source directory. It does not modify content_info.json.

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 hard-coded constraint is for better performance and limited scrub bar length on screen. 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:

--sizes 240,320
--sizes 240x120,320x150
--sizes 240x120,320

In case only width known, the height will be calculated base on video aspect ratio. The number of generated thumbnails tracks will be equal to the number of passed sizes.

The thumbnails are tiled into sprite sheets and served in a SegmentNumber AdaptationSet by SW Repackager to reduce the number of thumbnail requests from client.

The --sprite-max-size option (or --thumbnails-sprite-max-size in ew-vodingest) controls the maximum pixel dimension (width or height) of the generated sprite sheet. The default value is 16000. The upper bound is constrained by ffmpeg’s MJPEG encoder. The allowed range is [1024, 16000]. Adjust this value based on your target device software or hardware limitations, for example if the player or decoder has a lower maximum image size.

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.

ew-parse-dat

This tool prints the content of a .dat segment info file (the per-track index of an ESF asset) in a human readable form. It is useful for inspecting the segment layout of a track.

usage: ew-parse-dat <file.dat>

It takes a single positional argument, the path to the .dat file, and prints one line per segment with the following fields:

Example:

$ ew-parse-dat video.dat
{Nr:1 Time:0 Dur:4000 Size:12345 Offset:0 Rest:0}
{Nr:2 Time:4000 Dur:4000 Size:12000 Offset:12345 Rest:0}
...