omakase-media-tools 0.1.2

A CLI utility and samples for creation of sample media and temporal metadata tracks for use with the Omakase Player framework

Omakase Player Command Line Utility

This PIP package provides a command line utility for use with the reference implementation of the Omakase Player open source project.

The CLI utility may be used to generate temporal metadata tracks for use with the Omakase Player framework.

The Python script 'create_omp_tracks.py' is used for creating Omakase Player temporal metadata tracks from source media files. The script is capable of generating the following types of metadata tracks:

• Audio Metric Analysis Tracks using the create_omp_tracks --audio-metrics CLI option
• Audio Waveform Analysis Tracks using the create_omp_tracks --waveforms CLI option
• Video Bitrate Analysis Tracks using the create_omp_tracks --video-bitrate CLI option
• Video Thumbnail Tracks using the create_omp_tracks --thumbnails CLI option

The create_omp_tracks.py utility is provided to help demonstrate the capabilities of the Omakase Player framework and to bootstrap small POC projects. The CLI utility is provided as-is and are not intended to be used in a production environments.

The reference implementation of the reference player can be found in GitHub at omakase-player.

Contents:

• Requirements
• Installation
• Usage
  • Usage create_omp_tracks.py --thumbnails
  • Usage create_omp_tracks.py --video-bitrate
  • Usage create_omp_tracks.py --audio-metrics
  • Usage create_omp_tracks.py --waveforms
• External Links
• License

Requirements

---

Python

• Python 3.6 or higher

ffmpeg

• Download a static build from the ffmpeg website and install using the instructions for your platform.
• Ensure that the ffmpeg executable is in your path.

audiowaveform

audiowaveform is a C++ program that takes an audio file and generates raw waveform data from it.

This data is then used to generate an OMP v1.0 VTT file containing the waveform metadata needed by the Omakase Player.

• download and install from GitHub here: audiowaveform

ffmpeg-bitrate-stats

The ffmpeg-bitrate-stats Python package is used to generate raw video bitrate metrics, when are then processed to create an OMP v1.0 VTT file for use with Omakase Player.

• Install the ffmpeg-bitrate-stats Python package from the following GitHub repository: ffmpeg-bitrate-stats

Installation

---

• Install the PIP package omp-media-tools from PyPi.

Usage

---

The Python script create_omp_tracks.py is a command line utility that can generate Omakase Player temporal metadata tracks from source media files. It is capable of generating the following types of metadata tracks:

• Audio Metric Analysis Tracks using the create_omp_tracks --audio-metrics CLI option
• Audio Waveform Analysis Tracks using the create_omp_tracks --waveforms CLI option
• Video Bitrate Analysis Tracks using the create_omp_tracks --video-bitrate CLI option
• Video Thumbnail Tracks using the create_omp_tracks --thumbnails CLI option

Usage create_omp_tracks.py --thumbnails

A thumbnail timeline metadata track and series of thumbnail images, can be generated with this option.

An input video file must be specified and the VTT and image files generated are written to the output directory specified.

The frequency of the thumbnails is controlled by the --seconds-interval CLI option.

usage: create_omp_tracks.py [-h] [-v] --thumbnails -i INPUT_FILE -o OUTPUT_DIR [-s {1,2,3,4,5,10,12,15}]

Create OMP thumbnail timeline metadata track.

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output
  -t, --thumbnails      Create thumbnail track
  -i INPUT_FILE, --input-file INPUT_FILE
                        Input file
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Output directory
  -s {1,2,3,4,5,10,12,15}, --seconds-interval {1,2,3,4,5,10,12,15}
                        Seconds between video bitrate samples or video thumbnails

Example - Thumbnail Timeline Metadata Track

WEBVTT

00:00:00.000 --> 00:00:01.999
tearsofsteel_4k00001.jpg

00:00:02.000 --> 00:00:03.999
tearsofsteel_4k00002.jpg

Usage create_omp_tracks.py --video-bitrate

A metadata track of the video bitrate can be generated with this option. The resulting metadata track can then be used to visualize the video bitrate as a line chart on the Omakase Player timeline.

usage: create_omp_tracks.py [-h] [-v] --video-bitrate -i INPUT_FILE -o OUTPUT_DIR [-s {1,2,3,4,5,10,12,15}]

Create OMP video bitrate metadata track.

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output
  -t, --video-bitrate   Create video bitrate track
  -i INPUT_FILE, --input-file INPUT_FILE
                        Input file
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Output directory
  -s {1,2,3,4,5,10,12,15}, --seconds-interval {1,2,3,4,5,10,12,15}
                        Seconds between video bitrate samples or video thumbnails

An input video file must be specified and the VTT and image files generated are written to the output directory specified.

The resolution of the bitrate samples is controlled by the --seconds-interval CLI option.

Example - Video Bitrate Metadata Track

WEBVTT

NOTE
Omakase Player Web VTT
V1.0

00:00:00.000 --> 00:00:01.999
276.39:MEASUREMENT=avg:COMMENT=2-sec interval

Please Note: The OMP v1.0 VTT file format is a standard WebVTT file with the following additional metadata:

• The :MEASUREMENT=<metric name> tag is optional and can be used to specify the video bitrate metric.
• The :COMMENT=<comment> tag is optional indicates the sample interval for the bitrate metric.

The optional tags are used by the Omakase Player to provide telemetry metadata for the video bitrate metric as the video is played.

Usage create_omp_tracks.py --audio-metrics

Audio metrics can be generated for an audio tracks, or all audio tracks, with this CLI option. At present, two audio metric metadata tracks are created for each audio file:

• RMS Levels using the ffmpeg ametadata filter
• R128 Momentary Loudness also using the ametadata filter

If --input-dir is used, all of the wav and aac files in the current directory are processed. If --input-file is used, only the audio file specified is processed.

The resulting metadata tracks are named with the basename of the audio file and appended with R128_2-SEC or RMS_2-SEC respectively. All files are written to the directory specified with --output-dir.

At present, the metrics are calculated as an average over a two-second interval.

usage: create_omp_tracks.py [-h] [-v] --audio-metrics (-i INPUT_FILE | -d INPUT_DIR) -o OUTPUT_DIR

Create OMP audio metric metadata tracks.

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output
  -t, --video-bitrate   Create video bitrate track
  -i INPUT_FILE, --input-file INPUT_FILE
                        Input file
  -d INPUT_DIR, --input-dir INPUT_DIR
                        Input directory of files
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Output directory

Example - Audio Metrics Metadata Track

WEBVTT

NOTE
Omakase Player Web VTT
V1.0

00:00:00.000 --> 00:00:01.999
-56.033:MEASUREMENT=lavfi.r128.M:COMMENT=2-sec avg

Please Note: The OMP v1.0 VTT file format is a standard WebVTT file with the following additional metadata:

• The :MEASUREMENT=<metric name> tag is optional and can be used to specify the audio metric type.
• The :COMMENT=<comment> tag is optional and can be used to provide additional information about the audio metric.

The optional tags are used by the Omakase Player to provide telemetry metadata for the audio metric as the video is played.

Usage create_omp_tracks.py --waveforms

The --waveforms option generates audio waveform metadata tracks that can be used to provide an audio waveform visualization in Omakase Player.

Waveform metadata can be generated for a single audio track, or all audio tracks, with this CLI option. The generated waveform includes the entire soundfield, but individual channels can be visualized with a dual-mono audio track for each channel.

If --input-dir is used, all of the wav and aac files in the current directory are processed. If --input-file is used, only the audio file specified is processed.

The resulting metadata tracks are named with the basename of the audio file All files are written to the directory specified with --output-dir.

At present, the metrics are calculated as an average over a 1-second interval.

usage: create_omp_tracks.py [-h] [-v] --waveforms (-i INPUT_FILE | -d INPUT_DIR) -o OUTPUT_DIR

Create OMP audio waveform metadata tracks.

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output
  -t, --video-bitrate   Create video bitrate track
  -i INPUT_FILE, --input-file INPUT_FILE
                        Input file
  -d INPUT_DIR, --input-dir INPUT_DIR
                        Input directory of files
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Output directory

Example - Audio Waveform Metadata Track

WEBVTT
  
00:00:00.000 --> 00:00:00.999
-0.0101, 0.0108

External Links

---

• Omakase Player Project Page
• Omakase Player GitHub Repository
• ffmpeg Project Page
• ffmpeg-bitrate-stats GitHub Repository
• audiowaveform Project Page
• audiowaveform GitHub Repository## License

License

---

create_omp_tracks.py, Copyright 2024 ByOmakase, LLC (https://byomakase.org)