The BEAR is a binaural renderer for ADM content, as specified in EBU Tech 3396. It is based on the EAR, and is is integrated into the EAR Production Suite.
This repository contains:
-
visr_bear: a real-time C implementation of the BEAR, using libear and VISR. It has a C API that makes it reasonably straightforward to embed into other applications; see visr_bear/include/api.hpp
-
bear: a python module containing a command-line tool
bear-render
, which uses visr_bear to render ADM WAV files to binaural.
This is currently a pre-release, awaiting code to generate the data files from publicly-available data and an EBU tech-doc describing the processing performed by the BEAR.
Building the BEAR can be challenging; as an alternative it's possible to run it in docker if you just want to render files.
-
Install docker:
-
On linux, install the docker package.
-
On OSX or Windows, install docker desktop, or follow a guide like this if the docker desktop license is not suitable.
-
-
Download the image, either:
-
From a workflow artifact -- go to the list of workflows , select one, and download
bear_docker.tar.gz
from the list of artifacts. It will come as a zip file which you'll have to extract (a github actions limitation). -
From a release -- future releases will include a
bear_docker.tar.gz
or similar file.
-
-
Load the image with:
sudo docker load -i path/to/bear_docker.tar.gz
On windows you probably don't need sudo.
To render a file in.wav to out.wav in the current directory:
sudo docker run --rm -v $(pwd):/data bear bear-render data/in.wav data/out.wav
Or to see the available options, run:
sudo docker run --rm bear bear-render --help
-v
sets up a mapping between files inside the container and files outside (so
mapping the current directory (via $(pwd)
) to /data
means that in.wav
becomes /data/in.wav
on the command-line); this is required because docker
runs processes in an isolated environment.
explanation of arguments
sudo docker run
the command to run a container
--rm
delete the created container (not the image) after is finishes
-v $(pwd):/data
allow the container to access files in the current directory (see above)
bear
the name of the image/container to run
bear-render data/in.wav data/out.wav
The BEAR command-line to run.
To get this running, you'll need to install:
- This python module
- VISR
- visr_bear
Steps for each are outlined below.
To fetch the required submodules, first run:
git submodule update --init --recursive
Installation in a virtualenv is generally preferable to doing a system-wide install; follow the Use a virtualenv steps below first to do that.
This repository contains a standard python package.
Install it by changing into this directory and running:
pip install -e .
For development you can install the test and dev dependencies with:
pip install -e .[test,dev]
Tests are ran with:
pytest
To reformat code to match the existing style, run black
on any changed sources. flake8
should ideally not report any warnings.
Get VISR 0.13.0 or greater. Currently this is available in the visr
branch of this repository, or here:
- zip: https://github.com/ebu/bear/archive/refs/heads/visr.zip
- tar.gz: https://github.com/ebu/bear/archive/refs/heads/visr.tar.gz
Eventually this will be available from the upstream repository:
https://github.com/s3a-spatialaudio/VISR
To configure:
cmake -B build . -DBUILD_PYTHON_BINDINGS=ON -DBUILD_DOCUMENTATION=OFF -DBUILD_AUDIOINTERFACES_PORTAUDIO=OFF -DBUILD_USE_SNDFILE_LIBRARY=OFF
Build:
cmake --build build
Install:
cmake --build build -t install
The cmake flags can be adjusted, but python bindings are currently necessary to
run bear-render
and the tests.
This is in the visr_bear
subdirectory:
cd visr_bear
The process is the same as for VISR; to configure:
cmake -B build .
Build:
cmake --build build
Install:
cmake --build build -t install
There are various ways to configure and build this:
You should probably use a virtualenv to avoid messing up your system by installing things to your system directories (which will require sudo). This is just a directory containing an installation of python, and directories for installing libraries and programs.
Create it in env
with:
python -m venv env
To use the virtualenv you'll need to activate it; this just sets up some environment variables:
source ./env/bin/activate
To get cmake to install into the virtualenv, add this to the cmake 'configuration' commands:
-DCMAKE_INSTALL_PREFIX=$VIRTUAL_ENV
With this setup you'll probably need to add env/lib
to your library search path; set this with:
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/
This could be added to the end of the env/bin/activate
script if desired.
For better performance, set either -DCMAKE_BUILD_TYPE=Release
or
-DCMAKE_BUILD_TYPE=RelWithDebInfo
. The latter is nice for development as it
retains debug symbols.
bear-render infile.wav outfile.wav
This supports various options similar to ear-render
; see bear-render --help
.
Copyright 2020 BBC
BEAR is licensed under the terms of the Apache License, Version 2.0; see LICENSE for details.