Skip to content

MPEG H UI manager example

Jump to bottom
ameci-iis edited this page Jun 21, 2024 · 2 revisions

About

The mpeghdec repository provides a command-line program as an example for MPEG-H UI manager handling implementation.

The example program:

  • takes an MP4 file, containing an MPEG-H audio track, as input and extracts the MPEG-H Audio frames from MP4 file format (using the mmtisobmff project)
  • processes each extracted MPEG-H Audio frame with the MPEG-H UI manager component:
    • to extract and print the Audio Scene Configuration (AudioSceneConfiguration XML message) → see MPEG-H UI manager XML format definition
    • [optional] to store the AudioSceneConfiguration XML message to a file (see xmlSceneState option)
    • [optional] to insert the User Interactions (ActionEvent XML messages as defined in MPEG-H UI manager XML format ) based on the input interactivity script (see script option)
  • stores the processed MPEG-H Audio frames (incl. the MPEG-H UI packets) into an MP4 file
    • [optional] shows handling for the persistence cache (see persistFile option)

How to build

To build the MPEG-H UI manager command-line example program set mpeghdec_BUILD_BINARIES variable while configuring the project using CMake :

$ cmake -S mpeghdec -B build -DCMAKE_BUILD_TYPE=Release -Dmpeghdec_BUILD_BINARIES=ON

Read build instructions to learn how to configure and build the project

If build process is successfully finished, the MPEG-H decoder command-line tool mpeghUiManager can be found:

  • in the build/bin folder
  • in the build/bin/Release folder on Windows

Usage

$ build/bin/mpeghUiManager -if <path to input file> -of <path to output file> [options]

-if <path to input file>

<path to input file> : relative or absolute path to an input MP4 file containing an MPEG-H audio track (MHM1 format) to decode.

-of <path to output file>

<path to output file> : relative or absolute path to the output MP4 file which will contain the processed MPEG-H data.

Options are:

-script <path to interactivity script>

<path to interactivity script> : if provided the mpeghUiManager will apply the ActionEvent messages defined by this script. See below the definition of the interactivity script.

-xmlSceneState <path to output file>

<path to output file> : relative or absolute path to an output file which will contain the extracted AudioSceneConfiguration XML message.

-persistFile <path to persistence file>

<path to persistence file> : relative or absolute path to a file which will be used by mpeghUiManager to load and store the persistence cache of the MPEG-H UI manager.

Interactivity script

The interactivity script will be used by the mpeghUiManager example program to simulate user interactions.

Each line of the interactivity script contains:

  • either <Sleep Frame="X">
    • defining at which MPEG-H Audio frame number X the mpeghUiManager will apply the following ActionEvent XML message(s)
  • or predefined ActionEvent XML message(s) as defined in MPEG-H UI manager XML format

Example

<ActionEvent uuid="00000000-0000-0000-0000-000000000000" version="11.0" actionType="70" paramText="ger" paramInt="0" />
<Sleep Frame="100">
<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="11.0" actionType="30" paramInt="3" />
<Sleep Frame="130">
<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="11.0" actionType="41" paramInt="1" paramFloat="-6.0" />
<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="11.0" actionType="42" paramInt="2" paramFloat="160.0" />

In this interactivity script example the mpeghUiManager will:

  • apply the action event command at line #1 before processing the first MPEG-H Audio frame
    • this action event command will set the preferred audio language in MPEG-H UI manager to German language
  • skip 100 MPEG-H Audio frames before to apply the action event command at line #3
    • the action event in line #3 will select the preset defined by preset ID 3
  • skip the next 30 MPEG-H Audio frames before applying the lines #5 and #6
    • the action event in line #5 will set the prominence level of an audio element with ID 1 to -6 dB
    • the action event in line #6 will set the azimuth position of an audio element with ID 2 to 160°

Testing

To test the MPEG-H UI manager handling with the provided command-line program example or with your own implementation please use test material from the test content repository.

Additionally you can:

Example to test MPEG-H UI manager handling for the file provided in test content repository:

$ build/bin/mpeghUiManager -if TRI_Fileset_17_514H_D1_D2_D3_O1_24bit2160p50.audio.mp4 -of out.mp4 -script action_event_test_script.txt

Example above:

  • takes the TRI_Fileset_17_514H_D1_D2_D3_O1_24bit2160p50.audio.mp4 test item as input
  • takes the interactivity script from action_event_test_script.txt file download the example script here
  • writes the processed MPEG-H Audio bitstream, now containing inserted MPEG-H UI packets, into out.mp4 file

NOTE: use the MPEG-H decoder command-line example program mpeghDecoder to decode input and output files to verify the applied MPEG-H interactivity

Remarks

  • Only the first MPEG-H Audio track (MHM1 format) will be processed, other MPEG-H Audio tracks will be ignored/skipped.
  • Other tracks than MPEG-H Audio track (MHM1 format) will be ignored/skipped.
Clone this wiki locally