-
Notifications
You must be signed in to change notification settings - Fork 7
MPEG H UI manager example
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)
- [optional] shows handling for the persistence cache (see
![](img_uim_example.png)
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
$ 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.
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
<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°
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:
- visit www.mpegh.com to get further test material and information about Fraunhofer MPEG-H trademark program .
- create your own test content using the MPEG-H Authoring Suite.
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
- 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.