Skip to content

MPEG H UI manager example

Jump to bottom
ameci-iis edited this page Feb 3, 2025 · 3 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, in the format '[<frame number>] <Audio Scene XML>' where <frame number> is the frame number at which the <Audio Scene XML> is first applied.

-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.

NOTE: The contents of this file influence the UI manager behavior.

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