ADM Utilities¶

ADM Builder¶

The builder.ADMBuilder class makes it easier to construct basic ADM structures which are properly linked together. For example, to make an ADM with a single Objects channel:

from ear.fileio.adm.builder import ADMBuilder
from ear.fileio.adm.elements import AudioBlockFormatObjects, ObjectPolarPosition

builder = ADMBuilder()

builder.create_programme(audioProgrammeName="my audioProgramme")
builder.create_content(audioContentName="my audioContent")

block_formats = [
    AudioBlockFormatObjects(
        position=ObjectPolarPosition(azimuth=0.0, elevation=0.0, distance=1.0),
    ),
]
builder.create_item_objects(0, "MyObject 1", block_formats=block_formats)

# do something with builder.adm

class ear.fileio.adm.builder.ADMBuilder(adm=NOTHING, last_programme=None, last_content=None, last_object=None, last_pack_format=None, last_stream_format=None, item_parent=None)¶

Builder object for creating ADM object graphs.

adm¶

ADM object to modify.

Type: ADM

last_programme¶

The last programme created, to which created audioContents will be linked.

Type: Optional[AudioProgramme]

last_content¶

The last content created, to which created audioObjects will be linked by default.

Type: Optional[AudioContent]

last_object¶

The last object created, to which created audioObjects or audioPackFormats will be linked by default.

Type: Optional[AudioObject]

last_pack_format¶

The last pack_format created, to which created audioChannelFormats will be linked by default.

Type: Optional[AudioPackFormat]

last_stream_format¶

The last stream_format created, to which created audioTrackFormats will be linked by default.

Type: Optional[AudioStreamFormat]

item_parent¶

The last explicitly created audioContent or audioObject, used as the parent for audioObjects created by create_item* functions.

Type: Optional[Union[AudioContent, AudioObject]]

class Format(channel_formats, track_formats, pack_format, stream_formats)¶

Structure referencing the ADM components of a format with a particular channel layout.

This holds an audioPackFormat, and one audioTrackFormat, audioStreamFormat and audioChannelFormat per channel in the format.

channel_formats¶

Type: list[AudioChannelFormat]

track_formats¶

Type: list[AudioTrackFormat]

pack_format¶

Type: AudioPackFormat

stream_formats¶

Type: list[AudioStreamFormat]

property channel_format¶: singular accessor for channel_formats

property stream_format¶: singular accessor for stream_formats

property track_format¶: singular accessor for track_formats

class Item(format, track_uids, audio_object, parent)¶

Structure referencing the ADM components of a created item.

This holds an audioObject, one audioTrackUID per channel, and a reference to Format for the format parts of the item.

format¶

Type: Format

track_uids¶

Type: list[AudioTrackUID]

audio_object¶

Type: AudioObject

parent¶

Type: Union[AudioContent, AudioObject]

property channel_format¶: accessor for format.channel_format

property channel_formats¶: accessor for format.channel_formats

property pack_format¶: accessor for format.pack_format

property stream_format¶: accessor for format.stream_format

property stream_formats¶: accessor for format.stream_formats

property track_format¶: accessor for format.track_format

property track_formats¶: accessor for format.track_formats

property track_uid¶: singular accessor for track_uids

MonoItem¶

compatibility alias for users expecting *_mono to return MonoItem

alias of ear.fileio.adm.builder.ADMBuilder.Item

create_channel(parent=DEFAULT, **kwargs)¶

Create a new audioChannelFormat.

Parameters

parent (AudioPackFormat) – parent packFormat; defaults to the last packFormat created
kwargs – see AudioChannelFormat

Returns

created audioChannelFormat

Return type

AudioChannelFormat

create_content(parent=DEFAULT, **kwargs)¶

Create a new audioContent.

Parameters

parent (AudioProgramme) – parent programme; defaults to the last one created
kwargs – see AudioContent

Returns

created audioContent

Return type

AudioContent

create_format_hoa(orders, degrees, name, **kwargs)¶

Create ADM components representing the format of a HOA stream.

This is a wrapper around create_format_multichannel().

Parameters

orders (list[int]) – order for each track
degrees (list[int]) – degree for each track
name (str) – name used for all components
kwargs – arguments for AudioBlockFormatHoa

Returns

the created components

Return type

Format

create_format_mono(type, name, block_formats=[])¶

Create ADM components needed to represent a mono format.

This makes:

an audioChannelFormat with the given block_formats
an audioPackFormat linked to the audioChannelFormat
an audioStreamFormat linked to the audioChannelFormat
an audioTrackFormat linked to the audioStreamFormat

Parameters

type (TypeDefinition) – type of channelFormat and packFormat
name (str) – name used for all components
block_formats (list[AudioBlockFormat]) – block formats to add to the channel format

Returns

the created components

Return type

Format

create_format_multichannel(type, name, block_formats)¶

Create ADM components representing a multi-channel format.

This makes:

an audioChannelFormat for each channel
an audioStreamFormat linked to each audioChannelFormat
an audioTrackFormat linked to each audioStreamFormat
an audioPackFormat linked to the audioChannelFormats

Parameters

type (TypeDefinition) – type of channelFormat and packFormat
name (str) – name used for all components
block_formats (list[list[AudioBlockFormat]]) – list of audioBlockFormats for each audioChannelFormat

Returns

the created components

Return type

Format

create_item_direct_speakers(*args, **kwargs)¶

Create ADM components needed to represent a DirectSpeakers channel.

Wraps create_item_mono() with type=TypeDefinition.DirectSpeakers.

Returns: the created components
Return type: Item

create_item_hoa(track_indices, orders, degrees, name, parent=DEFAULT, **kwargs)¶

Create ADM components representing a HOA stream.

This is a wrapper around create_format_hoa() and create_item_multichannel_from_format().

Parameters

track_indices (list[int]) – zero-based indices of the tracks in the BWF file.
orders (list[int]) – order for each track
degrees (list[int]) – degree for each track
name (str) – name used for all components
parent (Union[AudioContent, AudioObject]) – parent of the created audioObject defaults to the last content or explicitly created object
kwargs – arguments for AudioBlockFormatHoa

Returns

the created components

Return type

Item

create_item_mono(type, track_index, name, parent=DEFAULT, block_formats=[])¶

Create ADM components needed to represent a mono channel, either DirectSpeakers or Objects.

This makes:

an audioChannelFormat with the given block_formats
an audioPackFormat linked to the audioChannelFormat
an audioStreamFormat linked to the audioChannelFormat
an audioTrackFormat linked to the audioStreamFormat
an audioTrackUID linked to the audioTrackFormat and audioPackFormat
an audioObject linked to the audioTrackUID and audioPackFormat

Parameters

type (TypeDefinition) – type of channelFormat and packFormat
track_index (int) – zero-based index of the track in the BWF file.
name (str) – name used for all components
parent (Union[AudioContent, AudioObject]) – parent of the created audioObject defaults to the last content or explicitly created object
block_formats (list[AudioBlockFormat]) – block formats to add to the channel format

Returns

the created components

Return type

Item

create_item_mono_from_format(format, track_index, name, parent=DEFAULT)¶

Create ADM components needed to represent a mono channel given an existing format.

This makes:

an audioTrackUID linked to the audioTrackFormat and audioPackFormat of format
an audioObject linked to the audioTrackUID and audioPackFormat

Parameters

format (Format) –
track_index (int) – zero-based index of the track in the BWF file.
name (str) – name used for all components
parent (Union[AudioContent, AudioObject]) – parent of the created audioObject defaults to the last content or explicitly created object

Returns

the created components

Return type

Item

create_item_multichannel(type, track_indices, name, block_formats, parent=DEFAULT)¶

Create ADM components representing a multi-channel object.

This makes:

an audioChannelFormat for each channel
an audioStreamFormat linked to each audioChannelFormat
an audioTrackFormat linked to each audioStreamFormat
an audioPackFormat linked to the audioChannelFormats
an audioTrackUID linked to each audioTrackFormat and the audioPackFormat
an audioObject linked to the audioTrackUIDs and the audioPackFormat

Parameters

type (TypeDefinition) – type of channelFormat and packFormat
track_indices (list[int]) – zero-based indices of the tracks in the BWF file.
name (str) – name used for all components
block_formats (list[list[AudioBlockFormat]]) – list of audioBlockFormats for each audioChannelFormat
parent (Union[AudioContent, AudioObject]) – parent of the created audioObject defaults to the last content or explicitly created object

Returns

the created components

Return type

Item

create_item_multichannel_from_format(format, track_indices, name, parent=DEFAULT)¶

Create ADM components representing a multi-channel object, referencing an existing format structure.

This makes:

an audioTrackUID linked to each audioTrackFormat and the audioPackFormat in format
an audioObject linked to the audioTrackUIDs and the audioPackFormat in format

Parameters

format (Format) – format components to reference
track_indices (list[int]) – zero-based indices of the tracks in the BWF file.
name (str) – name used for all components
parent (Union[AudioContent, AudioObject]) – parent of the created audioObject defaults to the last content or explicitly created object

Returns

the created components

Return type

Item

create_item_objects(*args, **kwargs)¶

Create ADM components needed to represent an object channel.

Wraps create_item_mono() with type=TypeDefinition.Objects.

Returns: the created components
Return type: Item

create_object(parent=DEFAULT, **kwargs)¶

Create a new audioObject.

Parameters

parent (Union[AudioContent, AudioObject]) – parent content or object; defaults to the last content created
kwargs – see AudioObject

Returns

created audioObject

Return type

AudioObject

create_pack(parent=DEFAULT, **kwargs)¶

Create a new audioPackFormat.

Parameters

parent (AudioObject or AudioPackFormat) – parent object or packFormat; defaults to the last object created
kwargs – see AudioPackFormat

Returns

created audioPackFormat

Return type

AudioPackFormat

create_programme(**kwargs)¶

Create a new audioProgramme.

Parameters: kwargs – see AudioProgramme
Returns: created audioProgramme
Return type: AudioProgramme

create_stream(**kwargs)¶

Create a new audioStreamFormat.

Parameters: kwargs – see AudioChannelFormat
Returns: created audioStreamFormat
Return type: AudioStreamFormat

create_track(parent=DEFAULT, **kwargs)¶

Create a new audioTrackFormat.

Parameters

parent (AudioStreamFormat) – parent streamFormat; defaults to the last audioStreamFormat created
kwargs – see AudioTrackFormat

Returns

created audioTrackFormat

Return type

AudioTrackFormat

create_track_uid(parent=DEFAULT, **kwargs)¶

Create a new audioTrackUID.

Parameters

parent (AudioObject) – parent audioObject; defaults to the last audioObject created
kwargs – see AudioTrackUID

Returns

created audioTrackUID

Return type

AudioTrackUID

load_common_definitions()¶: Load common definitions into adm.

ID Generation¶

When ADM objects are created, they have their IDs set to None. Before serialisation, the IDs must be generated using generate_ids():

ear.fileio.adm.generate_ids.generate_ids(adm)¶

regenerate ids for all elements in adm

Parameters: adm (ADM) – ADM structure to modify

CHNA Utilities¶

In a BW64 file, the AXML and CHNA chunks store overlapping and related information about audioTrackUIDs:

track index: CHNA only
audioTrackFormat reference: CHNA and AXML
audioPackFormat reference: CHNA and AXML

To simplify this, the elements.AudioTrackUID class stores the track index from the CHNA, and we provide utilities for copying data between a CHNA and an ADM object:

ear.fileio.adm.chna.load_chna_chunk(adm, chna)¶

Add information from the chna chunk to the adm track UIDs structure.

Any existing track UIDs in adm are checked for consistency against the data in chna; any non-existent track-UIDs are created.

The track index, pack format ref and track format ref attributes are transferred; there references are resolved, and we assume that any references in adm have already been resolved

Parameters

adm (ADM) – adm structure to add information to
chna (ChnaChunk) – chna chunk to get information from

ear.fileio.adm.chna.populate_chna_chunk(chna, adm)¶

Populate the CHNA chunk with information from the ADM model.

All CHNA entries are replaced, and are populated from the trackIndex, audioTrackUID, and the track format/pack format references.

Since the CHNA chunk contains IDs, the IDs in the ADM must have been generated before calling this.

Parameters

adm (ADM) – adm structure to get information to
chna (ChnaChunk) – chna chunk to populate

ear.fileio.adm.chna.guess_track_indices(adm)¶

Guess track indices from the audioTrackUID IDs.

This information should really come from the CHNA, but sometimes that isn’t available.

Parameters: adm (ADM) – ADM structure to modify

Common Definitions¶

The library includes a copy of the common definitions file, which can be loaded into an ADM structure:

ear.fileio.adm.common_definitions.load_common_definitions(adm)¶

Load the common definitions file from IRU-R Rec. BS.2094-1, setting is_common_definition=True on all loaded elements.

Parameters: adm (ADM) – ADM structure to add to.