Package: ear
EBU ADM Renderer (EAR)TheEBU ADM Renderer(EAR)is a complete interpretation of theAudio Definition Model (ADM)format, specified in RecommendationITU-R BS.2076-1. ADM is the recommended format for all stages and use cases within the scope of programme productions ofNext Generation Audio (NGA). This repository contains a Python reference implementation of the EBU ADM Renderer.This Renderer implementation is capable of rendering audio signals to all reproduction systems mentioned in"Advanced sound system for programme production (ITU-R BS.2051-1)".Further descriptions of theEARalgorithms and functionalities can be found inEBU Tech 3388.Note: Version 2.0 of the renderer represents also the reference implementation ofITU-R BS.2127 (ITU ADM Renderer)Test filesA initial set of ADM files to test theEARcan be found underhttps://ebu.io/qc/testmaterialandhttp://cvssp.org/data/s3a/public/radiodrama_register.phpInstallationTo install the latest release from PyPi:$pipinstallearPython versionsEARsupports Python >=3.6 and runs on all major platforms (Linux, Mac OSX,
Windows).Installation of extra packagesIf you want to run the unit tests you can install all extra requirements with pip:$pipinstallear[test]Getting startedTheEARreference implementation comes with two command line tools:ear-renderIs the main tool to render BW64/ADM audio filesear-utilsCollection of useful ADM utilitiesCommand line rendererusage:ear-render[-h][-d]-starget_system[-llayout_file][--output-gain-dbgain_db][--fail-on-overload][--enable-block-duration-fix][--programmeid][--comp-objectid][--apply-conversion{to_cartesian,to_polar}][--strict]input_fileoutput_file

EBUADMrenderer

positionalarguments:input_fileoutput_file

optionalarguments:-h,--helpshowthishelpmessageandexit-d,--debugprintdebuginformationwhenanerroroccurs-starget_system,--systemtarget_systemTargetoutputsystem,accoringtoITU-RBS.2051.Availablesystemsare:0+2+0,0+5+0,2+5+0,4+5+0,4+5+1,3+7+0,4+9+0,9+10+3,0+7+0,4+7+0-llayout_file,--layoutlayout_fileLayoutconfigfile--output-gain-dbgain_dboutputgainindB(default:0)--fail-on-overload,-cfailifanoverloadconditionisdetectedintheoutput--enable-block-duration-fixautomaticallytrytofixfaultyblockformatdurations--programmeidselectanaudioProgrammetorenderbyID--comp-objectidselectanaudioObjectbyIDfromacomplementarygroup--apply-conversion{to_cartesian,to_polar}ApplyconversiontoObjectsaudioBlockFormatsbeforerendering--stricttreatunknownADMattributesaserrorsTo render an ADM file, the following three parameters must be given:-sfollowed by the target output format to render tothe name of the input filethe name of the output fileFor exampleear-render -s 0+5+0 input.wav output_surround.wavwill render the BW64/ADM fileinput.wavto a0+5+0target speaker layout and store the result inoutput_surround.wav.Theoptional--layoutparameter allows to specify the real loudspeaker positions and screen dimensions of a reproduction setup.
Refer tothe layout file documentationfor more information about its format.--fail-on-overloadmakes the rendering process fail in case an overload in the output channels to ensure any signal clipping doesn't go unnoticed. Use--output-gain-dbto adjust the output gain.--enable-block-duration-fixautomatically fixes durations ofaudioBlockFormatsin case they are not continuous.Please notethat the proper way to handle this situation is to fix the input file.--strictenables strict ADM parsing mode. Some of the currently available
ADM/BW64 files may not strictly adhere to the BS.2076 specification, for example by including xml attributes that are not part of the standard.
The default behaviour is to output a warning and continue processing.
When strict mode is enabled, warnings are turned into errors and processing is  stopped.Please notethat, depending on the size of the file, it may
take some time to render the file. At the time of writing, the parsing of the ADM XML data is relatively slow when the ADM is large (>= a few megabytes).Command line ADM utilitiesTheear-utilscommand provides various subcommands which can be seen on the help message
when called withear-utils --help:Each subcommand may have its own command line options, which can be
displayed usingear-utils SUBCOMMAND --help, whereSUBCOMMANDis one of the supported subcommands.usage:ear-utils[-h]{make_test_bwf,replace_axml,dump_axml,dump_chna,ambix_to_bwf}...

EBUADMrendererutilities

optionalarguments:-h,--helpshowthishelpmessageandexitavailablesubcommands:{make_test_bwf,replace_axml,dump_axml,dump_chna,ambix_to_bwf}make_test_bwfmakeabwffilefromawavfileandsomemetadatareplace_axmlreplacetheaxmlchunkinanexistingADMBWFfiledump_axmldumptheaxmlchunkofanADMBWFfiletostdoutdump_chnadumpthechnachunkofanADMBWFfiletostdoutambix_to_bwfmakeaBWFfilefromanambixformatHOAfileHOA ADM Creationusage:ear-utilsambix_to_bwf[-h][--normNORM][--nfcDistNFCDIST][--screenRef][--chna-only]inputoutput

positionalarguments:inputinputfileoutputoutputBWFfile

optionalarguments:-h,--helpshowthishelpmessageandexit--normNORMnormalizationmode--nfcDistNFCDISTNear-FieldCompensationDistance(float)--screenRefScreenReference--chna-onlyuseonlyCHNAwithcommondefinitionsTo convert an ambiX file in an ADM one, the following two parameters must be given:the name of the input filethe name of the output fileThe optional parameters are :The normalization of the signals (N3D, FuMa or SN3D, which is the default value)The NFC Distance, i.e., the distance at which the HOA mix was created. A float value between 0 and 20 meters must be given.
The default value 0 means no NFC processing.The screenRef flag, which tells if the audio content is screen related or not. The default value is False, which means no screen scaling.For example,ear-utils ambix_to_bwf --nfcDist 2.53 input.wav output.wavwill create an ADM file called output.wav containing the audio samples of the input.wav file and the ADM metadata corresponding to an ambiX file with SN3D normalization, an 2.53 meters nfcDist, and no screen scaling.Please notethat the software implicitly assumes that all the HOA channels are in ACN ordering and that no channel is missing. For example, it will assumes the signal is a 4th order HOA signal if it finds 25 channels ((4+1)²=25).Changelog2.1.0- 2022-01-26FixedDepth and height parameters were switched in metadata conversion. See#26.Bug in channel lock priority order, which controls the loudspeaker selection when the object position is the same distance from multiple loudspeakers. See#28.Screen scaling now fails explicitly in cases where it was not well-defined before, generally with extreme positions and sizes. See#22.Errors with gaps at the start of metadata. See#13.Rounding of times in XML writer. See#12.audioStreamFormatreferencing error messages. See34b738aand04533fc.Improved extraData handling in BW64 reader; see#48ChangedDirectSpeakerspanner uses allocentric panning for Cartesian positions. See222374a.Removed python 2.7 support.fix_block_format_durationsparameter is deprecated, and the ADM XML parser no longer issues warnings for timing issues -- useear.fileio.adm.timing_fixesfor this functionality instead. See#8.--enable-block-duration-fixperforms more extensive fixes; this now fixes the following issues:audioBlockFormatswhere thertimeplus thedurationof oneaudioBlockFormatdoes not match thertimeof the next.interpolationTimeparameter larger thanduration.audioBlockFormatrtimeplusdurationextending past the end of the containingaudioObject.Issue a warning forDirectSpeakersblocks with aspeakerLabelcontainingLFEwhich is not detected as an LFE channel. See#9.Improved warning and error output: tidier formatting, and repeated warnings are suppressed by default. See#37.AddedloudnessMetadatadata structures, parsing and generation. See#25.ear-utils regeneratecommand to re-generate AXML and CHNA chunks. See#8.TheabsoluteDistanceparameter is now extracted from AXML and added to theExtraDatastructure; see#45.Lots of documentation, seehttps://ear.readthedocs.io/2.0.0- 2019-05-22Changes for ITU ADM renderer reference code.Changes to rendering of Objects specified using Cartesian parameters.Added conversion between Cartesian and polar Objects parameters.Changed to BSD-Clear license.1.2.0- 2019-05-22FixedSlightly non-normalised gains in extent panner.ChangedImproved downmix/upmix behaviour for DirectSpeakers content specified using
the common definitions.Change default azimuth of M+-SC to 15.Support wider azimuths for M+-SC; they may now be between 5 and 25 degrees,
or 35 and 60 degrees.Removed LFE behaviour for Objects.Validate Cartesian and frequency information for Objects1.1.2- 2019-05-22FixedBug whereby NaNs could be produced in polar extent panner.1.1.1- 2019-04-12FixedaspectRatiois an attribute not an element.Accept theurn:ebu:metadata-schema:ebuCore_2016namespace.Added default for Z coordinates.Various deprecation warnings.AddedSpecified loudspeaker positions are now checked against the allowed ranges.Validation of screenEdgeLock in Objects.1.1.0- 2018-11-26Removedadm_parentreferences in ADM objects.AddedMatrixtype support.Simple validation of ADM data model, and more extensive validation of ADM
structures.Support for rendering objects with silentaudioTrackUIDreferences.Support foraudioPackFormatHOA parameters.Selection ofaudioProgrammeand complementaryaudioObjectsfromear-render.adm_pathtoRenderingItems, with pointers to the corresponding ADM
objects. This is not used by the renderer but is a useful feature for other
applications built on top of the underlying ADM library.Support for more flexible referencing of nestedaudioPackFormats; eachaudioTrackUIDorchnarow can reference any appropriateaudioPackFormaton the path from the rootaudioPackFormat(which contains the full set ofaudioChannelFormatsused) to theaudioPackFormatthat contains theaudioChannelFormatof the track.Better support for using multi-channelaudioPackFormats-- in anaudioObjectorchna-only file using multipleaudioPackFormatsmay be
ambiguous if they share someaudioChannelFormats. This should now be
handled correctly in all cases.ChangedThe reference direction betweenaudioTrackFormatandaudioStreamFormatwas reversed in the data model (audioTrackFormats now point at a singleaudioStreamFormat), andaxmlreferences in either direction now establish
this relationship. Note that this does not follow the exact wording in
BS.2076-1, but this helps compatibility with other systems and should match
future revisions of BS.2076. If either of these references are omitted a
warning will be issued when a file is rendered. When generating BW64+ADM
files (withear-utils) both reference directions are now included.Complete re-implementation ofRenderingItemselection to support other
features in this release. This functionality was moved fromear.fileio.utilstoear.core.select_items.RenderingItemsnow use theTrackSpecstructure rather than an index to
point to their source audio, to allow for silent andMatrixtracks.1.0.1- 2018-11-23ChangedAn error will be raised if anyaudioTrackUIDelements or CHNA rows have IDATU_00000000, as references to these elements could be confused with silentaudioTrackUIDreferences.Miscellaneous improvements to testing infrastructure.FixedWhen generating BW64+ADM files (withear-utils), do not generateaudioTrackUIDs with IDATU_00000000, which (as above) could be confused
with silentaudioTrackUIDreferences.Updated use ofattrsto fix deprecation warnings.Wrong imports and CHNA chunk generation inreplace_axmlcommand.Pytest warnings fixed by upgradingpytest-datafilesto 2.0.Error when testingblock_aligneron python 3.7 with coverage enabled.Error inPeakMonitorwhen rendering very short files.dump_chnain binary mode on python 3.Padding character in axml chunk.1.0.0 - 2018-03-29Initial release.