Skip to content

MPEG H UI manager XML format (deprecated V9.0)

Jump to bottom
ameci-iis edited this page Jun 21, 2024 · 1 revision

Warning

This MPEG-H UI XML format version is deprecated for mpeghdec release > r1.0.0.

Glossary

Term

Explanation
ASI Audio Scene Information; a technical term (AudioSceneInfo) related to MAE/Metadata Audio Elements. The term is described in chapter 15 (page 301 et seqq.) of the MPEG-H standard. An ASI will for example describe the audio objects available, including their properties.
MPEG-H

ISO/IEC 23008 - High Efficiency Coding and Media Delivery in Heterogeneous Environments; formal title of a group of standards under development by the ISO/IEC Moving Picture Experts Group (MPEG) including but not limited to

  • MPEG media transport
  • High Efficiency Video Coding
  • 3D Audio

This document refers to MPEG-H Part 3 whenever the "MPEG-H" word is used in this document.
UI User Interface
GUI Graphical User Interface
XML Extensible Markup Language
UUID Universally Unique Identifier
DRC Dynamic Range Control

Introduction and scope of this specification

The MPEG-H audio standard provides a user side control of the decoded audio scene: MPEG-H interactivity. The MPEG-H interactivity allows the user to control the following parts of the MPEG-H decoding process:

  • Preset selection
  • Selection of an audio object
  • Prominence level control of an audio object
  • Position control of an audio object
  • Selection of preferred audio language
  • Selection of preferred label language
  • Selection of device category
  • Selection of accessibility mode
  • Selection of DRC effect/gains
  • Selection of Album mode

To learn about the MPEG-H interactivity feature and MPEG-H UI manager component, please read the following documentations:

This document describes the XML based interface of the MPEG-H UI manager component.

MPEG-H UI manager XML interface

The UI manager provides a simple two-way XML https://www.w3.org/XML/ interface: 

  • to describe the Audio Scene Configuration to be used for MPEG-H UI renderer implementation
  • to describe the format of user settings, also called user interaction events
  • to describe the format of the system settings
    • please note that the system settings and user settings share the same XML message format.

NOTE: XML output message from MPEG-H UI manager called "AudioSceneConfig"

NOTE: XML input message to MPEG-H UI manager called "ActionEvent"

UUID (Content ID)

Both, AudioSceneConfig XML and ActionEvent XML messages, contain a mandatory @uuid attribute, describing the relation of the XML messages to an associated bitstream content (content ID).

All generated AudioSceneConfig XML messages will contain this attribute to allow the MPEG-H UI renderer implementation to uniquely address the corresponding ActionEvent messages. 

The format of the @uuid attribute is based on GUID type:

<xs:simpleType name="guid">
  <xs:restriction base="xs:string">
     <xs:pattern value="(\[0-9a-fA-F\])\{8\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{12\}"/>
  </xs:restriction>
</xs:simpleType>

The MPEG-H UI manager generates the current content ID (@uuid attribute value) based on the content metadata (ASI ID) which uniquely defines a corresponding content. This metadata is generated during MPEG-H authoring. 

The MPEG-H UI manager defines a special UUID (@uuid == 00000000-0000-0000-0000-000000000000) to be used in the ActionEvent XML message to set the MPEG-H UI manager system settings like the preferred audio language.

NOTE: the MPEG-H UI manager accepts only the ActionEvents messages with the same @uuid as the current processed content ID inside of MPEG-H UI manager context. All other ActionEvent messages, except system settings (@uuid == 00000000-0000-0000-0000-000000000000), will be interpreted as delayed delivered ActionEvent messages and will be ignored.

ActionEvent XML message

The ActionEvent XML message can be used to trigger an interactivity related task in the MPEG-H UI manager: 

  • Preset selection
  • Changing the prominence level / position of an audio element
  • Selection of an audio element from an audio element switch group
  • Changing the prominence level / position of an audio element switch group
  • Selection whether an audio element or audio element switch group is muted
  • Preferred audio language selection
  • Preferred label language selection
  • Device category selection
  • Selection of accessibility mode
  • Selection of a DRC effect
  • Selection of an Album mode

The ActionEvent XML message has a simple structure:

<xs:element name="ActionEvent">
   <xs:complexType>
      <xs:attribute name="uuid" type="xs:ID" use="required"/>
      <xs:attribute name="version" use="required" fixed="9.0"/>
      <xs:attribute name="actionType" type="xs:int" use="required"/>
      <xs:attribute name="paramInt" type="xs:int"/>
      <xs:attribute name="paramFloat" type="xs:decimal"/>
      <xs:attribute name="paramText" type="xs:string"/>
      <xs:attribute name="paramBool" type="xs:boolean"/>
   </xs:complexType>
</xs:element>

XSD element/attribute

Description
@uuid

unique identifier (see "UUID / Content ID")
@version version of XML interface
@actionType desired UI manager command
@paramInt optional integer parameter of an action request
@paramFloat optional float parameter of an action request
@paramText optional text parameter of an action request
@paramBool optional boolean parameter of an action request

NOTE: the @paramInt, @paramFloat, @paramText and @paramBool attributes are optional. The appearance of these attributes depends on the corresponding @actionType command. See the table below

Following table defines all allowed MPEG-H UI manager commands: 

Action type ID

Action type name

Is system setting?

Required parameters

Description
0 IIS_UIM_CMD_RESET yes not required

Request to reset the AudioScene XML configuration of the current bitstream to default state (see "Reset")
10 IIS_UIM_CMD_DRC_SELECTED yes paramInt

Selection of DRC effect (see "Selection of DRC effect")
11 IIS_UIM_CMD_DRC_BOOST yes paramFloat

Scaling factor for amplifying DRC gains (see "Scaling of DRC gains")
12 IIS_UIM_CMD_DRC_COMPRESS yes paramFloat

Scaling factor for attenuating DRC gains (see "Scaling of DRC gains")
20 IIS_UIM_CMD_TARGET_LOUDNESS yes paramFloat

Desired target loudness (see "Device category selection")
21 IIS_UIM_CMD_ALBUM_MODE yes paramBool

Selection of Album mode (see "Selection of Album Mode")
30 IIS_UIM_CMD_PRESET_SELECTED yes paramInt

Preset selection (see "AudioSceneConfig::Preset")
31 IIS_UIM_CMD_ACCESSIBILITY_PREFERENCE yes paramInt

Selection of accessibility mode (see "Selection of accessibility mode")
40 IIS_UIM_CMD_AUDIO_ELEMENT_MUTING_CHANGED no paramInt, paramBool Muting of an audio element
41 IIS_UIM_CMD_AUDIO_ELEMENT_PROMINENCE_LEVEL_CHANGED no paramInt, paramFloat Prominence level change of an audio element
42 IIS_UIM_CMD_AUDIO_ELEMENT_AZIMUTH_CHANGED no paramInt, paramFloat Azimuth position change of an audio element
43 IIS_UIM_CMD_AUDIO_ELEMENT_ELEVATION_CHANGED no paramInt, paramFloat Elevation position change of an audio element
60 IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_SELECTED no paramInt, paramFloat Selection of an audio element from an audio element switch group
61 IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_MUTING_CHANGED no paramInt, paramBool Muting of an audio element switch group
62 IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_PROMINENCE_LEVEL_CHANGED no paramInt, paramFloat Prominence level change of an audio element switch group
63 IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_AZIMUTH_CHANGED no paramInt, paramFloat Azimuth position change of an audio element switch group
64 IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_ELEVATION_CHANGED no paramInt, paramFloat Elevation position change of an audio element switch group
70 IIS_UIM_CMD_AUDIO_LANGUAGE_SELECTED yes paramText, paramInt Selection of preferred audio language
71 IIS_UIM_CMD_INTERFACE_LANGUAGE_SELECTED yes paramText, paramInt Selection of preferred label language
90 IIS_UIM_CMD_SET_GUID not required Set unique identifier of the current content

NOTE: Any ActionEvent XML message with an @actionType value, not defined in this table, will be ignored. 

NOTE: If the action type ID is marked as a system setting in the table above, the @uuid attribute value in the ActionEvent XML message must be set to 00000000-0000-0000-0000-000000000000

AudioSceneConfig XML message

The AudioSceneConfig XML message contains all necessary information required for MPEG-H UI renderer implementation. The MPEG-H UI manager generates the AudioSceneConfig XML message from the processed MPEG-H bitstream (Audio Scene Information metadata).

The structure of the AudioSceneConfig XML message is presented in the following UML diagram:

img_ui_xml_uml_v9.0.png

The MPEG-H UI manager will provide an AudioSceneConfig XML message if:

  • MPEG-H Audio bitstream will contain a new audio scene definition -> MPEG-H config change
  • a preset is selected by the user -> this will trigger to generate a new AudioSceneConfig XML message, since the AudioSceneConfig XML message always reflects the current rendered audio scene which depends on the currently selected preset.
  • IIS_UIM_CMD_RESET action event was triggered -> the audio scene will be reset to the default state
  • preferred audio language was changed using the IIS_UIM_CMD_AUDIO_LANGUAGE_SELECTED action event
  • preferred label language was changed using the IIS_UIM_CMD_INTERFACE_LANGUAGE_SELECTED action event.
    • NOTE: The new AudioSceneConfig XML message is not immediately available if the MPEG-H UI manager doesn't cache labels for all languages. In this case the new AudioSceneConfig XML message will be available as soon as the next ASI metadata (MHAS ASI packet) will be repeated in the bitstream.

AudioSceneConfig root element

The AudioSceneConfig root element contains: 

  • list of available DRC effects
  • description of available presets
  • list of audio elements
  • list of audio element switch groups

The AudioSceneConfig XML message structure of the first layer is defined as followed:

<xs:element name="AudioSceneConfig">
   <xs:annotation>
      <xs:documentation>audio scene content description</xs:documentation>
   </xs:annotation>
   <xs:complexType>
      <xs:sequence minOccurs="0" maxOccurs="1">
         <xs:element name="DRCInfo" type="DRCInfo"/>
         <xs:element name="presets">
            <xs:complexType>
               <xs:sequence>
                  <xs:element name="preset" type="Preset" minOccurs="0" maxOccurs="unbounded"/>
               </xs:sequence>
            </xs:complexType>
         </xs:element>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element name="audioElement" type="AudioElement"/>
            <xs:element name="audioElementSwitch" type="AudioElementSwitch"/>
         </xs:choice>
      </xs:sequence>
      <xs:attribute name="uuid" type="guid" use="required"/>
      <xs:attribute name="version" use="required" fixed="9.0"/>
      <xs:attribute name="configChanged" type="xs:boolean" use="required" />
   </xs:complexType>
</xs:element>

XSD element/attribute

Description
@uuid

unique ID (see "UUID / Content ID") shall be used in associated ActionEvent messages
@version version of XML interface
@configChanged Indicates that a config change was recognized
DRCInfo

List of available DRC effects (see "Selection of DRC effect")
presets

List of presets (see "AudioSceneConfig::Preset")
audioElement Single audio element
audioElementSwitch Group of audio elements

Config change

If the MPEG-H UI manager recognizes a configuration change in the MPEG-H Audio bitstream, the MPEG-H UI manager generates an AudioSceneConfig XML message, containing configChanged="true" parameter to indicate a new configuration. This can be used by the system to perform some customer-specific system setting logic.

XML example:

<AudioSceneConfig uuid="12345678-1234-1234-1234-123456789012" version="9.0" configChanged="true" />

NOTE: An AudioSceneConfig XML message, containing configChanged="true" parameter, does not contain a valid configuration. Only the uuid attribute value shall be used if required. 

Label description

The MPEG-H UI manager XML interface provides two options to describe the labels to be presented in MPEG-H UI renderer:

  • Custom label description
  • Table based label description

Custom label description

The "custom label" is a broadcaster-defined description for the labels. 

The structure of the description XML element is defined as followed:

<xs:complexType name="CustomDescriptor">
   <xs:sequence>
      <xs:element name="description" type="LocalizedString" maxOccurs="unbounded"/>
   </xs:sequence>
</xs:complexType>
<xs:simpleType name="ISO639-2_3-letter-code">
   <xs:restriction base="xs:string">
      <xs:pattern value="\[a-z\]\[a-z\]\[a-z\]"/>
   </xs:restriction>
</xs:simpleType>
<xs:complexType name="LocalizedString">
   <xs:simpleContent>
      <xs:extension base="xs:string">
         <xs:attribute name="langCode" type="ISO639-2_3-letter-code" use="required"/>
      </xs:extension>
   </xs:simpleContent>
</xs:complexType>

Each preset element, audio element or audio element switch group can contain multi-lingual definitions for a custom label. The @langCode attribute of the "description" XML element defines the corresponding 3-letter language code (iso639-2). 

The MPEG-H UI manager allows the selection of a preferred language for the labels (see "Preferred audio language").

XML example:

...
<description langCode="eng">Stadium</description>
<description langCode="spa">Estadio</description>
<description langCode="ger">Stadion</description>
...

Table-based label description

The table-based label description concept allows instead of the multi-lingual description of an UI element to refer to an entry of predefined description tables. The MPEG-H UI renderer implementation will need to lookup in the local dictionary to translate the description code to the description label for the used language.

Definition

All label description tables in AudioSceneConfig are based on the AudioSceneConfig::AbstractTable:

<xs:complexType name="AbstractTable">
   <xs:attribute name="code" use="required">
      <xs:simpleType>
         <xs:restriction base="xs:unsignedByte">
            <xs:minInclusive value="0"/>
            <xs:maxInclusive value="255"/>
         </xs:restriction>
      </xs:simpleType>
   </xs:attribute>
   <xs:attribute name="alias" type="xs:string"/>
</xs:complexType>

XSD element/attribute

Description
code table entry ID
alias Optional human readable alias for the table entry ID

Additionally to the attributes defined by the AudioSceneConfig::AbstractTable type, each table also contains a fixed table name:

<xs:complexType name="SomeTable">
   <xs:complexContent>
      <xs:extension base="AbstractTable">
         <xs:attribute name="table" type="xs:string" use="required" fixed="SomeTable"/>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

An example of usage of a predefined table:

...
<someLabel table="SomeTable" code="5" >
...

MPEG-H UI manager XML format defines following tables:

  • Content kind table
    • table = "ContentKindTable"
    • to indicate the type of the audio element or audio element switch group
  • Preset kind table
    • table = "PresetTable"
    • e.g. to indicate the accessibility information of a preset
  • Switch kind table
    • table ="SwitchKindTable"

ContentKindTable definition

This table is based on the MPEG-H mae_contentKind table1

Table code

Description
0 undefined
1 complete main
2 dialogue
3 music
4 effect
5 mixed
6 LFE
7 voiceover
8 spokensubtitle
9 audiodescription/visually impaired
10 commentary
11 hearing impaired
12 emergency
13-255

Reserved for future use

PresetTable definition

This table is based on the MPEG-H mae_groupPresetKind table1

Table code

Description
0 undefined
1 integrated TV loudspeaker
2 high quality loudspeaker
3 mobile speakers
4 mobile headphones
5 hearing impaired (light)
6 hearing impaired (heavy)
7 visually impaired / audio description
8 spoken subtitles
9 loudness/DRC
10-255

Reserved for future use

SwitchKindTable definition

Table code

Description
0 undefined
1-255

Reserved for future use

AudioSceneConfig::DRCInfo

This XML element of the AudioSceneConfig provides a list of the available DRC effects for the currently processed MPEG-H Audio content:

<xs:complexType name="DRCInfo">
   <xs:sequence minOccurs="0" maxOccurs="16">
      <xs:element name="drcSetEffectAvailable">
         <xs:complexType>
            <xs:attribute name="index" type="xs:unsignedInt" use="required"/>
         </xs:complexType>
      </xs:element>
   </xs:sequence>
</xs:complexType>

XML example:

<AudioSceneConfig ...
   ...
   <DRCInfo>
      <drcSetEffectAvailable index="0"/>
      <drcSetEffectAvailable index="1"/>
      <drcSetEffectAvailable index="5"/>
   </DRCInfo>
   ...
</AudioSceneConfig>

See "Dynamic Range Control (DRC)" to get detailed information about MPEG-H DRC control. 

AudioSceneConfig::Preset

Definition

This part of the AudioSceneConfig contains collected information of an MPEG-H preset. If multiple presets are defined in the received MPEG-H Audio bitstream the AudioSceneConfig XML message will contain a list of AudioSceneConfig::Preset elements.

Each preset contains following information:

<xs:complexType name="Preset">
   <xs:sequence>
      <xs:element name="kind" type="PresetTable" minOccurs="0"/>
      <xs:element name="customKind" type="CustomDescriptor" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="id" type="xs:int" use="required"/>
   <xs:attribute name="isActive" type="xs:boolean" use="required"/>
   <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
   <xs:attribute name="isDefault" type="xs:boolean" use="required"/>
</xs:complexType>

XSD element/attribute

Description
id Preset ID [shall be used in the associated UI event]
isActive

Defines whether this preset is currently applied

NOTE: the MPEG-H UI renderer shall mark the active preset as selected
isAvailable

Defines whether this preset is currently available for selection

NOTE: the MPEG-H UI renderer shall mark an unavailable preset as unselectable
isDefault Defines whether this preset is the default one
kind Kind of preset
customKind Kind of preset defined as custom text representation

Example

XML example:

...
<preset id="1" isActive="true" isAvailable="true" isDefault="false">
  <customKind>
     <description langCode="eng">Broadcast</description>
   </customKind>
</preset>
<preset id="2" isActive="false" isAvailable="true" isDefault="true">
   <customKind>
     <description langCode="eng">Live</description>
   </customKind>
</preset>
<preset id="3" isActive="false" isAvailable="true" isDefault="false">
   <customKind>
     <description langCode="eng">Teamradio</description>
   </customKind>
</preset>
...

The XML example above describes an audio scene where 3 presets are defined by the bitstream metadata:

  • preset 1 is labeled as "Broadcast" and is currently active
  • preset 2 is labeled as "Live" and is defined to be the default preset
  • preset 3 is labeled as "Teamradio" 

MPEG-H UI renderer example:

ActionEvent

The associated ActionEvent XML message parameter: 

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType = 30 [IIS_UIM_CMD_PRESET_SELECTED]
paramInt ID of the selected preset

NOTE: The selection of a preset triggers the generation of a new AudioSceneConfig XML message after the MPEG-H UI manager performs the preset selection 

ActionEvent XML message example to select the "Teamradio" preset from the above example:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="30" paramInt="3" />

Properties of AudioSceneConfig::audioElement and AudioSceneConfig::audioElementSwitch

An audio element and an audio element switch group can contain the following properties: 

  • Prominence level property
  • Muting property
  • Azimuth property
  • Elevation property

Each property contains property-related parameters and the following common parameter:

<xs:complexType name="PropertyCommon">
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>

PropertyCommon parameter

Description
isActionAllowed If false, the User is not allowed to perform interactivity on this property type

AudioSceneConfig::ProminenceLevelProperty

Definition

The prominence level property describes all parameters related to the gain control of an audio element or an audio element switch group in relation to the complete audio scene. If the prominence level is changed, the MPEG-H decoder also adjusts the gains of all other audio elements, so that the overall loudness of the audio scene stays constant.

ui_xml_prominence_handling.png

The maximal allowed range prominence level is between -63 dB and 31 dB. A broadcaster can limit the allowed range by definition of min/max values for each audio element or audio element switch group.

NOTE: The prominence level of -63 dB for an audio element or audio element switch group will be mapped to -infinity dB in the MPEG-H decoder as defined in ISO/IEC 23008-3:2022

Prominence level property definition:

<xs:complexType name="PropertyCommon">
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>
<xs:complexType name="ProminenceLevelProperty">
   <xs:complexContent>
      <xs:extension base="PropertyCommon">
         <xs:attribute name="min" type="xs:decimal" use="required"/>
         <xs:attribute name="max" type="xs:decimal" use="required"/>
         <xs:attribute name="val" type="xs:decimal" use="required"/>
         <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

XSD element/attribute

Description
isActionAllowed If false, the User is not allowed to perform interactivity on this property type
min minimal allowed prominence level in dB
max maximal allowed prominence level in dB
val current prominence level in dB
def default prominence level in dB

RECOMMENDATION: If the isActionAllowed parameter is set to "false" the MPEG-H renderer shall mark a used UI element for the prominence level as inactive or shall not render this UI element for the related audio element or audio element switch group. 

Example

XML example:

...
<prominenceLevelProp isActionAllowed="true" min="-20.0" max="12.0" val="0.0" def="0.0" />
...

The XML example above defines the prominence property of an audio element or an audio element switch group with following conditions:

  • the User is allowed to change the currently set prominence value
  • the allowed range is from -20 dB to 12 dB
  • the currently set value is 0 dB
  • the defined default value is 0 dB

MPEG-H UI renderer example:

ActionEvent

The associated ActionEvent XML message parameter: 

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType

= 41 [IIS_UIM_CMD_AUDIO_ELEMENT_PROMINENCE_LEVEL_CHANGED]

or

= 62 [IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_PROMINENCE_LEVEL_CHANGED]
paramInt ID of the corresponding audio element or audio element switch group
paramFloat prominence level to set in dB

ActionEvent example to set the prominence level for the audio element with id 1 to -6.0 dB:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="41" paramInt="1" paramFloat="-6.0" />

AudioSceneConfig::MutingProperty

Defintion

The muting property describes parameters related to muting control of an audio element or an audio element switch group

Muting property definition:

<xs:complexType name="PropertyCommon">
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>
<xs:complexType name="MutingProperty">
   <xs:complexContent>
      <xs:extension base="PropertyCommon">
         <xs:attribute name="val" type="xs:boolean" use="required"/>
         <xs:attribute name="def" type="xs:boolean" use="required"/>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

XSD element/attribute

Description
isActionAllowed If false, the User is not allowed to perform interactivity on this property type
val

current muting state

if true then an audio element or an audio element switch group is muted
def default muting state

Example

XML example:

...
<mutingProp isActionAllowed="true" val="true" def="false" />
...

The XML example above defines the muting property of an audio element or an audio element switch group with following conditions:

  • the User is allowed to mute and unmute the associated audio element or an audio element switch group
  • the current state is muted
  • the defined default state is unmuted

ActionEvent

The associated ActionEvent XML message parameter: 

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType

= 40 [IIS_UIM_CMD _AUDIO_ELEMENT_MUTING_CHANGED]

or

= 61 [IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_MUTING_CHANGED]
paramInt ID of the corresponding audio element or audio element switch group
paramBool

= true to mute

= false to unmute

ActionEvent example to mute the audio element with id 1:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="40" paramInt="1" paramBool="true" />

AudioSceneConfig::AzimuthProperty

Defintion

ui_xml_azimuth.png

The AzimuthProperty allows the azimuth positioning of an audio element or an audio element switch group within the maximal allowed azimuth range between -180° and 180° as defined in ISO/IEC 23008-3:2022. A broadcaster can limit the allowed azimuth range by definition of min/max values for each audio element or audio element switch group.

Azimuth property definition:

<xs:complexType name="PropertyCommon">
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>
<xs:complexType name="AzimuthProperty">
   <xs:complexContent>
      <xs:extension base="PropertyCommon">
         <xs:attribute name="min" type="xs:decimal" use="required"/>
         <xs:attribute name="max" type="xs:decimal" use="required"/>
         <xs:attribute name="val" type="xs:decimal" use="required"/>
         <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

XSD element/attribute

Description
isActionAllowed If false, the User is not allowed to perform interactivity on this property type
min rightmost position in degree
max leftmost position in degree
val current position in degree
def default position in degree
Example

XML example:

...
<azimuthProp isActionAllowed="true" min="-160.0" max="160.0" val="0.0" def="0.0" />
...

The XML example above defines the azimuth property of an audio element or an audio element switch group with following conditions:

  • the User is allowed to change the azimuth position of the associated audio element or audio element switch group
  • the allowed range is between -160° and 160°
  • the current position is set to 0°
  • the defined default position is 0°

MPEG-H UI renderer example:

ActionEvent

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType

= 42 [IIS_UIM_CMD_AUDIO_ELEMENT_AZIMUTH_CHANGED]

or

= 63 [IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_AZIMUTH_CHANGED]
paramInt ID of the corresponding audio element or audio element switch group
paramFloat azimuth degree to set

ActionEvent example to set the azimuth position of the audio element with id 1 to 160° degree:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="42" paramInt="1" paramFloat="160.0" />

AudioSceneConfig::ElevationProperty

Definition

ui_xml_elevation.png

The ElevationProperty allows the elevation positioning of an audio element or an audio element switch group within the maximal allowed elevation range between -90° and 90° as defined in ISO/IEC 23008-3:2022. A broadcaster can limit the allowed elevation range by definition of min/max values for each audio element or audio element switch group.

Elevation property definition:

<xs:complexType name="PropertyCommon">
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>
<xs:complexType name="ElevationProperty">
   <xs:complexContent>
      <xs:extension base="PropertyCommon">
         <xs:attribute name="min" type="xs:decimal" use="required"/>
         <xs:attribute name="max" type="xs:decimal" use="required"/>
         <xs:attribute name="val" type="xs:decimal" use="required"/>
         <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

XSD element/attribute

Description
isActionAllowed If false, the User is not allowed to perform interactivity on this property type
min lowermost position in degree
max uppermost position in degree
val current position in degree
def default position in degree

Example

XML example:

...
<elevationProp isActionAllowed="true" min="0.0" max="60.0" val="45.0" def="45.0" />
...

The XML example above defines the elevation property of an audio element or an audio element switch group with following conditions:

  • the User is allowed to change the elevation position of the associated audio element or an audio element switch group
  • the allowed range is between 0° and 60°
  • the current position is set to 45°
  • the defined default position is 45°

MPEG-H UI renderer example:

ActionEvent

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType

= 43 [IIS_UIM_CMD_AUDIO_ELEMENT_ELEVATION_CHANGED]

or

= 64 [IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_ELEVATION_CHANGED]
paramInt ID of the corresponding audio element or audio element switch group
paramFloat elevation degree to set

ActionEvent example to set the elevation position of the audio element with id 1 to 45° degree:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="43" paramInt="1" paramFloat="45.0" />

AudioSceneConfig::audioElement

Defintion

This part of the audio scene configuration describes all parameters related to an audio element: 

  • Audio element availability
  • Prominence level property
  • Muting property
  • Azimuth property
  • Elevation property

Each audio element contains the following information: 

<xs:complexType name="AudioElement">
   <xs:sequence>
      <xs:element name="prominenceLevelProp" type="ProminenceLevelProperty" minOccurs="0"/>
      <xs:element name="mutingProp" type="MutingProperty" minOccurs="0"/>
      <xs:element name="azimuthProp" type="AzimuthProperty" minOccurs="0"/>
      <xs:element name="elevationProp" type="ElevationProperty" minOccurs="0"/>
      <xs:element name="kind" type="AudioElementKind" minOccurs="0"/>
      <xs:element name="customKind" type="CustomAudioElementKind" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="id" type="xs:int" use="required"/>
   <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
</xs:complexType>

XSD element/attribute

Description
id

audio element ID

will be used in the associated ActionEvent XML messages
isAvailable

defines whether this audio element is currently available.

NOTE: If an audio element is not available the MPEG-H UI renderer shall not display any UI elements for the audio element and its properties or mark the audio element and its properties as currently unavailable.
prominenceLevelProp

Prominence level property (see "AudioSceneConfig::ProminenceLevelProperty")
mutingProp

Muting property (see "AudioSceneConfig::MutingProperty")
azimuthProp

Azimuth property (see "AudioSceneConfig::AzimuthProperty")
elevationProp

Elevation property (see "AudioSceneConfig::ElevationProperty")
kind Kind of audio element
customKind Kind of audio element defined as custom text representation

@langCode attribute in AudioSceneConfig::AudioElementKind and AudioSceneConfig::CustomAudioElementKind

The @langCode attribute of an audio element will be used to describe the language of the associated audio content. This information can be used by the MPEG-H UI renderer to visualize the language of the associated audio content: e.g. drawing a country flag 

Example

XML example of an audio element with prominence level and elevation properties:

...
<audioElement id="123" isAvailable="true">
   <prominenceLevelProp isActionAllowed="true" min="-20.0" max="12.0" val="-6.0" def="0.0" />
   <elevationProp isActionAllowed="true" min="0.0" max="60.0" val="45.0" def="0.0" />
   <customKind langCode="ger">
      <description langCode="ger">Kommentator</description>
      <description langCode="eng">Commentator</description>
      <description langCode="ita">Commentatore</description>
   </customKind>
</audioElement>
...

The XML example above defines an audio element with id = 123 and indicates that:

  • this audio element is available
  • the User can change the prominence level in the range from -20.0 dB to 12.0 dB
  • the currently set prominence value is -6.0 dB
  • the defined default value for prominence is 0.0 dB
  • the User can change the elevation position of this audio element by an elevation offset in the allowed range from 0° to 60°
  • the current elevation position is set to 45°
  • the defined default elevation position is 0°
  • the User is NOT allowed to mute/unmute this audio element
  • the User is NOT allowed to change the azimuth position of this audio element
  • the audio content of this audio element is in German language
  • this audio element is labeled:
    • in German as "Kommentator"
    • in English as "Commentator"
    • in Italian as "Commentatore"

MPEG-H UI renderer example:

ActionEvent

See ActionEvent of the corresponding audio element property:

  • ActionEvent for prominence property
  • ActionEvent for muting property
  • ActionEvent for azimuth property
  • ActionEvent for elevation property

AudioSceneConfig::audioElementSwitch

Definition

This part of AudioSceneConfig XML message describes all parameters related to an audio element switch group: 

  • audio element switch group availability
  • Audio element option list
  • Prominence level property
  • Muting property
  • Azimuth property
  • Elevation property

Each audio element switch group contains the following information:

<xs:complexType name="AudioElementSwitch">
   <xs:sequence>
      <xs:element name="prominenceLevelProp" type="ProminenceLevelProperty" minOccurs="0"/>
      <xs:element name="mutingProp" type="MutingProperty" minOccurs="0"/>
      <xs:element name="azimuthProp" type="AzimuthProperty" minOccurs="0"/>
      <xs:element name="elevationProp" type="ElevationProperty" minOccurs="0"/>
      <xs:element name="audioElements">
         <xs:complexType>
            <xs:sequence>
               <xs:element name="audioElement" type="AudioElementSwitchItem" maxOccurs="unbounded"/>
            </xs:sequence>
         </xs:complexType>
      </xs:element>
      <xs:element name="kind" type="SwitchKindTable" minOccurs="0"/>
      <xs:element name="customKind" type="CustomDescriptor" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="id" type="xs:int" use="required"/>
   <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
   <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
</xs:complexType>

XSD element/attribute

Description
id

audio element switch group ID

will be used in the associated ActionEvent XML messages
isAvailable

Defines whether this audio element switch group is currently available.

NOTE: If an audio element switch group is not available the MPEG-H UI renderer shall not display any UI elements for the audio element switch group and its properties or mark the audio element switch group and its properties as currently unavailable.
isActionAllowed If false, the User is not allowed to select an audio element item from the audio element option list
prominenceLevelProp

Prominence level property (see "AudioSceneConfig::ProminenceLevelProperty")
mutingProp

Muting property (see "AudioSceneConfig::MutingProperty")
azimuthProp

Azimuth property (see "AudioSceneConfig::AzimuthProperty")
elevationProp

Elevation property (see "AudioSceneConfig::ElevationProperty")
kind Kind of audio element switch group
customKind Kind of audio element switch group defined as custom text representation
audioElement List of audio elements options

audio element switch group option

Each audio element option in the audio element switch group contains the following information:

<xs:complexType name="AudioElementSwitchItem">
   <xs:sequence>
      <xs:element name="kind" type="AudioElementKind" minOccurs="0"/>
      <xs:element name="customKind" type="CustomAudioElementKind" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="id" type="xs:int" use="required"/>
   <xs:attribute name="isActive" type="xs:boolean" use="required"/>
   <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
   <xs:attribute name="isSelectable" type="xs:boolean" default="true"/>
   <xs:attribute name="isDefault" type="xs:boolean" use="required"/>
</xs:complexType>

XSD element/attribute

Description
id Option ID will be used in the associated ActionEvent XML
isAvailable

Defines whether this audio element switch group item is currently available.

NOTE: If an audio element switch group item is not available, the UI element associated with this audio element switch group item shall be marked as unavailable.
isSelectable

This attribute will be used to signalize that an audio element switch group item, if it is delivered in a secondary stream (hybrid delivery), can or cannot be retrieved. For the audio element switch group items in the main stream this attribute is always set to "true".

NOTE: If an audio element switch group item is not selectable, the MPEG-H UI renderer shall not allow to select such an element or shall not render the UI element for such an element.
isActive Defines whether this audio element option is currently selected
isDefault Defines whether this audio element option is default
kind Kind of audio element option
customKind Kind of audio element option defined as custom text representation

@langCode attribute in AudioSceneConfig::AudioElementKind and AudioSceneConfig::CustomAudioElementKind

The @langCode attribute of an audio element switch group or audio element switch group option will be used to describe the language of the associated audio content. This information can be used by the MPEG-H UI renderer to visualize the language of the associated audio content: e.g. drawing a country flag 

Example

XML example of an audio element switch group:

...
<audioElementSwitch id="123" isAvailable="true" isActionAllowed="true">
   <prominenceLevelProp isActionAllowed="true" min="-20.0" max="12.0" val="-6.0" def="0.0" />
   <mutingProp isActionAllowed="false" val="false" def="false" />
   <elevationProp isActionAllowed="true" min="0.0" max="60.0" val="45.0" def="0.0" />
   <audioElements>
      <audioElement id="20" isAvailable="true" isActive="true" isDefault="true" isSelectable="true">
         <customKind langCode="ger">
            <description langCode="ger">Deutsch</description>
            <description langCode="eng">German</description>
         </customKind>
      </audioElement>
      <audioElement id="21" isAvailable="true" isActive="false" isDefault="false" isSelectable="true">
         <customKind langCode="spa">
            <description langCode="ger">Spanisch</description>
            <description langCode="eng">Spanish</description>
         </customKind>
       </audioElement>
       <customKind>
          <description langCode="ger">Kommentator</description>
          <description langCode="eng">Commentator</description>
       </customKind>
   </audioElements>
</audioElementSwitch>
...

The XML example above defines an audio element switch group with id = 123 and indicates that:

  • this audio element switch group is available
  • the User can change the prominence level in the range from -20.0 dB to 12.0 dB
  • the currently set prominence value is -6.0 dB
  • the defined default value for prominence is 0.0 dB
  • the User can change the elevation position of this audio element switch group in the allowed range from 0° to 60°
  • the current elevation position is set to 45°
  • the defined default elevation position is 0°
  • the User is NOT allowed to mute/unmute this audio element (explicitly indicated in the AudioSceneConfig XML message)
  • the User is NOT allowed to change the azimuth position of this audio element
  • this audio element switch group is labeled:
    • in German as "Kommentator"
    • in English as "Commentator"
  • this audio element switch group contains the following audio element items:
    • audio element with id = 20 with the following information:
      • this audio element item is available
      • this audio element item is currently active (selected)
      • this audio element item is defined as the default option
      • this audio element item can be selected
      • the audio content of this audio element item is in German language
      • this audio element item is labeled:
        • in German as "Deutsch"
        • in English as "German"
    • audio element with id = 21 with the following information:
      • this audio element item is available
      • this audio element item is currently NOT active
      • this audio element item can be selected
      • the audio content of this audio element item is in Spanish language
      • this audio element item is labeled:
        • in German as "Spanisch"
        • in English as "Spanish"

MPEG-H UI renderer example:

ActionEvent

The action events of the audio element switch group properties (prominence level / muting / elevation / azimuth) are described in the corresponding property section.

The ActionEvent XML message for the audio element option selection contains:

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType = 60 [IIS_UIM_CMD_AUDIO_ELEMENT_SWITCH_SELECTED]
paramInt ID of the corresponding audio element switch group
paramFloat ID of the selected audio element option

ActionEvent example selection of Spanish language in the above configuration example:

<ActionEvent uuid="12345678-1234-1234-1234-123456789012" version="9.0" actionType="60" paramInt="123" paramFloat="21" />

Reset

The IIS_UIM_CMD_RESET command allows to reset the audio scene configuration of the current MPEG-H bitstream to the default state (selection of default preset).

The ActionEvent XML message for reset command contains:

ActionEvent parameter

Description
uuid Corresponding UUID of the AudioSceneConfig XML message
version = 9.0
actionType = 0 [IIS_UIM_CMD_RESET]

Preferred audio language

The MPEG-H UI manager provides a unique feature to automatically select a language from the available audio element dialogue options in the bitstream based on the user-preferred language selection. 

The ActionEvent XML message for the preferred audio language selection contains:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType = 70 [IIS_UIM_CMD_AUDIO_LANGUAGE_SELECTED]
paramText ISO639-2 3-letter-code
paramInt

Priority:

  • allowed value range from 0 to 9.
  • 0 means highest priority

NOTE: The priorities have to be set in ascending order without gaps

The MPEG-H UI manager interface allows for setting a list of preferred languages. The @paramInt attribute can be used to define the priority of the corresponding preferred language.

NOTE: A new "set preferred language" action event would rewrite an already set preferred language with the same priority value.

The following diagram shows the preferred language selection behavior:

It is recommended to provide the selection of the preferred language as a system setting:

Preferred label language

Similar to the preferred audio language, the MPEG-H UI manager provides a unique feature to automatically select a preferred language of the labels to be inserted to AudioSceneConfig XML message. The system framework or MPEG-H UI renderer component can request to select a particular label language from all available multi-lingual representations of a label in the bitstream.

NOTE: The availability of the selected preferred label language depends on the metadata of the processed MPEG-H Audio bitstream.  

The ActionEvent content:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType = 71 [IIS_UIM_CMD_INTERFACE_LANGUAGE_SELECTED]
paramText ISO639-2 3-letter-code
paramInt

Priority:

allowed value range from 0 to 9.

0 means highest priority

NOTE: The priorities have to be set in ascending order without gaps.

The MPEG-H UI manager interface allows for setting a list of preferred label languages. The @paramInt attribute can be used to define the priority of the corresponding preferred label language.

NOTE: A new "set preferred label language" action event would rewrite an already set preferred label language with the same priority value.

It is recommended to provide the selection of the preferred label language as a system setting. The selection of the preferred label language can be combined with the preferred audio language selection.

Device category selection

Dependent on the category of the playback device and the expected available dynamic range of a typical listening situation, a target loudness value is set at the MPEG-H decoder. 

For different playback device categories the following target loudness values are typical:

Device category

Available dynamic range

Target Loudness (LKFS)
AVR with high quality loudspeakers high dynamic range -31
TV with integrated speakers medium dynamic range -24
mobile device restricted dynamic range -16

If the playback device category is not fixed or unknown at the decoder, the MPEG-H UI Manager allows to override the playback device category using a system setting.

Example of device category selection menu:

To set the desired target loudness the ActionEvent XML message shall contain following information:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType = 20 [IIS_UIM_CMD_TARGET_LOUDNESS]
paramFloat

Target loudness in LKFS according to ITU-R BS.1770-4.

or special value -128

ActionEvent XML message example for target loudness configuration for TV device category:

<ActionEvent uuid="00000000-0000-0000-0000-000000000000" version="9.0" actionType="20" paramFloat="-24.0" />

Target loudness values are restricted to the range between -63 and -10 LKFS.

The special target loudness value of -128 is used for falling back to the target loudness that has been set at the decoder. This special value is the default value of the MPEG-H UI manager.

Selection of accessibility mode

The accessibility feature of the MPEG-H UI manager allows for automatic selection of an accessibility mode if this is available in a bitstream. 

The accessibility mode feature like a preferred audio language feature is a system preference and will be automatically applied after each config change or after a new accessibility mode is selected.

Supported accessibility modes:

ID

MODE

Description
0 NONE No accessibility mode will be applied.
1 VISUAL_IMPAIRED Visual impaired accessibility mode
2 LIGHT_HEARING_IMPAIRED Light hearing impaired accessibility mode
3 HEAVY_HEARING_IMPAIRED Heavy hearing impaired accessibility mode
4 VISUAL_HEARING_IMPAIRED Visual and hearing impaired accessibility mode

Example of accessibility mode selection menu:

The ActionEvent XML message contains:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType = 31 [IIS_UIM_CMD_ACCESSIBILITY_PREFERENCE]
paramInt Accessibility mode ID (see table above)

Dynamic Range Control (DRC)

Selection of DRC effect

The MPEG-H UI manager interface allows to request to apply one of the defined DRC effect types.
Currently following DRC effects are allowed:

DRC effect ID

DRC effect

Short name
-1 Off OFF
0 None NONE
1 Late night NIGHT
2 Noisy environment NOISY
3 Limited playback range LIMITED
4 Low playback level LOWLEVEL
5 Dialog enhancement DIALOG
6 General compression GENERAL

NOTES:

  • The usage of a DRC effect ID not defined in this table can cause unexpected DRC behavior
  • DRC effect "Off" disables DRC processing
  • DRC effect "None" also disables DRC processing, but automatically enables DRC processing if necessary to prevent signal clipping
  • DRC effect "General compression" can be used for enabling DRC without particular DRC effect type request.

The special DRC effect ID value of -2 is used for falling back to the DRC effect that has been set at the decoder. This special value is the default value of the UI manager.

The system framework shall provide the possibility to select the desired DRC effect type as a system-wide setting. Additionally to the user selection of a desired DRC effect type, the system framework can also provide a way for an automatic switch to a specific DRC effect type: e.g. selection of "NIGHT" DRC effect type for a specific time of the day.

To set the DRC effect the ActionEvent shall contain following information:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType = 10 [IIS_UIM_CMD_DRC_SELECTED]
paramInt DRC effect ID (see above table), or special value -2.

NOTE: With this ActionEvent the user or the system just requests to apply a desired DRC effect type. The actually applied DRC effect depends on the following condition:

  • The MPEG-H bitstream contains DRC metadata for the desired DRC effect type.

In the case, where the MPEG-H bitstream doesn't contain DRC metadata for the desired DRC effect type, the MPEG-H UI manager applies a predefined fallback DRC selection strategy.

To allow a visual feedback about existing DRC effect types in the current MPEG-H bitstream, the AudioSceneConfig XML message can contain information about the availability of specific DRC effect types:

<xs:complexType name="DRCInfo">
  <xs:sequence minOccurs="0" maxOccurs="16">
    <xs:element name="drcSetEffectAvailable">
      <xs:complexType>
        <xs:attribute name="index" type="xs:unsignedInt" use="required"/>
      </xs:complexType>
    </xs:element>
  </xs:sequence>
</xs:complexType>

Following XML example of DRC info shows that only NONE, NIGHT and DIALOG effects are available for the current MPEG-H bitstream:

<AudioSceneConfig>
  <DRCInfo>
    <drcSetEffectAvailable index=0/>
    <drcSetEffectAvailable index=1/>
    <drcSetEffectAvailable index=5/>
  </DRCInfo>
  ...
</AudioSceneConfig>

NOTE: The availability information of the DRC effects should only be used as additional information to be presented to the user. The non-availability of a DRC effect type shall not prevent its selection. As defined before, the MPEG-H UI manager will follow a predefined fallback strategy in case the selected DRC effect type is not available.

Scaling of DRC gains

The DRC effect as described above is accomplished by applying a time-varying gain to the audio signal, that is conveyed as metadata in the bitstream.

This time-varying DRC gain can be mitigated by the DRC boost and compress scaling factors. These factors between 0.0 and 1.0 are applied to the DRC gain values in dB. This will lead to increased dynamics of the audio signal.

The boost scaling factor is only applied to positive dB values of the DRC gain. It will affect the dynamics of soft parts of the audio signal. On the other hand, the compress scaling factor is only applied to negative dB values of the DRC gain. It will affect the dynamics of loud parts of the audio signal.

To set the DRC boost and compress scaling factors, the ActionEvent shall contain following information:

ActionEvent parameter

Description
uuid = 00000000-0000-0000-0000-000000000000
version = 9.0
actionType

= 11 [IIS_UIM_CMD_DRC_BOOST]

or

= 12 [IIS_UIM_CMD_DRC_COMPRESS]
paramFloat

Scaling factor on amplifying DRC gains (actionType 11)

or

scaling factor on attenuating DRC gains (actionType 12)

The scaling factors are restricted to the range between 0.0 and 1.0.

The default value is 1.0 for both factors.

Selection of Album Mode

The MPEG-D DRC Album Mode should be activated if the songs of an album are played back in album order.

With activated Album Mode, the Album Loudness value will be selected by the decoder if present in the bitstream.

The Album Mode should not be activated for using a custom playlist or shuffle playback.

With deactivated Album Mode, the Program or Anchor Loudness value will be selected by the decoder. Moreover, MPEG-D DRC Fading gains are applied to the signal if present in the bitstream.

To toggle the Album Mode, the ActionEvent shall contain following information:

ActionEvent parameter

Description
Uuid = 00000000-0000-0000-0000-000000000000
Version = 9.0
actionType = 21 [IIS_UIM_CMD_ALBUM_MODE]
paramBool

= true to activate Album Mode

= false to deactivate Album Mode

The default value is false.

XML/UI Examples

Example 1

AudioSceneConfig XML:

<?xml version="1.0" encoding="utf-8"?>
<AudioSceneConfig uuid="00100000-0000-0000-0000-000000000000" version="9.0" configChanged="false">
  <DRCInfo>
    <drcSetEffectAvailable index="0"/>
    <drcSetEffectAvailable index="1"/>
    <drcSetEffectAvailable index="2"/>
    <drcSetEffectAvailable index="5"/>
    <drcSetEffectAvailable index="6"/>
  </DRCInfo>
  <presets>
  </presets>
  <audioElement id="0" isAvailable="true">
    <customKind langCode="eng">
      <description langCode="eng">Ambience</description>
    </customKind>
  </audioElement>
  <audioElement id="100" isAvailable="true">
    <prominenceLevelProp min="-20.0" max="12.0" def="0.0" val="0.0" isActionAllowed="true"/>
    <mutingProp def="false" val="false" isActionAllowed="true"/>
    <customKind langCode="eng">
      <description langCode="eng">English</description>
    </customKind>
  </audioElement>
  <audioElement id="101" isAvailable="true">
    <prominenceLevelProp min="-40.0" max="30.0" def="0.0" val="0.0" isActionAllowed="true"/>
    <mutingProp def="true" val="true" isActionAllowed="true"/>
    <customKind langCode="spa">
      <description langCode="eng">Spanish</description>
    </customKind>
  </audioElement>
  <audioElement id="102" isAvailable="true">
    <mutingProp def="true" val="true" isActionAllowed="true"/>
    <customKind langCode="chi">
      <description langCode="eng">Chinese</description>
    </customKind>
  </audioElement>
</AudioSceneConfig>

Example description:

  • All DRC effects are available
  • Audio element with id="0"
    • Audio content is in English language
    • Has English label "Ambience"
    • Muting is not allowed
    • Prominence level change is not allowed
    • Positioning is not allowed
  • Audio element with id="100":
    • Audio content is in English language
    • Has English label "English"
    • Allowed prominence level change in range from -20.0 dB to 12.0 dB
    • Current prominence level value is set to 0.0 dB
    • Muting is allowed
    • Not muted
    • Positioning is not allowed
  • Audio element with id="101":
    • Audio content is in Spanish language
    • Has English label "Spanish"
    • Allowed prominence level change in range from -40.0 dB to 30.0 dB
    • Current prominence level value is set to 0.0 dB
    • Muting is allowed
    • Muted
    • Positioning is not allowed
  • Audio element with id="102":
    • Audio content is in Chinese language
    • Has English label "Chinese"
    • Prominence level change is not allowed
    • Muting is allowed
    • Muted
    • Positioning is not allowed

MPEG-H UI renderer example:

Example 2

AudioSceneConfig XML:

<?xml version="1.0" encoding="utf-8"?>
<AudioSceneConfig uuid="12600000-0000-0000-0000-000000000000" version="9.0" configChanged="false">
  <DRCInfo>
    <drcSetEffectAvailable index="0"/>
    <drcSetEffectAvailable index="1"/>
    <drcSetEffectAvailable index="2"/>
    <drcSetEffectAvailable index="5"/>
    <drcSetEffectAvailable index="6"/>
  </DRCInfo>
  <presets>
    <preset id="0" isActive="true" isDefault="true" isAvailable="true">
      <customKind>
        <description langCode="eng">TV </description>
      </customKind>
    </preset>
    <preset id="10" isActive="false" isDefault="false" isAvailable="true">
      <customKind>
        <description langCode="eng">Dialog+</description>
      </customKind>
    </preset>
    <preset id="1" isActive="false" isDefault="false" isAvailable="true">
      <customKind>
        <description langCode="eng">Live</description>
      </customKind>
    </preset>
  </presets>
  <audioElement id="0" isAvailable="true">
    <customKind>
      <description langCode="eng">Bed</description>
    </customKind>
  </audioElement>
  <audioElement id="30" isAvailable="true">
    <prominenceLevelProp min="-20.0" max="12.0" def="-20.0" val="-20.0" isActionAllowed="true"/>
    <mutingProp def="false" val="false" isActionAllowed="false"/>
    <customKind langCode="eng">
      <description langCode="eng">PA</description>
    </customKind>
  </audioElement>
  <audioElementSwitch id="0" isAvailable="true" isActionAllowed="true">
    <prominenceLevelProp min="-20.0" max="12.0" def="0.0" val="0.0" isActionAllowed="true"/>
    <mutingProp def="false" val="false" isActionAllowed="false"/>
    <azimuthProp min="-90.0" max="90.0" def="45.0" val="45.0" isActionAllowed="true"/>
    <elevationProp min="0.0" max="45.0" def="30.0" val="30.0" isActionAllowed="true"/>
    <audioElements>
      <audioElement id="100" isActive="true" isDefault="true" isAvailable="true" isSelectable="true">
        <customKind langCode="eng">
          <description langCode="eng">ENG</description>
        </customKind>
      </audioElement>
      <audioElement id="101" isActive="false" isDefault="false" isAvailable="true" isSelectable="true">
        <customKind langCode="ger">
          <description langCode="eng">GER</description>
        </customKind>
      </audioElement>
    </audioElements>
    <customKind>
      <description langCode="eng">Language</description>
    </customKind>
  </audioElementSwitch>
</AudioSceneConfig>

Example description:

  • All DRC effects are available
  • Available presets:
    • 1st preset with id="0"
      • Has English label "TV" 
      • Is current active preset
      • Is defined as default preset
    • 2nd preset with id="10"
      • Has English label "Dialog+"
    • 3rd preset with id="1"
      • Has English label "Live"
  • Audio element with id="0"
    • Has English label "Bed"
    • Muting is not allowed
    • Prominence level change is not allowed
    • Positioning is not allowed
  • Audio element with id="30":
    • Has English label "PA"
    • Allowed prominence level change in range from -20.0 dB to 12.0 dB
    • Current prominence level value is set to -20.0 dB
    • Muting is not allowed
    • Not muted
    • Positioning is not allowed
    • Audio content is in English language
  • Audio element switch group with id="0"
    • Group label in English is "Language"
    • Available options:
      • Audio element item with id="100"
        • is current active option
        • can be selected
        • is defined as default
        • Has English label "ENG"
        • Audio content is in English language
      • Audio element item with id="101"
        • can be selected
        • Has English label "GER"
        • Audio content is in German language
    • Muting is not allowed
    • Not muted
    • Allowed elevation change in range from 0° to 45°
    • Current elevation value is set to 30°
    • Allowed azimuth change in range from -90° to 90°
    • Current azimuth value is set to 45°
    • Prominence level change is not allowed

MPEG-H UI renderer example:

Example 3

AudioSceneConfig XML:

<?xml version="1.0" encoding="utf-8"?>
<AudioSceneConfig uuid="00500000-0000-0000-0000-000000000000" version="9.0" configChanged="false">
  <DRCInfo>
    <drcSetEffectAvailable index="0"/>
    <drcSetEffectAvailable index="1"/>
    <drcSetEffectAvailable index="2"/>
    <drcSetEffectAvailable index="5"/>
    <drcSetEffectAvailable index="6"/>
  </DRCInfo>
  <presets>
    <preset id="28" isActive="false" isDefault="false" isAvailable="true">
      <customKind>
        <description langCode="eng">Default</description>
      </customKind>
    </preset>
    <preset id="29" isActive="false" isDefault="false" isAvailable="true">
      <customKind>
        <description langCode="eng">English</description>
      </customKind>
    </preset>
    <preset id="30" isActive="false" isDefault="false" isAvailable="true">
      <customKind>
        <description langCode="eng">Mixed</description>
      </customKind>
    </preset>
  </presets>
  <audioElement id="0" isAvailable="true">
    <customKind langCode="eng">
      <description langCode="eng">Ambience</description>
    </customKind>
  </audioElement>
  <audioElement id="101" isAvailable="true">
    <prominenceLevelProp min="-40.0" max="30.0" def="0.0" val="0.0" isActionAllowed="true"/>
    <mutingProp def="true" val="true" isActionAllowed="true"/>
    <customKind langCode="spa">
      <description langCode="eng">Spanish</description>
    </customKind>
  </audioElement>
  <audioElementSwitch id="0" isAvailable="true" isActionAllowed="true">
    <prominenceLevelProp min="-20.0" max="12.0" def="0.0" val="0.0" isActionAllowed="true"/>
    <mutingProp def="false" val="false" isActionAllowed="true"/>
    <audioElements>
      <audioElement id="100" isActive="true" isDefault="true" isAvailable="true" isSelectable="true">
        <customKind langCode="eng">
          <description langCode="eng">ENG</description>
        </customKind>
      </audioElement>
      <audioElement id="102" isActive="false" isDefault="false" isAvailable="true" isSelectable="true">
        <customKind langCode="chi">
          <description langCode="eng">CHI</description>
        </customKind>
      </audioElement>
    </audioElements>
    <customKind>
      <description langCode="eng">Language</description>
    </customKind>
  </audioElementSwitch>
</AudioSceneConfig>

Example description:

  • All DRC effects are available
  • Available presets:
    • 1st preset with id="28"
      • Has English label "Default" 
      • Is current active preset
      • Is defined as default preset
    • 2nd preset with id="29"
      • Has English label "English"
    • 3rd preset with id="30"
      • Has English label "Mixed"
  • Audio element with id="0"
    • Has English label "Ambience"
    • Muting is not allowed
    • Prominence level change is not allowed
    • Positioning is not allowed
    • Audio content is in English language
  • Audio element with id="101":
    • Has English label "Spanish"
    • Allowed prominence level change in range from -40.0 dB to 30.0 dB
    • Current prominence level value is set to 0.0 dB
    • Muting is allowed
    • Muted
    • Positioning is not allowed
    • Audio content is in Spanish language
  • Audio element switch group with id="0"
    • Group label in English is "Language"
    • Available options:
      • Audio element item with id="100"
        • is current active option
        • can be selected
        • is defined as default
        • Has English label "ENG"
        • Audio content is in English language
      • Audio element item with id="102"
        • can be selected
        • Has English label "CHI"
        • Audio content is in Chinese language
    • Allowed prominence level change in range from -20.0 dB to 12.0 dB
    • Current prominence level value is set to 0.0 dB
    • Muting is allowed
    • Unmuted

MPEG-H UI renderer example:

Full UI manager XML schema

<?xml version="1.0" encoding="UTF-8"?>
<!-- IIS MPEG-UI manager XML interface V9.0 -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="AudioSceneConfig">
    <xs:annotation>
      <xs:documentation>audio scene content description</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence minOccurs="0" maxOccurs="1">
        <xs:element name="DRCInfo" type="DRCInfo"/>
        <xs:element name="presets">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="preset" type="Preset" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element name="audioElement" type="AudioElement"/>
          <xs:element name="audioElementSwitch" type="AudioElementSwitch"/>
        </xs:choice>
      </xs:sequence>
      <xs:attribute name="uuid" type="guid" use="required"/>
      <xs:attribute name="version" use="required" fixed="9.0"/>
      <xs:attribute name="configChanged" type="xs:boolean" use="required"/>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="DRCInfo">
    <xs:sequence minOccurs="0" maxOccurs="16">
      <xs:element name="drcSetEffectAvailable">
        <xs:complexType>
          <xs:attribute name="index" type="xs:unsignedInt" use="required"/>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Preset">
    <xs:sequence>
      <xs:element name="kind" type="PresetTable" minOccurs="0"/>
      <xs:element name="customKind" type="CustomDescriptor" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:int" use="required"/>
    <xs:attribute name="isActive" type="xs:boolean" use="required"/>
    <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
    <xs:attribute name="isDefault" type="xs:boolean" use="required"/>
  </xs:complexType>
  <xs:complexType name="AudioElement">
    <xs:sequence>
      <xs:element name="prominenceLevelProp" type="ProminenceLevelProperty" minOccurs="0"/>
      <xs:element name="mutingProp" type="MutingProperty" minOccurs="0"/>
      <xs:element name="azimuthProp" type="AzimuthProperty" minOccurs="0"/>
      <xs:element name="elevationProp" type="ElevationProperty" minOccurs="0"/>
      <xs:element name="kind" type="AudioElementKind" minOccurs="0"/>
      <xs:element name="customKind" type="CustomAudioElementKind" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:int" use="required"/>
    <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
  </xs:complexType>
  <xs:complexType name="AudioElementSwitch">
    <xs:sequence>
      <xs:element name="prominenceLevelProp" type="ProminenceLevelProperty" minOccurs="0"/>
      <xs:element name="mutingProp" type="MutingProperty" minOccurs="0"/>
      <xs:element name="azimuthProp" type="AzimuthProperty" minOccurs="0"/>
      <xs:element name="elevationProp" type="ElevationProperty" minOccurs="0"/>
      <xs:element name="audioElements">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="audioElement" type="AudioElementSwitchItem" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="kind" type="SwitchKindTable" minOccurs="0"/>
      <xs:element name="customKind" type="CustomDescriptor" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:int" use="required"/>
    <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
    <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
  </xs:complexType>
  <xs:complexType name="AudioElementSwitchItem">
    <xs:sequence>
      <xs:element name="kind" type="AudioElementKind" minOccurs="0"/>
      <xs:element name="customKind" type="CustomAudioElementKind" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:int" use="required"/>
    <xs:attribute name="isActive" type="xs:boolean" use="required"/>
    <xs:attribute name="isAvailable" type="xs:boolean" use="required"/>
    <xs:attribute name="isSelectable" type="xs:boolean" default="true"/>
    <xs:attribute name="isDefault" type="xs:boolean" use="required"/>
  </xs:complexType>
  <xs:complexType name="CustomAudioElementKind">
    <xs:complexContent>
      <xs:extension base="CustomDescriptor">
        <xs:attribute name="langCode" type="ISO639-2_3-letter-code"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="AudioElementKind">
    <xs:complexContent>
      <xs:extension base="ContentKindTable">
        <xs:attribute name="langCode" type="ISO639-2_3-letter-code"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="CustomDescriptor">
    <xs:sequence>
      <xs:element name="description" type="LocalizedString" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="ISO639-2_3-letter-code">
    <xs:restriction base="xs:string">
      <xs:pattern value="\[a-z\]\[a-z\]\[a-z\]"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="LocalizedString">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="langCode" type="ISO639-2_3-letter-code" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="PropertyCommon">
    <xs:attribute name="isActionAllowed" type="xs:boolean" use="required"/>
  </xs:complexType>
  <xs:complexType name="ProminenceLevelProperty">
    <xs:complexContent>
      <xs:extension base="PropertyCommon">
        <xs:attribute name="min" type="xs:decimal" use="required"/>
        <xs:attribute name="max" type="xs:decimal" use="required"/>
        <xs:attribute name="val" type="xs:decimal" use="required"/>
        <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="MutingProperty">
    <xs:complexContent>
      <xs:extension base="PropertyCommon">
        <xs:attribute name="val" type="xs:boolean" use="required"/>
        <xs:attribute name="def" type="xs:boolean" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="ElevationProperty">
    <xs:complexContent>
      <xs:extension base="PropertyCommon">
        <xs:attribute name="min" type="xs:decimal" use="required"/>
        <xs:attribute name="max" type="xs:decimal" use="required"/>
        <xs:attribute name="val" type="xs:decimal" use="required"/>
        <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="AzimuthProperty">
    <xs:complexContent>
      <xs:extension base="PropertyCommon">
        <xs:attribute name="min" type="xs:decimal" use="required"/>
        <xs:attribute name="max" type="xs:decimal" use="required"/>
        <xs:attribute name="val" type="xs:decimal" use="required"/>
        <xs:attribute name="def" type="xs:decimal" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="AbstractTable">
    <xs:attribute name="code" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:unsignedByte">
          <xs:minInclusive value="0"/>
          <xs:maxInclusive value="255"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="alias" type="xs:string"/>
  </xs:complexType>
  <xs:complexType name="PresetTable">
    <xs:complexContent>
      <xs:extension base="AbstractTable">
        <xs:attribute name="table" type="xs:string" use="required" fixed="PresetTable"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="ContentKindTable">
    <xs:complexContent>
      <xs:extension base="AbstractTable">
        <xs:attribute name="table" type="xs:string" use="required" fixed="ContentKindTable"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="SwitchKindTable">
    <xs:complexContent>
      <xs:extension base="AbstractTable">
        <xs:attribute name="table" type="xs:string" use="required" fixed="SwitchKindTable"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="ActionEvent">
    <xs:complexType>
      <xs:attribute name="uuid" type="guid" use="required"/>
      <xs:attribute name="version" use="required" fixed="9.0"/>
      <xs:attribute name="actionType" type="xs:int" use="required"/>
      <xs:attribute name="paramInt" type="xs:int"/>
      <xs:attribute name="paramFloat" type="xs:decimal"/>
      <xs:attribute name="paramText" type="xs:string"/>
      <xs:attribute name="paramBool" type="xs:boolean"/>
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="guid">
    <xs:restriction base="xs:string">
      <xs:pattern value="(\[0-9a-fA-F\])\{8\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{4\}-(\[0-9a-fA-F\])\{12\}"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

References

1: ISO/IEC 23008-3:2022↩

Clone this wiki locally