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 MonoItem(channel_format, track_format, pack_format, stream_format, track_uid, audio_object, parent)¶

Structure referencing the ADM components created as part of a mono item.

channel_format¶

Type: AudioChannelFormat

track_format¶

Type: AudioTrackFormat

pack_format¶

Type: AudioPackFormat

stream_format¶

Type: AudioStreamFormat

track_uid¶

Type: AudioTrackUID

audio_object¶

Type: AudioObject

parent¶

Type: Union[AudioContent, AudioObject]

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_item_direct_speakers(*args, **kwargs)¶

Create ADM components needed to represent a DirectSpeakers channel.

Wraps create_item_mono() with type=TypeDefinition.DirectSpeakers.

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

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

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

MonoItem

create_item_objects(*args, **kwargs)¶

Create ADM components needed to represent an object channel.

Wraps create_item_mono() with type=TypeDefinition.Objects.

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.