Audio Orchestrator

Audio Orchestrator is a desktop application for prototyping orchestrated audio experiences.

Create a project, import audio files, and author metadata for audio objects, sequence destinations, and user controls to define the experience; then start a preview with real devices on your local network or export a web application bundle to host it on a server.

• Read the user guide.
• Extend the template application and client libraries.

Audio Orchestrator requires ffmpeg and ffprobe to be available in the system path or a specific location in your home directory. For a manual installation, place the binaries in ~/audio-orchestrator-ffmpeg/bin on macOS and %HOME%\audio-orchestrator-ffmpeg\bin on Windows. See the installation instructions for more details.

NB Audio Orchestrator by default uses a synchronisation server cloud-sync hosted by the BBC, which may go away without warning in the future. We recommend replacing this with your own server by setting its URL in the advanced export settings. There are some notes on running a self-hosted cloud-sync server.

Architecture overview

Audio Orchestrator is an Electron app, using a React app built with webpack for the user interface (in the "renderer" process), and managing background tasks to facilitate file access, media analysis and encoding, and the preview server (in the "main" process).

Development

Development requires a macOS (or possibly Linux) environment. The instructions have only been tested on macOS (on an Apple Silicon machine with macOS Sequoia). The build however produces installers for both Windows (x86) and macOS (x86 and arm64).

Getting started

1. Ensure you have Node.js version 20.x+ installed.

node -v # e.g., v20.9.0

2. Log in to the GitHub packages NPM registry. Create a personal access token (classic) with only the read:packages permission, then log in using your GitHub username and the token as the password:

npm login --registry https://npm.pkg.github.com --scope @bbc

Install the dependencies:

npm install

This will install packages from npm to node_modules/ and then download the required binaries for Electron.

Start a development version of the app:

npm run dev

During development runs, a local server is started on port 8080 to host the react-frontend; make sure this port is not used for anything else or the Electron window will show something else or just a white screen. Changes to the frontend source code should be reflected immediately. The app needs to be restarted for changes to the background tasks or electron app to take effect.

Build the installers for distribution:

npm run dist

The outputs are written to the ./dist/ folder.

Repository structure

All dependencies and scripts are listed in the single package.json at the top level of this repository. The relevant folders are:

• react-frontend/: The user interface, written with React and Redux, interacting with electron APIs through globals set in a preload script.
• background-tasks/: Tasks interacting with subprocesses and the file system, used by the electron-app to provide system operations that can be called from the react-frontend.
• electron-app/: The electron-app, bundling and configuring all the other components to create a standalone desktop application.
• logging/: A common logging module used by the background-tasks and electron-app components.

Releases and versions

Pull requests should update the main package.json version and run npm install && npm run credits before they are merged to ensure the new version is used throughout. Changelog.md should also be manually updated.

Released binaries are currently not signed, so we recommend building Audio Orchestrator yourself from the source code using the instructions above.

Documentation

The user guide hosted on GitHub pages is built automatically by a GitHub action on changes to the docs/ directory on the main branch; a local preview can be run using the material-mkdocs docker image:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

History

Audio Orchestrator was originally developed in the BBC R&D Audio Team by Kristian Hentschel with contributions from Jon Francombe, Emma Young, Danial Haddadi, and Sonal Tandon between 2019 and 2022. It was distributed through the BBC Connected Studio MakerBox site, and used in several public pilots on BBC Taster. The software is now available to interested members of the community through this Audio Orchestrator open source repository, but will not see significant further development from the BBC.