ADM Data¶

The ADM data representation is in the ear.fileio.adm module.

An ADM document is represented by an adm.ADM object, which contains lists of all of the top-level ADM elements.

In general, element objects have properties which match the ADM XML tag or attribute names, except for:

The main ID of elements are stored in an .id property, rather than (for example) .audioProgrammeID.
typeDefinition and typeLabel are resolved to a single .type property.
formatDefinition and formatLabel are resolved to a single .format property.
References to other objects by ID are translated into a python object reference, or a list of references. For example, audioObjectIDRef elements in an audioContent tag become a list of elements.AudioObject stored in elements.AudioContent.audioObjects.

Note

Element objects do contain IDRef properties (e.g. audioObjectIDRef), which are used while parsing, but these are cleared when references are resolved to avoid storing conflicting information.
In representations of ADM elements which contain both text and attributes (for example <objectDivergence azimuthRange="30">0.5</objectDivergence>), the text part is stored in a semantically-relevant property, e.g. elements.ObjectDivergence.value. For boolean elements (e.g. channelLock), this is represented by the presence or absence of the object in the parent object.

class ear.fileio.adm.adm.ADM¶

An ADM document.

addAudioChannelFormat(channelformat)¶

Add an audioChannelFormat.

Parameters: channelformat (ear.fileio.adm.elements.AudioChannelFormat) –

addAudioContent(content)¶

Add an audioContent.

Parameters: content (ear.fileio.adm.elements.AudioContent) –

addAudioObject(audioobject)¶

Add an audioObject.

Parameters: audioobject (ear.fileio.adm.elements.AudioObject) –

addAudioPackFormat(packformat)¶

Add an audioPackFormat.

Parameters: packformat (ear.fileio.adm.elements.AudioPackFormat) –

addAudioProgramme(programme)¶

Add an audioProgramme.

Parameters: programme (ear.fileio.adm.elements.AudioProgramme) –

addAudioStreamFormat(streamformat)¶

Add an audioStreamFormat.

Parameters: streamformat (ear.fileio.adm.elements.AudioStreamFormat) –

addAudioTrackFormat(trackformat)¶

Add an audioTrackFormat.

Parameters: trackformat (ear.fileio.adm.elements.AudioTrackFormat) –

addAudioTrackUID(trackUID)¶

Add an audioTrackUID.

Parameters: trackUID (ear.fileio.adm.elements.AudioTrackUID) –

property audioChannelFormats¶

Get all audioChannelFormat elements.

Type: list[AudioChannelFormat]

property audioContents¶

Get all audioContent elements.

Type: list[AudioContent]

property audioObjects¶

Get all audioObject elements.

Type: list[AudioObject]

property audioPackFormats¶

Get all audioPackFormat elements.

Type: list[AudioPackFormat]

property audioProgrammes¶

Get all audioProgramme elements.

Type: list[AudioProgramme]

property audioStreamFormats¶

Get all audioStreamFormat elements.

Type: list[AudioStreamFormat]

property audioTrackFormats¶

Get all audioTrackFormat elements.

Type: list[AudioTrackFormat]

property audioTrackUIDs¶

Get all audioTrackUID elements.

Type: list[AudioTrackUID]

property elements¶: Iterator over all elements.

lookup_element(key)¶: Get an element by ID.

validate()¶: Validate all elements, raising an exception if an error is found.

Note

This is not extensive.

Top-level Elements¶

class ear.fileio.adm.elements.main_elements.ADMElement(id=None, is_common_definition=False)¶

base class for top-level ADM elements

id¶

ADM ID attribute (e.g. audioProgrammeID)

Type: str

is_common_definition¶

was this read from the common definitions file?

Type: bool

class ear.fileio.adm.elements.AudioProgramme(id=None, is_common_definition=False, audioProgrammeName=None, audioProgrammeLanguage=None, start=None, end=None, maxDuckingDepth=None, audioContents=NOTHING, audioContentIDRef=NOTHING, referenceScreen=PolarScreen(aspectRatio=1.78, centrePosition=PolarPosition(azimuth=0.0, elevation=0.0, distance=1.0), widthAzimuth=58.0), loudnessMetadata=NOTHING)¶

ADM audioProgramme

audioProgrammeName¶

Type: str

audioProgrammeLanguage¶

Type: Optional[str]

start¶

Type: Optional[fractions.Fraction]

end¶

Type: Optional[fractions.Fraction]

maxDuckingDepth¶

Type: Optional[float]

audioContents¶

audioContent elements referenced via audioContentIDRef

Type: list[AudioContent]

referenceScreen¶

Type: Optional[Union[CartesianScreen, PolarScreen]]

loudnessMetadata¶

Type: list[LoudnessMetadata]

class ear.fileio.adm.elements.AudioContent(id=None, is_common_definition=False, audioContentName=None, audioContentLanguage=None, loudnessMetadata=NOTHING, dialogue=None, audioObjects=NOTHING, audioObjectIDRef=None)¶

ADM audioContent

audioContentName¶

Type: str

audioContentLanguage¶

Type: Optional[str]

loudnessMetadata¶

Type: list[LoudnessMetadata]

dialogue¶

Type: Optional[int]

audioObject¶

Type: list[AudioObject]

class ear.fileio.adm.elements.AudioObject(id=None, is_common_definition=False, audioObjectName=None, start=None, duration=None, importance=None, interact=None, disableDucking=None, dialogue=None, audioPackFormats=NOTHING, audioTrackUIDs=NOTHING, audioObjects=NOTHING, audioComplementaryObjects=NOTHING, audioPackFormatIDRef=None, audioTrackUIDRef=None, audioObjectIDRef=None, audioComplementaryObjectIDRef=None)¶

ADM audioObject

audioObjectName¶

Type: str

start¶

Type: Optional[fractions.Fraction]

duration¶

Type: Optional[fractions.Fraction]

importance¶

Type: Optional[int]

interact¶

Type: Optional[bool]

disableDucking¶

Type: Optional[bool]

dialogue¶

Type: Optional[int]

audioPackFormats¶

Type: list[AudioPackFormat]

audioTrackUIDs¶

Type: list[AudioTrackUID]

audioObjects¶

Type: list[AudioObject]

audioComplementaryObjects¶

Type: list[AudioObject]

class ear.fileio.adm.elements.AudioPackFormat(id=None, is_common_definition=False, audioPackFormatName=None, type=None, absoluteDistance=None, audioChannelFormats=NOTHING, audioPackFormats=NOTHING, importance=None, encodePackFormats=NOTHING, inputPackFormat=None, outputPackFormat=None, normalization=None, nfcRefDist=None, screenRef=None, audioChannelFormatIDRef=None, audioPackFormatIDRef=None, encodePackFormatIDRef=None, decodePackFormatIDRef=None, inputPackFormatIDRef=None, outputPackFormatIDRef=None)¶

ADM audioPackformat

audioPackFormatName¶

Type: str

type¶

typeDefintion and/or typeLabel

Type: TypeDefinition

absoluteDistance¶

Type: Optional[float]

audioChannelFormats¶

Type: list[AudioChannelFormat]

audioPackFormats¶

Type: list[AudioPackFormat]

importance¶

Type: Optional[int]

encodePackFormats¶

Only for type==Matrix. Encode and decode pack references are a single binary many-many relationship; we only store one side.

Type: list[AudioPackFormat]

inputPackFormat¶

Only for type==Matrix.

Type: Optional[AudioPackFormat]

outputPackFormat¶

Only for type==Matrix.

Type: Optional[AudioPackFormat]

normalization¶

Only for type==HOA.

Type: Optional[str]

nfcRefDist¶

Only for type==HOA.

Type: Optional[float]

screenRef¶

Only for type==HOA.

Type: Optional[bool]

class ear.fileio.adm.elements.AudioChannelFormat(id=None, is_common_definition=False, audioChannelFormatName=None, type=None, audioBlockFormats=NOTHING, frequency=NOTHING)¶

ADM audioChannelFormat

audioChannelFormatName¶

Type: str

type¶

typeDefintion and/or typeLabel

Type: TypeDefinition

audioBlockFormats¶

Type: list[AudioBlockFormat]

frequency¶

Type: Frequency

class ear.fileio.adm.elements.AudioTrackFormat(id=None, is_common_definition=False, audioTrackFormatName=None, format=None, audioStreamFormat=None, audioStreamFormatIDRef=None)¶

ADM audioTrackFormat

audioTrackFormatName¶

Type: str

format¶

formatDefintion and/or formatLabel

Type: FormatDefinition

audioStreamFormat¶

Type: Optional[AudioStreamFormat]

class ear.fileio.adm.elements.AudioStreamFormat(id=None, is_common_definition=False, audioStreamFormatName=None, format=None, audioChannelFormat=None, audioPackFormat=None, audioTrackFormatIDRef=None, audioChannelFormatIDRef=None, audioPackFormatIDRef=None)¶

ADM audioStreamFormat

audioStreamFormatName¶

Type: str

format¶

formatDefintion and/or formatLabel

Type: FormatDefinition

audioChannelFormat¶

Type: Optional[AudioStreamFormat]

audioPackFormat¶

Type: Optional[AudioPackFormat]

class ear.fileio.adm.elements.AudioTrackUID(id=None, is_common_definition=False, trackIndex=None, sampleRate=None, bitDepth=None, audioTrackFormat=None, audioPackFormat=None, audioTrackFormatIDRef=None, audioPackFormatIDRef=None)¶

ADM audioTrackUID

trackIndex¶

1-based track index from CHNA chunk

Type: Optional[int]

sampleRate¶

Type: Optional[int]

bitDepth¶

Type: Optional[int]

audioTrackFormat¶

Type: Optional[AudioTrackFormat]

audioPackFormat¶

Type: Optional[AudioPackFormat]

Common Sub-Elements¶

class ear.fileio.adm.elements.TypeDefinition(value)¶

Bases: enum.Enum

ADM type definitions, representing typeDefintion and typeLabel attributes.

Binaural = 5¶

DirectSpeakers = 1¶

HOA = 4¶

Matrix = 2¶

Objects = 3¶

class ear.fileio.adm.elements.FormatDefinition(value)¶

Bases: enum.Enum

ADM format definitions, representing formatDefintion and formatLabel attributes.

PCM = 1¶

class ear.fileio.adm.elements.LoudnessMetadata(loudnessMethod=None, loudnessRecType=None, loudnessCorrectionType=None, integratedLoudness=None, loudnessRange=None, maxTruePeak=None, maxMomentary=None, maxShortTerm=None, dialogueLoudness=None)¶

ADM loudnessMetadata

loudnessMethod¶

Type: Optional[str]

loudnessRecType¶

Type: Optional[str]

loudnessCorrectionType¶

Type: Optional[str]

integratedLoudness¶

Type: Optional[float]

loudnessRange¶

Type: Optional[float]

maxTruePeak¶

Type: Optional[float]

maxMomentary¶

Type: Optional[float]

maxShortTerm¶

Type: Optional[float]

dialogueLoudness¶

Type: Optional[float]

class ear.fileio.adm.elements.Frequency(lowPass=None, highPass=None)¶

ADM frequency element

lowPass¶

Type: Optional[float]

highPass¶

Type: Optional[float]

Common Types¶

class ear.fileio.adm.elements.ScreenEdgeLock(horizontal=None, vertical=None)¶

ADM screenEdgeLock information from position elements

horizontal¶

screenEdgeLock from azimuth or X coordinates; must be left or right.

Type: Optional[str]

vertical¶

screenEdgeLock from elevation or Z coordinates; must be top or bottom.

Type: Optional[str]

audioBlockFormat types¶

class ear.fileio.adm.elements.AudioBlockFormat(id=None, rtime=None, duration=None)¶

ADM audioBlockFormat base class

id¶

Type: Optional[str]

rtime¶

Type: Optional[fractions.Fraction]

duration¶

Type: Optional[fractions.Fraction]

Objects audioBlockFormat¶

class ear.fileio.adm.elements.AudioBlockFormatObjects(id=None, rtime=None, duration=None, position=None, cartesian=False, width=0.0, height=0.0, depth=0.0, gain=1.0, diffuse=0.0, channelLock=None, objectDivergence=None, jumpPosition=NOTHING, screenRef=False, importance=10, zoneExclusion=NOTHING)¶

Bases: ear.fileio.adm.elements.AudioBlockFormat

ADM audioBlockFormat with typeDefinition == “Objects”

position¶

Type: Optional[ObjectPosition]

cartesian¶

Type: bool

width¶

Type: float

height¶

Type: float

depth¶

Type: float

gain¶

Type: float

diffuse¶

Type: float

channelLock¶

Type: Optional[ChannelLock]

objectDivergence¶

Type: Optional[ObjectDivergence]

jumpPosition¶

Type: JumpPosition

screenRef¶

Type: bool

importance¶

Type: int

zoneExclusion¶

Type: list[Union[CartesianZone, PolarZone]]

class ear.fileio.adm.elements.CartesianZone(minX, minY, minZ, maxX, maxY, maxZ)¶

ADM zoneExclusion zone element with Cartesian coordinates

minX¶

Type: float

minY¶

Type: float

minZ¶

Type: float

maxX¶

Type: float

maxY¶

Type: float

maxZ¶

Type: float

class ear.fileio.adm.elements.PolarZone(minElevation, maxElevation, minAzimuth, maxAzimuth)¶

ADM zoneExclusion zone element with polar coordinates

minElevation¶

Type: float

maxElevation¶

Type: float

minAzimuth¶

Type: float

maxAzimuth¶

Type: float

class ear.fileio.adm.elements.ChannelLock(maxDistance=None)¶

ADM channelLock element

maxDistance¶

Type: Optional[float]

class ear.fileio.adm.elements.JumpPosition(flag=False, interpolationLength=None)¶

ADM jumpPosition element

flag¶

contents of the jumpPosition element

Type: bool

interpolationLength¶

Type: Optional[fractions.Fraction]

class ear.fileio.adm.elements.ObjectDivergence(value, azimuthRange=None, positionRange=None)¶

ADM objectDivergence element

value¶

Type: float

azimuthRange¶

Type: Optional[float]

positionRange¶

Type: Optional[float]

class ear.fileio.adm.elements.ObjectPosition¶: Base for classes representing data contained in audioBlockFormat position elements for Objects.

See also

ObjectPolarPosition and ObjectCartesianPosition

class ear.fileio.adm.elements.ObjectPolarPosition(azimuth, elevation, distance=1.0, screenEdgeLock=NOTHING)¶

Bases: ear.fileio.adm.elements.ObjectPosition, ear.common.PolarPositionMixin

Represents data contained in audioBlockFormat position elements for Objects where polar coordinates are used.

Attributes are formatted according to the ADM coordinate convention.

azimuth¶

anti-clockwise azimuth in degrees, measured from the front

Type: float

elevation¶

elevation in degrees, measured upwards from the equator

Type: float

distance¶

distance relative to the audioPackFormat absoluteDistance parameter

Type: float

screenEdgeLock¶

Type: ScreenEdgeLock

class ear.fileio.adm.elements.ObjectCartesianPosition(X, Y, Z, screenEdgeLock=NOTHING)¶

Bases: ear.fileio.adm.elements.ObjectPosition, ear.common.CartesianPositionMixin

Represents data contained in audioBlockFormat position elements for Objects where Cartesian coordinates are used.

Attributes are formatted according to the ADM coordinate convention.

X¶

left-to-right position, from -1 to 1

Type: float

Y¶

back-to-front position, from -1 to 1

Type: float

Z¶

bottom-to-top position, from -1 to 1

Type: float

screenEdgeLock¶

Type: ScreenEdgeLock

DirectSpeakers audioBlockFormat¶

class ear.fileio.adm.elements.AudioBlockFormatDirectSpeakers(id=None, rtime=None, duration=None, position=None, speakerLabel=NOTHING)¶

Bases: ear.fileio.adm.elements.AudioBlockFormat

ADM audioBlockFormat with typeDefinition == “DirectSpeakers”

position¶

Type: DirectSpeakerPosition

speakerLabel¶

Type: list[str]

class ear.fileio.adm.elements.BoundCoordinate(value, min=None, max=None)¶

ADM position coordinate for DirectSpeakers

This represents multiple position elements with the same coordinate, so for azimuth this translates to:

<position coordinate="azimuth">{value}</position>
<position coordinate="azimuth" bound="min">{min}</position>
<position coordinate="azimuth" bound="max">{max}</position>

Attributes are formatted according to the ADM coordinate convention.

value¶

value for unbounded position element

Type: float

min¶

value for position element with bound="min"

Type: Optional[float]

max¶

value for position element with bound="max"

Type: Optional[float]

class ear.fileio.adm.elements.DirectSpeakerPosition¶: Base for classes representing data contained in audioBlockFormat position elements for DirectSpeakers.

See also

DirectSpeakerPolarPosition and DirectSpeakerCartesianPosition

class ear.fileio.adm.elements.DirectSpeakerPolarPosition(bounded_azimuth, bounded_elevation, bounded_distance=NOTHING, screenEdgeLock=NOTHING)¶

Bases: ear.fileio.adm.elements.DirectSpeakerPosition, ear.common.PolarPositionMixin

Represents data contained in audioBlockFormat position elements for DirectSpeakers where polar coordinates are used.

Attributes are formatted according to the ADM coordinate convention.

bounded_azimuth¶

data for position elements with coordinate="azimuth"

Type: BoundCoordinate

bounded_elevation¶

data for position elements with coordinate="elevation"

Type: BoundCoordinate

bounded_distance¶

data for position elements with coordinate="distance"

Type: BoundCoordinate

screenEdgeLock¶

Type: ScreenEdgeLock

as_cartesian_array()¶

Get the position as a Cartesian array.

Returns: equivalent X, Y and Z coordinates
Return type: np.array of shape (3,)

property azimuth¶

anti-clockwise azimuth in degrees, measured from the front

Type: float

property distance¶

distance relative to the audioPackFormat absoluteDistance parameter

Type: float

property elevation¶

elevation in degrees, measured upwards from the equator

Type: float

class ear.fileio.adm.elements.DirectSpeakerCartesianPosition(bounded_X, bounded_Y, bounded_Z, screenEdgeLock=NOTHING)¶

Bases: ear.fileio.adm.elements.DirectSpeakerPosition, ear.common.CartesianPositionMixin

Represents data contained in audioBlockFormat position elements for DirectSpeakers where Cartesian coordinates are used.

bounded_X¶

data for position elements with coordinate="X"

Type: BoundCoordinate

bounded_Y¶

data for position elements with coordinate="Y"

Type: BoundCoordinate

bounded_Z¶

data for position elements with coordinate="Z"

Type: BoundCoordinate

screenEdgeLock¶

Type: ScreenEdgeLock

property X¶

left-to-right position, from -1 to 1

Type: float

property Y¶

back-to-front position, from -1 to 1

Type: float

property Z¶

bottom-to-top position, from -1 to 1

Type: float

HOA AudioBlockFormat¶

class ear.fileio.adm.elements.AudioBlockFormatHoa(id=None, rtime=None, duration=None, equation=None, order=None, degree=None, normalization=None, nfcRefDist=None, screenRef=None)¶

Bases: ear.fileio.adm.elements.AudioBlockFormat

ADM audioBlockFormat with typeDefinition == “HOA”

equation¶

Type: Optional[str]

order¶

Type: Optional[int]

degree¶

Type: Optional[int]

normalization¶

Type: Optional[str]

nfcRefDist¶

Type: Optional[float]

screenRef¶

Type: Optional[bool]

Matrix AudioBlockFormat¶

class ear.fileio.adm.elements.AudioBlockFormatMatrix(id=None, rtime=None, duration=None, outputChannelFormat=None, matrix=NOTHING, outputChannelFormatIDRef=None)¶

Bases: ear.fileio.adm.elements.AudioBlockFormat

ADM audioBlockFormat with typeDefinition == “Matrix”

outputChannelFormat¶

Type: Optional[AudioChannelFormat]

matrix¶

Type: list[MatrixCoefficient]

class ear.fileio.adm.elements.MatrixCoefficient(inputChannelFormat=None, gain=None, gainVar=None, phase=None, phaseVar=None, delay=None, delayVar=None, inputChannelFormatIDRef=None)¶

ADM audioBlockFormat Matrix coefficient element

inputChannelFormat¶

Type: Optional[AudioChannelFormat]

gain¶

Type: Optional[float]

gainVar¶

Type: Optional[str]

phase¶

Type: Optional[float]

phaseVar¶

Type: Optional[str]

delay¶

Type: Optional[float]

delayVar¶

Type: Optional[str]