Usage¶

Command-Line Tools¶

The EAR reference implementation comes with two command line tools:

ear-render: Is the main tool to render BW64/ADM audio files
ear-utils: Collection of useful ADM utilities

`ear-render`¶

To render an ADM file, the following three parameters must be given:

-s followed by the target output format to render to
the name of the input file
the name of the output file

For example, ear-render -s 0+5+0 input.wav output_surround.wav will render the BW64/ADM file input.wav to a 0+5+0 target speaker layout and store the result in output_surround.wav.

usage: ear-render [-h] [-d] -s target_system [-l layout_file]
                  [--output-gain-db gain_db] [--fail-on-overload]
                  [--enable-block-duration-fix] [--programme id]
                  [--comp-object id]
                  [--apply-conversion {to_cartesian,to_polar}] [--strict]
                  input_file output_file

Positional Arguments¶

input_file: BW64 file with CHNA and AXML (optional) chunks
output_file: BW64 output file

Named Arguments¶

-d, --debug

print debug information when an error occurs

Default: False

-s, --system

Target output system, accoring to ITU-R BS.2051. Available systems are: 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

-l, --layout

Layout config file

See speakers_file.

--output-gain-db

output gain in dB (default: 0)

Default: 0

--fail-on-overload, -c

fail if an overload condition is detected in the output

Default: False

--enable-block-duration-fix

automatically try to fix faulty block format durations

Default: False

--programme

select an audioProgramme to render by ID

--comp-object

select an audioObject by ID from a complementary group

Default: []

--apply-conversion

Possible choices: to_cartesian, to_polar

Apply conversion to Objects audioBlockFormats before rendering

--strict

treat unknown ADM attributes as errors

Default: False

`ear-utils`¶

The ear-utils command contains a collection of utilities for working with ADM files as sub-commands.

EBU ADM renderer utilities

usage: ear-utils [-h] [-d]
                 {make_test_bwf,replace_axml,dump_axml,dump_chna,regenerate,ambix_to_bwf}
                 ...

Named Arguments¶

-d, --debug

print debug information when an error occurs

Default: False

Sub-commands:¶

make_test_bwf¶

make a bwf file from a wav file and some metadata

ear-utils make_test_bwf [-h] -i INPUT -m META [--screen speakers_file] output

Positional Arguments¶

output: output bwf file

Named Arguments¶

-i, --input

input wav file

-m, --meta

input yaml metadata file

--screen

YAML format speakers file to take reference screen from

See speakers_file.

replace_axml¶

replace the axml chunk in an existing ADM BWF file

ear-utils replace_axml [-h] -a file [-g] input output

Positional Arguments¶

input: input bwf file
output: output bwf file

Named Arguments¶

-a, --axml

new axml chunk file

-g, --gen-chna

generate the CHNA information from the track UIDs

Default: False

dump_axml¶

dump the axml chunk of an ADM BWF file to stdout

ear-utils dump_axml [-h] input

Positional Arguments¶

input: input bwf file

dump_chna¶

dump the chna chunk of an ADM BWF file to stdout

ear-utils dump_chna [-h] [-b] input

Positional Arguments¶

input: input bwf file

Named Arguments¶

-b, --binary

output binary data

Default: False

regenerate¶

read and write an ADM BWF file, regnerating the ADM and CHNA

ear-utils regenerate [-h] [--enable-block-duration-fix] input output

Positional Arguments¶

input: input bwf file
output: output bwf file

Named Arguments¶

--enable-block-duration-fix

automatically try to fix faulty block format durations

Default: False

ambix_to_bwf¶

make a BWF file from an ambix format HOA file

ear-utils ambix_to_bwf [-h] [--norm NORM] [--nfcDist NFCDIST] [--screenRef]
                       [--chna-only]
                       input output

Positional Arguments¶

input: input file
output: output BWF file

Named Arguments¶

--norm

normalization mode

Default: “SN3D”

--nfcDist

Near-Field Compensation Distance (float)

--screenRef

Screen Reference

Default: False

--chna-only

use only CHNA with common definitions

Default: False

Speakers File Format¶

Information about the loudspeaker layout can be passed to the renderer by using a speakers file with the --speakers flag.

File Format¶

A speakers file is a YAML document, which contains a list of loudspeakers under the speakers key, and the screen information under the screen key. Either may be omitted if not required.

Speakers list¶

The top level speakers item should contain a sequence of mappings, one for each output loudspeaker.

Each mapping should look something like this:

- {channel: 7, names: M+000, position: {az: 0.0, el: 0.0, r: 2.0 }}

which defines a loudspeaker connected to channel 7 (zero based), assigned to M+000 (in bs.2051 terms), with a given position. The file should contain a sequence of lines as above; one line per speaker.

The possible keys are as follows:

channel (required): The zero-based output channel number.
names (required): A list (or a single string) of BS.2051 channel names that this speaker should handle, i.e. like M+000 or [U+180, UH+180].
position (optional): A mapping containing the real loudspeaker position, with keys az, el and r specifying the azimuth, elevation and distance of the loudspeaker in ADM angle format (anticlockwise azimuth, degrees) and metres.
gain_linear (optional): A linear gain to apply to this output channel; this is useful for LFE outputs.

Screen¶

The top level screen item should contain a mapping, with at least a type key, and the following options, depending on the type. If the screen key is omitted, the default polar screen position specified in BS.2076-1 will be assumed. If a null screen is specified, then screen-related processing will not be applied.

if `type == "polar"`¶

aspectRatio (required): Screen width divided by screen height
centrePosition (required): Polar position of the centre of the screen, in the same format as the speaker position attribute.
widthAzimuth (required): Width of the screen in degrees.

if `type == "cart"`¶

aspectRatio (required): Screen width divided by screen height
centrePosition (required): Cartesian position of the centre of the screen; a mapping with keys X, Y and Z.
widthX (required): Width of the screen in Cartesian coordinates.

Examples¶

Useful speakers files should be stored in ear/doc/speakers_files/.

A minimal example with a polar screen would look like:

speakers:
    - {channel: 0, names: M+030, position: {az: 30.0, el: 0.0, r: 2.0 }}
    - {channel: 1, names: M-030, position: {az: -30.0, el: 0.0, r: 2.0 }}
screen:
    type: polar
    aspectRatio: 1.78
    centrePosition: {az: 0.0, el: 0.0, r: 1.0}
    widthAzimuth: 58.0

A minimal example with a Cartesian screen would look like:

speakers:
    - {channel: 0, names: M+030, position: {az: 30.0, el: 0.0, r: 2.0 }}
    - {channel: 1, names: M-030, position: {az: -30.0, el: 0.0, r: 2.0 }}
screen:
    type: cart
    aspectRatio: 1.78
    centrePosition: {X: 0.0, Y: 1.0, Z: 0.0}
    widthX: 0.5

A minimal example with screen processing disabled:

speakers:
    - {channel: 0, names: M+030, position: {az: 30.0, el: 0.0, r: 2.0 }}
    - {channel: 1, names: M-030, position: {az: -30.0, el: 0.0, r: 2.0 }}
screen: null

Usage¶

Command-Line Tools¶

ear-render¶

Positional Arguments¶

Named Arguments¶

ear-utils¶

Named Arguments¶

Sub-commands:¶

make_test_bwf¶

Positional Arguments¶

Named Arguments¶

replace_axml¶

Positional Arguments¶

Named Arguments¶

dump_axml¶

Positional Arguments¶

dump_chna¶

Positional Arguments¶

Named Arguments¶

regenerate¶

Positional Arguments¶

Named Arguments¶

ambix_to_bwf¶

Positional Arguments¶

Named Arguments¶

Speakers File Format¶

File Format¶

Speakers list¶

Screen¶

if type == "polar"¶

if type == "cart"¶

Examples¶

`ear-render`¶

`ear-utils`¶

if `type == "polar"`¶

if `type == "cart"`¶