Guide for setting up an Ambisonics playback system on GNU/Linux using consumer equipment such as a GPU and an AV-receiver

setup_ambisonics_on_gpu.sh

#!/bin/sh

# Setting up an Ambisonics listening rig using consumer hardware
# This guide was tested on Ubuntu Linux using an Nvidia GPU, a consumer-grade 5.1 av-receiver and audio transmission via HDMI.

# install necessary software
sudo apt install qjackctl ambdec mpv

# launch Qjackctl and start JACK on a sound card that is not the GPU
qjackctl

# Create JACK sink for NVidia GPU with 6 channels for 5.1 output.
# Background: On my system it seems impossible to use a GPU output device as
# the main device in Jack. Hence I need to set another audio device (e.g. 
# onboard audio) as the main device and use bridging to make the GPU a second
# playback device.
# To determine the correct device name and number for your GPU output, use aplay -l.
# You might need experiment to determine which device number belongs to which
# HDMI/DP port.
alsa_out -d hw:NVidia,7 -c 6 &
# Alternatively, one can use zita-j2a for tighter synchronization between the
# audio devices, which can be useful if you want to output audio to both audio
# devices at the same time, e.g. to get more output channels for more
# sophisticated Ambisonics setups. However, I couldn't get it to work with my
# GPU.
# sudo apt install zita-ajbridge
# zita-j2a -d hw:NVidia,7 -c 6 &

# With the output device being set up, we now have to launch an Ambisonics
# decoder that decodes B-Format to a given speaker layout.
# Here, we launch ambdec and make it load the ITU5.1 2nd order decoder preset for a 5.1 speaker
# layout and set a volume of 0.
ambdec -p /usr/share/ambdec/presets/ -c /usr/share/ambdec/presets/itu5.1-ord2-optim.ambdec -V 0 &

# After these steps, the "backend" of the Ambisonics playback chain is set up. You can now load applications that output Ambisonics B-Format. I'll illustrate this with mpv.

# Launch mpv in a directory containing *.amb files.
# We disable auto connections to prevent mpv from connecting to unusable (when using a GPU) system ports
mpv --ao=jack --jack-connect=no --jack-std-channel-layout=any .

# mpv is now running and should be playing an *.amb file. However, you will not hear anything since you need to tell Jack how the output ports of mpv have to be connected to ambdec.
# You have to connect everything in QjackCtl in the connection window manually. In my case, the channel order in JACK for the GPU output is FL,FR,SL,SR,C,SW.
# If you play Ambisonic files with ACN channel order, you can simply connect all mpv output ports straight to the corresponding ambdec input ports. E.g.:
# mpv ambdec
# 0 -> 0
# 1 -> 1
# 2 -> 2
# 3 -> 3
# ...

# Should you get incorrect spatialization, most likely the channel mapping from mpv to ambdec or the mapping from ambdec to the GPU ports is incorrect. Be aware of different channel orderings for Ambisonics files. ambdec expects ACN order. If you play files with FuMa channel order, mpv output ports should be connected to ambdec in QjackCtl this way:
# mpv ambdec
# 0 -> 0
# 1 -> 3
# 2 -> 1
# 3 -> 2
# also see https://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#Reference_table_of_layouts_and_normalisations

# You can use this file to test spatialization (has FuMa channel ordering):
# https://ambisonia.com/Members/ajh/ambisonicfile.2007-05-29.7251031563/

# Once everything is connected correctly, you should open the patchbay in QJackCtl, create a new preset and answer yes when prompted whether you want to create a patchbay configuration based on the currect connections to store the current configuration. If you `activate` this preset in the patchbay menu, all ports will be connected automatically the next time you launch the software as long as the preset is active.

# To automate this setup sequence, you can comment out one-time steps (and perhaps the mpv command) and set this script to be executed by QJackCtl when launching JACK (settings -> options -> run script after start).


# If you want to listen to UHJ encoded stereo recordings in surround,
# you can use Ardour with the Ambisonics plugin suite:
sudo apt install ardour amb-plugins

# You need to configure JACK in such a way that the 2 stereo channels are
# routed from your music player to a stereo track in Ardour for which the UHJ
# decoder plugin is active. From Ardour output the 4 channels to ambdec.