get up to date with the main branch to then merge fork into main branch

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: install libsndfile
+        run: sudo apt-get install -y libsndfile1
+
+      - name: Install Tox
+        run: pip install tox
+
+      - name: Run Tox
+        run: tox -e py
+
+      - name: Upload Coverage
+        uses: actions/upload-artifact@v2
+        with:
+          name: coverage-${{ matrix.python }}
+          # use a wildcard so that the archives have a folder in the root
+          path: .tox/py/cov_*

CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## Unreleased Changes
+
+### Fixed
+- Padding after data chunks in bw64 files was not written, and this error was silently ignored in the reader. This can be fixed with the new `ear-utils rewrite` command.
+- Mutable default parameters in ADMBuilder could cause unexpected extra blocks to be added when this was used from other programs.
+- ADM elements outside the `audioFormatExtended` were parsed, causing errors for some files containing non-standard ADM data.
+- Generated IDs for audioStreamFormat and audioTrackFormat included the format (i.e. always PCM, or 0001), but should include the type of the linked channel/pack format. See [#78].
+
+### Changed
+- Added a warning for audioBlockFormats which have a duration but no rtime; previously these were fixed silently. See [#54].
+- Switched from ruamel.yaml to PyYAML. See [#62].
+
+### Added
+
+- Preliminary support for BS.2076-2 structures. Until this is standardised, a warning will be emitted when rendering files with this version. See [#59] and [#58].
+- `--set-version` to `ear-utils regenerate`. This can be used to fix files which use BS.2076-2 features but have no version tag.
+
+## [2.1.0] - 2022-01-26
+
+### Fixed
+- Depth 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].
+- `audioStreamFormat` referencing error messages. See [34b738a] and [04533fc].
+- Improved extraData handling in BW64 reader; see [#48]
+
+### Changed
+- `DirectSpeakers` panner uses allocentric panning for Cartesian positions. See [222374a].
+- Removed python 2.7 support.
+- `fix_block_format_durations` parameter is deprecated, and the ADM XML parser no longer issues warnings for timing issues -- use `ear.fileio.adm.timing_fixes` for this functionality instead. See [#8].
+- `--enable-block-duration-fix` performs more extensive fixes; this now fixes the following issues:
+    - `audioBlockFormats` where the `rtime` plus the `duration` of one `audioBlockFormat` does not match the `rtime` of the next.
+    - `interpolationTime` parameter larger than `duration`.
+    - `audioBlockFormat` `rtime` plus `duration` extending past the end of the containing `audioObject`.
+- Issue a warning for `DirectSpeakers` blocks with a `speakerLabel` containing `LFE` which 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].
+
+### Added
+- `loudnessMetadata` data structures, parsing and generation. See [#25].
+- `ear-utils regenerate` command to re-generate AXML and CHNA chunks. See [#8].
+- The `absoluteDistance` parameter is now extracted from AXML and added to the `ExtraData` structure; see [#45].
+- Lots of documentation, see https://ear.readthedocs.io/
+
 ## [2.0.0] - 2019-05-22
 
 Changes for ITU ADM renderer reference code.
@@ -104,6 +149,26 @@ Changes for ITU ADM renderer reference code.
 
 Initial release.
 
+[#8]: https://github.com/ebu/ebu_adm_renderer/pull/8
+[#9]: https://github.com/ebu/ebu_adm_renderer/pull/9
+[#12]: https://github.com/ebu/ebu_adm_renderer/pull/12
+[#13]: https://github.com/ebu/ebu_adm_renderer/pull/13
+[#22]: https://github.com/ebu/ebu_adm_renderer/pull/22
+[#25]: https://github.com/ebu/ebu_adm_renderer/pull/25
+[#26]: https://github.com/ebu/ebu_adm_renderer/pull/26
+[#28]: https://github.com/ebu/ebu_adm_renderer/pull/28
+[#37]: https://github.com/ebu/ebu_adm_renderer/pull/37
+[#45]: https://github.com/ebu/ebu_adm_renderer/pull/45
+[#48]: https://github.com/ebu/ebu_adm_renderer/pull/48
+[#54]: https://github.com/ebu/ebu_adm_renderer/pull/54
+[#62]: https://github.com/ebu/ebu_adm_renderer/pull/62
+[#59]: https://github.com/ebu/ebu_adm_renderer/pull/59
+[#58]: https://github.com/ebu/ebu_adm_renderer/issues/58
+[#78]: https://github.com/ebu/ebu_adm_renderer/pull/78
+[34b738a]: https://github.com/ebu/ebu_adm_renderer/commit/34b738a
+[04533fc]: https://github.com/ebu/ebu_adm_renderer/commit/04533fc
+[222374a]: https://github.com/ebu/ebu_adm_renderer/commit/222374a
+[2.1.0]: https://github.com/ebu/ebu_adm_renderer/compare/2.0.0...2.1.0
 [2.0.0]: https://github.com/ebu/ebu_adm_renderer/compare/1.2.0...2.0.0
 [1.2.0]: https://github.com/ebu/ebu_adm_renderer/compare/1.1.2...1.2.0
 [1.1.2]: https://github.com/ebu/ebu_adm_renderer/compare/1.1.1...1.1.2

MANIFEST.in

@@ -1,6 +1,7 @@
 include README.md
 include CHANGELOG.md
-include ear/core/data/README.md
 include LICENSE
 include doc/layout_file.md
 include tox.ini
+
+graft ear

README.md

@@ -1,7 +1,6 @@
 # EBU ADM Renderer (EAR)
 
-[![Build Status](https://travis-ci.org/ebu/ebu_adm_renderer.svg?branch=master)](https://travis-ci.org/ebu/ebu_adm_renderer)
-[![codecov](https://codecov.io/gh/ebu/ebu_adm_renderer/branch/master/graph/badge.svg)](https://codecov.io/gh/ebu/ebu_adm_renderer)
+[![build status badge](https://github.com/ebu/ebu_adm_renderer/workflows/test/badge.svg)](https://github.com/ebu/ebu_adm_renderer/actions?workflow=test)
 
 The **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.
 
@@ -26,8 +25,8 @@ $ pip install ear
 
 ### Python versions
 
-*EAR* supports Python 2.7 and Python >=3.6
-and runs on all major platforms (Linux, Mac OSX, Windows).
+*EAR* supports Python >=3.6 and runs on all major platforms (Linux, Mac OSX,
+Windows).
 
 ### Installation of extra packages
 

doc/.gitignore

@@ -0,0 +1,2 @@
+env
+_build

doc/ADM_XML.rst

@@ -0,0 +1,18 @@
+ADM XML Handling
+================
+
+.. py:module:: ear.fileio.adm.xml
+
+XML Parsing
+-----------
+
+.. autofunction:: load_axml_doc
+.. autofunction:: load_axml_string
+.. autofunction:: load_axml_file
+.. autofunction:: parse_string
+.. autofunction:: parse_file
+
+XML Generation
+--------------
+
+.. autofunction:: adm_to_xml

doc/ADM_data.rst

@@ -0,0 +1,193 @@
+ADM Data
+--------
+
+.. py:module:: ear.fileio.adm
+
+The ADM data representation is in the `ear.fileio.adm` module.
+
+An ADM document is represented by an :class:`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
+  :class:`elements.AudioObject` stored in
+  :attr:`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.
+  :attr:`elements.ObjectDivergence.value`. For boolean elements (e.g.
+  ``channelLock``), this is represented by the presence or absence of the
+  object in the parent object.
+
+.. autoclass:: ear.fileio.adm.adm.ADM
+   :members:
+
+Top-level Elements
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: ear.fileio.adm.elements.main_elements.ADMElement
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioProgramme
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioContent
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioObject
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioPackFormat
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioChannelFormat
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioTrackFormat
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioStreamFormat
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.AudioTrackUID
+   :members:
+
+Common Sub-Elements
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: ear.fileio.adm.elements.TypeDefinition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.FormatDefinition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.LoudnessMetadata
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.Frequency
+   :members:
+
+Common Types
+~~~~~~~~~~~~
+
+.. autoclass:: ear.fileio.adm.elements.ScreenEdgeLock
+   :members:
+
+Timing
+~~~~~~
+
+In general, times and durations are stored as a fractional number of seconds,
+represented by :class:`fractions.Fraction`.
+
+In order to represent fractional ADM times, :class:`time_format.FractionalTime`, a subclass
+of :class:`fractions.Fraction`, is used, while decimal times are represented by
+:class:`fractions.Fraction`.
+
+.. autoclass:: ear.fileio.adm.time_format.FractionalTime
+   :members:
+
+.. autofunction:: ear.fileio.adm.time_format.parse_time
+
+.. autofunction:: ear.fileio.adm.time_format.unparse_time
+
+
+audioBlockFormat types
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: ear.fileio.adm.elements.AudioBlockFormat
+   :members:
+
+Objects audioBlockFormat
+''''''''''''''''''''''''
+
+.. autoclass:: ear.fileio.adm.elements.AudioBlockFormatObjects
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.CartesianZone
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.PolarZone
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.ChannelLock
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.JumpPosition
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.ObjectDivergence
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.ObjectPosition
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.ObjectPolarPosition
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.ObjectCartesianPosition
+   :members:
+   :show-inheritance:
+
+DirectSpeakers audioBlockFormat
+'''''''''''''''''''''''''''''''
+
+.. autoclass:: ear.fileio.adm.elements.AudioBlockFormatDirectSpeakers
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.BoundCoordinate
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.DirectSpeakerPosition
+   :members:
+
+.. autoclass:: ear.fileio.adm.elements.DirectSpeakerPolarPosition
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.DirectSpeakerCartesianPosition
+   :members:
+   :show-inheritance:
+
+HOA AudioBlockFormat
+''''''''''''''''''''
+
+.. autoclass:: ear.fileio.adm.elements.AudioBlockFormatHoa
+   :members:
+   :show-inheritance:
+
+Matrix AudioBlockFormat
+'''''''''''''''''''''''
+
+.. autoclass:: ear.fileio.adm.elements.AudioBlockFormatMatrix
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ear.fileio.adm.elements.MatrixCoefficient
+   :members: