The audiotools module can be used via the CLI for performing rendering of audio files or used as a library by importing the functions in a python script.
This notebook contains a few commandline examples and a brief example of how to use the functions in an interactive python session (like this notebook) which can be also similarly used in a standalone python script.
%% Cell type:markdown id: tags:
# Command-line interface / renderer
The CLI can be used by running the python module: `python -m ivas_processing_scripts.audiotools --help`.
The module, its submodules and functions may be imported just like any other python package. To make the module available in *any* directory, the `PYTHONPATH` must be modified.
The module, its submodules and functions may be imported just like any other python package. To make the module available in _any_ directory, the `PYTHONPATH` must be modified.
The recommended way to do this is to add the following lines at the top of a script which requires this module:
importivas_processing_scripts.audiotools# import can now be resolved
```
An alternative is to modify the shell environment before calling the python interpreter, but this is left to the reader to try. The above solution is cross-platform.
%% Cell type:markdown id: tags:
## Example usage
%% Cell type:code id: tags:
``` python
importsys
sys.path.append("..")# in a real script, this would ideally be an absolute path
print(f"Delay is {getdelay(audio_hoa3,audio_hoa3_delayed)} samples")
```
%% Output
%% Cell type:markdown id: tags:
For more convenient manipulation of audio, the `audio` python file offers the base class `Audio` upon which the derived classes `BinauralAudio`, `ChannelBasedAudio`, `MetadataAssistedSpatialAudio`, `ObjectBasedAudio`, `SceneBasedAudio` are implemented.
To instantiate a class object, the convenience functions ("factory" methods) `fromtype()`, `fromarray()` and `fromfile()` are available:
The audio object allows usage of further functions, which accept an instance of `Audio` (i.e. derived classes), such as the ITU filter wrapper (filter executable must be in "../bin" or PATH!):
# the lpfilter_itu function accepts an audio object
# and a cutoff frequency as arguments
try:
hoa3_lp4k=lpfilter_itu(hoa3,4000)
exceptValueErrorase:
print(f"ValueError encountered : {e}")
# try with a supported cut-off
hoa3_lp3k5=lpfilter_itu(hoa3,3500)
print(f"Input audio: {hoa3.audio}")
print(
f"Filtered audio: {hoa3_lp3k5}"
)# the function returns the filtered array, not an object
```
%% Output
%% Cell type:markdown id: tags:
The object-based approach allows easier manipulation of audio since the necessary values for manipulation are available as attributes. A non-concrete object may also be created to be filled in with data later:
The conversion routines are implemented in the `convert` submodule of `audiotools`. These accept two audio objects - one as an input (a "concrete" object) and another as output to be filled-in ("hollow"). Using the concrete HOA3 audio object we instantiated from an array, and the hollow 7_1_4 object, we can use the `convert_channelbased()` function to perform a conversion:
The `convert_scenebased()` function was already provided with all of the information that was required to perform a conversion from the input format to the output format since they were all class attributes. Under the hood the function checked the type of output audio, computed the necessary rendering matrix using the loudspeaker positions, applied the transformation and set the audio array of the output object.
%% Cell type:markdown id: tags:
A more advanced example with a generator for performing operations on a framewise basis:
# example of an operation involving the input frame
frame_out[:]+=(
frame_in[:]
*0.5
*np.sin(2*np.pi*frame_idx)
*np.random.rand(*frame_in.shape)
)
```
%% Cell type:markdown id: tags:
This concludes the overview of the audiotools module. For readers interested in implementing scripts based on this module, it is recommended to run a debugging session for an example commandline above (either using an IDE or `python -m pdb -m ivas_processing_scripts.audiotools ...`) and examine the functions used, along with a read through of the source code.
A listing of each file in the module with a description is below for reference:
<details>
<summary>Click to expand...</summary>
```bash
.
├── __init__.py
├── __main__.py # entry point for CLI
├── audio.py # implementation of Audio base class and derived classes
├── audioarray.py # functions to manipulate numpy audio arrays
├── audiofile.py # functions to manipulate audio files
├── binaural_datasets
│ ├── __init__.py
│ ├── binaural_dataset.py # reading and parsing of binaural datasets
│ └── README.txt
├── binauralobjectrenderer.py # reference binaural rendering algorithm for object based audio
├── constants.py # submodule shared constants
├── convert
│ ├── __init__.py # TODO rename: conversion module
│ ├── __init__.py # conversion module
│ ├── binaural.py # binaural audio related conversions
│ ├── channelbased.py # channel based audio related conversions
│ ├── masa.py # MASA related conversions (relies on wrappers.masaRenderer)
│ ├── objectbased.py # object based audio related conversions
│ ├── omasa.py
│ ├── osba.py
│ └── scenebased.py # scene based audio related conversions
