Merge branch 'pyaudio3dtools-updates' into 'main'

---

# Python scripts for Testing the IVAS code and Generating test items

## Contents

0. [Requirements](#0-requirements)

1. [Scripts and classes for testing IVAS code](#1-scripts-and-classes-for-testing-ivas-code)

   - [Classes](#11-classes)

   - [Output directory structure](#12-output-directory-structure)

   - [Scripts](#13-scripts)

- [Python scripts for Testing the IVAS code and Generating test items](#python-scripts-for-testing-the-ivas-code-and-generating-test-items)

  - [Contents](#contents)

  - [0. Requirements](#0-requirements)

  - [- numpy and scipy for `generate_test_items.py`, `testBitexact.py` and `self_test.py`](#--numpy-and-scipy-for-generate_test_itemspy-testbitexactpy-and-self_testpy)

  - [1.  Scripts and classes for testing IVAS code](#1--scripts-and-classes-for-testing-ivas-code)

    - [1.1 Classes](#11-classes)

    - [1.2 Output directory structure](#12-output-directory-structure)

    - [1.3 Scripts](#13-scripts)

      - [Common commandline options for the scripts](#common-commandline-options-for-the-scripts)

     - [runIvasCodec.py](#runivascodecpy)

     - [IvasBuildAndRun.py](#ivasbuildandrunpy)

     - [IvasBuildAndRunChecks.py](#ivasbuildandruncheckspy)

     - [testBitexact.py](#testbitexactpy)

     - [self_test.py](#self_testpy)

2. [Script for generating listening test items](#2-script-for-generating-listening-test-items)

    - [generate_test_items.py](#21-generate_test_itemspy)

    - [Test configuration file](#22-test-configuration-file)

    - [Supported test conditions](#23-supported-test-conditions)

    - [Supported input/output/rendered audio formats](#24-supported-inputoutputrendered-audio-formats)

    - [Pre-renderer Metadata definiton](#25-pre-renderer-metadata-definition)

3. [Script for converting formats and binauralizing](#3-script-for-converting-formats-and-binauralizing)

    - [Binauralizing with head rotation](#31-binauralizing-with-head-rotation)

    - [Generating binaural reference signals](#32-generating-binaural-reference-signals)

      - [`runIvasCodec.py`](#runivascodecpy)

      - [`IvasBuildAndRun.py`](#ivasbuildandrunpy)

      - [`IvasBuildAndRunChecks.py`](#ivasbuildandruncheckspy)

      - [`testBitexact.py`](#testbitexactpy)

      - [`self_test.py`](#self_testpy)

  - [2. Script for generating listening test items](#2-script-for-generating-listening-test-items)

    - [2.1. `generate_test_items.py`](#21-generate_test_itemspy)

    - [2.2. Test configuration file](#22-test-configuration-file)

    - [2.3. Supported test conditions](#23-supported-test-conditions)

    - [2.4. Supported input/output/rendered audio formats](#24-supported-inputoutputrendered-audio-formats)

    - [2.5. Processing](#25-processing)

    - [2.6. Renderer Metadata definition](#26-renderer-metadata-definition)

  - [3. Script for converting formats and binauralizing](#3-script-for-converting-formats-and-binauralizing)

    - [3.1. Binauralizing with head rotation](#31-binauralizing-with-head-rotation)

    - [3.2. Generating binaural reference signals](#32-generating-binaural-reference-signals)

---

|--------------------------------------------------|----------------------|------------------------------------------------|

| MONO                                             |    yes/yes/yes       | mono signals                                   |

| STEREO                                           |    yes/yes/yes       | stereo signals                                 |

| ISM or ISMx                                      |    yes/no/no         | Objects with metadata, description using pre-renderer metadata |

| ISM or ISMx                                      |    yes/no/no         | Objects with metadata, description using renderer metadata |

| MASA or MASAx                                    |    yes/no/no         | mono or stereo signals with spatial metadata !!!metadata must share same basename as waveform file but with .met extension!!! |

| FOA/HOA2/HOA3 or PLANAR(FOA/HOAx)                |    yes/yes/yes       | Ambisonic signals or planar ambisonic signals  |

| BINAURAL/BINAURAL_ROOM                           |    no/yes/yes        | Binaural signals                               |

| 5_1/5_1_2/5_1_4/7_1/7_1_4 or CICP[6/12/14/16/19] |    yes/yes/yes       | Multi-channel signals for predefined loudspeaker layout |

| META                                             |    yes/yes/no        | Audio scene described by a pre-renderer config |

| META                                             |    yes/yes/no        | Audio scene described by a renderer config     |

---

---

### 2.6. Pre-renderer Metadata definition

### 2.6. Renderer Metadata definition

To run, the pre-renderer requires a config file describing the input scene.The expected format of the config file is as follows:

To run, the renderer requires a config file describing the input scene.The expected format of the config file is as follows:

---

- Line 1: Path to a "multitrack" audio file. This should be a single multichannel wav/pcm file that contains all input audio. For example channels 1-4 can be an FOA scene,channel 5 - an object and channels 6-11 - a 5.1 channel bed. If the path is not absolute, it is considered relative to the pre-renderer executable, not the config file. This path has lower priority than the one given on the command line: *The path in the config file is ignored if the --inputAudio argument to the  pre-renderer executable is specified.* When running together with the encoder using EVS_cod_prerenderer.sh, the path in  the config file is ignored and the one provided as script argument is used  instead.

- Line 1: Path to a "multitrack" audio file. This should be a single multichannel wav/pcm file that contains all input audio. For example channels 1-4 can be an FOA scene,channel 5 - an object and channels 6-11 - a 5.1 channel bed. If the path is not absolute, it is considered relative to the renderer executable, not the config file. This path has lower priority than the one given on the command line: *The path in the config file is ignored if the --inputAudio argument to the renderer executable is specified.*

---

- Line 2:  Contains number of inputs. An input can either be an Ambisonics scene, anobject or a channel bed.This is NOT the total number of channels in the input audio file.The pre-renderer currently supports simultaneously:  *Up to 2 SBA inputs,  Up to 2 MC inputs* Up to 16 ISM inputsThese limits can be freely changed with pre-processor macros, if needed.

- Line 2:  Contains number of inputs. An input can either be an Ambisonics scene, anobject or a channel bed.This is NOT the total number of channels in the input audio file.The renderer currently supports simultaneously:  *Up to 2 SBA inputs,  Up to 2 MC inputs* Up to 16 ISM inputsThese limits can be freely changed with pre-processor macros, if needed.

---

- Following lines: 

## 3. Script for converting formats and binauralizing

The script audio3dtool.py can convert between different input and output formats and binauralize the signals. 

The script audio3dtools.py can convert between different input and output formats and binauralize signals. 

Execute `python -m pyaudio3dtools.audio3dtools --help` for usage.

### 3.1. Binauralizing with head rotation

```

python -m pyaudio3dtools.audio3dtools -i cicp6_input.wav  -o . -F BINAURAL_REF -T .\trajectories\full_circle_in_15s

```

### 3.3. Rendering ISM to Custom loudspeakers with auxiliary binaural output

ISM metadata can either be specified via an input text file in the Renderer Metadata definition format, or via the commandline using the same style as IVAS:

```

python -m pyaudio3dtools.audio3dtools -i ism2.wav -f ISM2 -m ism1.csv NULL -F 7_1_4 -o . -b -T .\trajectories\full_circle_in_15s 

```

    audiofile,

    binauralrenderer,

    hoadecoder,

    prerenderer,

    spatialaudioconvert,

    spatialaudioformat,

    spatialmetadata,

)

from .EFAP import EFAP

        "--outformat",

        type=str,

        metavar="OUTFORMAT",

        help="Output format (default = None, same as input format)",

        help="Output format (default = %(default)s, same as input format)",

        default=None,

    )

    parser.add_argument(

        "-s",

        "--infs",

        type=int,

        help="Input sampling rate (Hz) (default = None, deduced for input file)",

        help="Input sampling rate (Hz) (default = %(default)s, deduced for input file)",

        default=None,

    )

    parser.add_argument(

        "-S",

        "--outfs",

        type=int,

        help="Output sampling rate (Hz) (default = None, same as input)",

        help="Output sampling rate (Hz) (default = %(default)s, same as input)",

        default=None,

    )

    parser.add_argument(

        "-c",

        "--inchan",

        type=int,

        help="Input number of channels (default = None, deduced for input file)",

        help="Input number of channels (default = %(default)s, deduced for input file)",

        default=None,

    )

    parser.add_argument(

        "-m",

        "--metadata",

        type=str,

        nargs="+",

        help="list of input metadata files (only relevant for ISM and MASA input)",

        default=None,

    )

    parser.add_argument(

        "-fc",

        "--outfc",

        type=int,

        help="Cut-off freq for eventual low-pass filtering (default = None)",

        help="Cut-off freq for eventual low-pass filtering (default = %(default)s)",

        default=None,

    )

    parser.add_argument(

        "-T",

        "--trajectory",

        type=str,

        help="Head-tracking trajectory file (default = None)",

        help="Head-tracking trajectory file (default = %(default)s)",

        default=None,

    )

    parser.add_argument(

        "--normalize",

        default=None,

        type=int,

        help="Normalize to given loudness with --LOUDNESS_TOOL (default = None)",

        help="Normalize to given loudness with --LOUDNESS_TOOL (default = %(default)s)",

    )

    """ Miscellaneous or meta arguments """

    parser.add_argument(

        "-b",

        "--binaural",

        help="Binauralize output in addition to converting to output format",

        help="Binauralize output *in addition to converting to output format",

        action="store_true",

    )

    parser.add_argument(

        "--binaural_dataset",

        type=str,

        help="Dataset to use for binaural rendering",

        help="Dataset to use for binaural rendering (default = %(default)s)",

        choices=["orange51", "orange52", "orange53", "orange54", "sadie"],

        default="orange53",

    )

                        outfile = outfile.replace(input_ext, ".out.wav")

                outfile = os.path.join(outdir, outfile)

            out_format, out_fs = spatialaudioconvert.spatial_audio_convert(

            spatialaudioconvert.spatial_audio_convert(

                infile,

                outfile,

                in_format=args.informat,

                in_fs=args.infs,

                in_nchans=args.inchan,

                in_meta_files=args.metadata,

                in_ls_layout_file=args.layoutfile,

                out_format=args.outformat,

                out_fs=args.outfs,

            logger.info(f"  Output {outfile}")

            if args.binaural:

                if args.outformat.find("BINAURAL") > -1:

                if args.outformat.startswith("BINAURAL"):

                    raise SystemExit(

                        "BINAURAL output format can not be binauralized again!"

                    )

                out_format_config = spatialaudioformat.Format(in_format=out_format)

                out_sig, out_fs = audiofile.readfile(

                    outfile, nchannels=out_format_config.nchannels, fs=out_fs

                )

                bin_sig = binauralrenderer.binaural_rendering(

                    out_sig, out_format_config.name, fs=out_fs

                )

                _, output_ext = os.path.splitext(os.path.basename(outfile))

                output_binaural_wav = outfile.replace(output_ext, "_BINAURAL.wav")

                audiofile.writefile(output_binaural_wav, bin_sig, out_fs)

                logger.info(f"  Output binaural {output_binaural_wav}")

                outfile_bin = outfile.replace(output_ext, "_BINAURAL.wav")

                logger.info(f"  Output binaural {outfile_bin}")

                spatialaudioconvert.spatial_audio_convert(

                    in_file=outfile,

                    out_file=outfile_bin,

                    in_format=args.outformat,

                    in_fs=args.outfs,

                    in_meta_files=args.metadata,

                    in_ls_layout_file=args.layoutfile,

                    out_format="BINAURAL",

                    output_loudness=args.normalize,

                    loudness_tool=args.loudness_tool,

                    trajectory=args.trajectory,

                    binaural_dataset=args.binaural_dataset,

                )

            outfile = None

    else: