{"id":13437191,"url":"https://github.com/ebu/ebu_adm_renderer","last_synced_at":"2025-10-29T15:44:23.583Z","repository":{"id":44753895,"uuid":"123921945","full_name":"ebu/ebu_adm_renderer","owner":"ebu","description":"The EBU ADM Renderer, written in Python, is the reference implementation of EBU Tech 3388","archived":false,"fork":false,"pushed_at":"2024-08-17T19:49:13.000Z","size":1956,"stargazers_count":83,"open_issues_count":16,"forks_count":14,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-02-24T07:03:24.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ear.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause-clear","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-05T13:15:36.000Z","updated_at":"2025-02-14T21:18:28.000Z","dependencies_parsed_at":"2023-01-29T15:45:42.578Z","dependency_job_id":"d28648e2-4993-4176-a997-76838eb32f1c","html_url":"https://github.com/ebu/ebu_adm_renderer","commit_stats":{"total_commits":220,"total_committers":6,"mean_commits":"36.666666666666664","dds":"0.054545454545454564","last_synced_commit":"ef2189021203101eab323e1eccdd2527b32a5024"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Febu_adm_renderer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Febu_adm_renderer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Febu_adm_renderer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Febu_adm_renderer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebu","download_url":"https://codeload.github.com/ebu/ebu_adm_renderer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244370874,"owners_count":20442309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:00:54.943Z","updated_at":"2025-10-29T15:44:18.540Z","avatar_url":"https://github.com/ebu.png","language":"Python","funding_links":[],"categories":["Multimedia content processing"],"sub_categories":[],"readme":"# EBU ADM Renderer (EAR)\n\n[![build status badge](https://github.com/ebu/ebu_adm_renderer/workflows/test/badge.svg)](https://github.com/ebu/ebu_adm_renderer/actions?workflow=test)\n\nThe **EBU ADM Renderer** **(*EAR*)** is a complete interpretation of the **Audio Definition Model (ADM)** format, specified in Recommendation [ITU-R BS.2076-1](https://www.itu.int/rec/R-REC-BS.2076/en). ADM is the recommended format for all stages and use cases within the scope of programme productions of **Next Generation Audio (NGA)**. This repository contains a Python reference implementation of the EBU ADM Renderer.\n\nThis 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)\"](https://www.itu.int/rec/R-REC-BS.2051/en).\n\nFurther descriptions of the *EAR* algorithms and functionalities can be found in [EBU Tech 3388](https://tech.ebu.ch/publications/adm-renderer-for-use-in-nga-broadcasting).\n\n***Note: Version 2.0 of the renderer represents also the reference implementation of [ITU-R BS.2127 (ITU ADM Renderer)](https://www.itu.int/rec/R-REC-BS.2127/en)***\n\n## Test files\nA initial set of ADM files to test the *EAR* can be found under\n  - https://ebu.io/qc/testmaterial and\n  - http://cvssp.org/data/s3a/public/radiodrama_register.php\n\n## Installation\n\nTo install the latest release from PyPi:\n\n```bash\n$ pip install ear\n```\n\n### Python versions\n\n*EAR* supports Python \u003e=3.6 and runs on all major platforms (Linux, Mac OSX,\nWindows).\n\n### Installation of extra packages\n\nIf you want to run the unit tests you can install all extra requirements with pip:\n```bash\n$ pip install ear[test]\n```\n\n## Getting started\n\nThe *EAR* reference implementation comes with two command line tools:\n\n- `ear-render` Is the main tool to render BW64/ADM audio files\n- `ear-utils` Collection of useful ADM utilities\n\n### Command line renderer\n\n```bash\nusage: ear-render [-h] [-d] -s target_system [-l layout_file]\n                  [--output-gain-db gain_db] [--fail-on-overload]\n                  [--enable-block-duration-fix] [--programme id]\n                  [--comp-object id]\n                  [--apply-conversion {to_cartesian,to_polar}] [--strict]\n                  input_file output_file\n\nEBU ADM renderer\n\npositional arguments:\n  input_file\n  output_file\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -d, --debug           print debug information when an error occurs\n  -s target_system, --system target_system\n                        Target output system, accoring to ITU-R BS.2051.\n                        Available systems are: 0+2+0, 0+5+0, 2+5+0, 4+5+0,\n                        4+5+1, 3+7+0, 4+9+0, 9+10+3, 0+7+0, 4+7+0\n  -l layout_file, --layout layout_file\n                        Layout config file\n  --output-gain-db gain_db\n                        output gain in dB (default: 0)\n  --fail-on-overload, -c\n                        fail if an overload condition is detected in the\n                        output\n  --enable-block-duration-fix\n                        automatically try to fix faulty block format durations\n  --programme id        select an audioProgramme to render by ID\n  --comp-object id      select an audioObject by ID from a complementary group\n  --apply-conversion {to_cartesian,to_polar}\n                        Apply conversion to Objects audioBlockFormats before\n                        rendering\n  --strict              treat unknown ADM attributes as errors\n```\n\nTo render an ADM file, the following three parameters must be given:\n  - `-s` followed by the target output format to render to\n  - the name of the input file\n  - the name of the output file\n\nFor 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`.\n\nThe *optional* `--layout` parameter allows to specify the real loudspeaker positions and screen dimensions of a reproduction setup.\nRefer to [the layout file documentation](doc/layout_file.md) for more information about its format.\n\n`--fail-on-overload` makes the rendering process fail in case an overload in the output channels to ensure any signal clipping doesn't go unnoticed. Use `--output-gain-db` to adjust the output gain.\n\n`--enable-block-duration-fix` automatically fixes durations of `audioBlockFormats` in case they are not continuous.\n**Please note** that the proper way to handle this situation is to fix the input file.\n\n`--strict` enables strict ADM parsing mode. Some of the currently available\nADM/BW64 files may not strictly adhere to the BS.2076 specification, for example by including xml attributes that are not part of the standard.\nThe default behaviour is to output a warning and continue processing.\nWhen strict mode is enabled, warnings are turned into errors and processing is  stopped.\n\n\n**Please note** that, depending on the size of the file, it may\ntake 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 (\u003e= a few megabytes).\n\n### Command line ADM utilities\n\nThe `ear-utils` command provides various subcommands which can be seen on the help message\nwhen called with `ear-utils --help`:\n\nEach subcommand may have its own command line options, which can be\ndisplayed using `ear-utils SUBCOMMAND --help`, where `SUBCOMMAND` is one of the supported subcommands.\n\n```bash\nusage: ear-utils [-h]\n                 {make_test_bwf,replace_axml,dump_axml,dump_chna,ambix_to_bwf}\n                 ...\n\nEBU ADM renderer utilities\n\noptional arguments:\n  -h, --help            show this help message and exit\n\navailable subcommands:\n  {make_test_bwf,replace_axml,dump_axml,dump_chna,ambix_to_bwf}\n    make_test_bwf       make a bwf file from a wav file and some metadata\n    replace_axml        replace the axml chunk in an existing ADM BWF file\n    dump_axml           dump the axml chunk of an ADM BWF file to stdout\n    dump_chna           dump the chna chunk of an ADM BWF file to stdout\n    ambix_to_bwf        make a BWF file from an ambix format HOA file\n```\n\n#### HOA ADM Creation\n```bash\nusage: ear-utils ambix_to_bwf [-h] [--norm NORM] [--nfcDist NFCDIST]\n                              [--screenRef] [--chna-only]\n                              input output\n\npositional arguments:\n  input              input file\n  output             output BWF file\n\noptional arguments:\n  -h, --help         show this help message and exit\n  --norm NORM        normalization mode\n  --nfcDist NFCDIST  Near-Field Compensation Distance (float)\n  --screenRef        Screen Reference\n  --chna-only        use only CHNA with common definitions\n```\n\n\nTo convert an ambiX file in an ADM one, the following two parameters must be given:\n-   the name of the input file\n-   the name of the output file\n\nThe optional parameters are :\n-   The normalization of the signals (N3D, FuMa or SN3D, which is the default value)\n-   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.\n    The default value 0 means no NFC processing.\n-   The screenRef flag, which tells if the audio content is screen related or not. The default value is False, which means no screen scaling.\n\nFor example, `ear-utils ambix_to_bwf --nfcDist 2.53 input.wav output.wav` will 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.\n\n**Please note** that 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Febu_adm_renderer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febu%2Febu_adm_renderer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Febu_adm_renderer/lists"}