Skip to content
Giso Grimm edited this page Jun 7, 2024 · 51 revisions

Installation instructions

deutsche Version

The installation instructions are probably incomplete, however, they may give a rough idea of the steps involved. Any comments and improvements are welcome!

To use the ovbox hardware or ov-client desktop application after successful installation (e.g., for connecting with other users), you will need an account on the configuration frontend https://box.orlandoviols.com/. We recommend to create an account before device installation.

The ovbox exists as hardware solution or as desktop application for Ubuntu Linux and macOS.

Installing a ready-made system for the Raspberry Pi

This is the easiest way to install an ovbox. You will need a computer (whether Windows PC, Apple or Linux computer), an SD card reader and an ovbox (i.e. a Raspberry Pi with USB sound card). On the computer, you need to install the Raspberry Pi imager (https://www.raspberrypi.org/downloads/) or another programme for writing to the SD card.

Load the ovbox system onto the computer: https://ovbox.de/2024-05-24-raspios-buster-ovbox.img.xz (677 MB).

If you want to make sure that the download worked correctly, you can check the integrity of the file. To do this, you need to calculate the md5sum - open the command line and enter md5sum <file> on Linux or MacOS, or CertUtil -hashfile <file> MD5 on Windows. <file> is the full path to the downloaded file. The md5 sum should be this:

b2f79c3cf68cbd512f01844593494390  2024-05-24-raspios-buster-ovbox.img.xz

Now open the Raspberry Pi imager, select the system by clicking on ‘Operating System’ and then ‘Use custom’ (at the bottom of the list). Select the previously downloaded 2024-05-24-raspios-buster-ovbox.img.xz. The SD card must then be selected. Press ‘write’ to write the system to the SD card. Please wait until the write process and the check have been completed.

raspberry pi imager

Now remove the SD card from the card reader and insert it into the Raspberry Pi.

Before switching on the Raspberry Pi, please make sure that it is

  • it is connected to the internet via a cable;
  • a ‘class compliant’ USB sound card is connected (class compliant devices can be operated with the standard driver for USB sound cards and do not require any special drivers);
  • headphones are connected to the sound card;
  • the new SD card is inserted correctly.

The Raspberry Pi can now be switched on. After about a minute, you should hear an announcement over the headphones and a new device should be displayed on the box.orlandoviols.com website. Now you can connect the device to your account: wiki.

Connect your device to your account as soon as possible so that it is not accidentally claimed by others. The connection to the account is only necessary after the first installation.

Download pre-configured raspios image

This installation works in the same way as with the finished system, only a different file must be selected: https://ovbox.de/2024-03-12-raspios-bullseye-arm64-lite-ovinstaller.zip (508 MB).

If you want to make sure that the download worked correctly, you can check the integrity of the file. To do this, you need to calculate the md5sum - open the command line and enter md5sum <file> under Linux or MacOS, or CertUtil -hashfile <file> MD5 under Windows. <file> is the full path to the downloaded file. The md5 sum should be this:

59c4a291438b366e0669d6957771ab85 2024-03-12-raspios-bullseye-arm64-lite-ovinstaller.zip

When switching on for the first time, many system components are installed from the Internet. This process should not be interrupted as the SD card may be damaged. After about 5-10, in some cases up to 30 minutes (approx. 1.5 GB of data is downloaded from the Internet and installed), you should hear an announcement over your headphones and a new device should be displayed on the box.orlandoviols.com website. Now you can connect the device to your account: wiki.

Connect your device to your account as soon as possible so that it is not accidentally claimed by others. The connection to the account is only necessary after the first installation.

Installation on an Ubuntu LTS and RaspiOS desktop PC

The ovbox is available for Ubuntu LTS and for other Debian-based systems, e.g. RaspiOS, as a binary package. This can be installed via the package manager of the operating system:

In Ubuntu 22.04 (jammy jellyfish, also Debian 12 bookworm):

sudo apt install software-properties-common
wget -qO- http://apt.hoertech.de/openmha-packaging.pub | sudo tee /etc/apt/trusted.gpg.d/openmha-packaging.asc
sudo apt-add-repository 'deb [arch=amd64] http://apt.hoertech.de jammy universe'

In Ubuntu 20.04 (focal, also Debian 11 bullseye):

wget -qO- http://apt.hoertech.de/openmha-packaging.pub | sudo apt-key add -
sudo apt-add-repository 'deb [arch=amd64] http://apt.hoertech.de focal universe'

In Ubuntu 18.04 (bionic, also Debian 10 buster):

wget -qO- http://apt.hoertech.de/openmha-packaging.pub | sudo apt-key add -
sudo apt-add-repository 'deb [arch=amd64] http://apt.hoertech.de bionic universe'

In Debian Buster on ARM (Raspberry Pi):

wget -qO- http://apt.hoertech.de/openmha-packaging.pub | sudo apt-key add -
(echo "";echo "deb [arch=armhf] http://apt.hoertech.de bionic universe")|sudo tee -a /etc/apt/sources.list

Then install the ov-client and all dependendies with

sudo apt update
sudo apt install --assume-yes ov-client-gui

To obtain the shortest possible latencies and a stable connection, the audio system should be optimized. The steps required for this are described here.

You will find the ovbox application in the "Sound & Video" application menu. To start the ovbox manually, open a terminal and type:

ovbox

You may now use the jack ports with your preferred audio software. Please note that ports may disappear and re-appear after remote configuration of your system or any of your peers. To ensure persistent port connections you may use the 'extra ports' field in the 'expert settings' of the 'device settings' dialog.

Installation on macOS

The ovbox was tested under macOS 12 (monterey) and macOS 13 (ventura). Earlier versions of macOS will probably not work.

To run the ovbox under macOS, some additional tools are needed. The most important one is the audio backend jack audio connection kit. This can be installed from jackaudio.org. Navigate to the downloads section and install the latest universal installer. The other dependency is node-js, required for the local web mixer. This can be installed from nodejs.org. To install node-js, download the macOS installer and execute it.

Alternatively, these tools can be installed via brew if you are familiar with the homebrew system:

brew install jack node

Once you have installed the dependencies, please go to the ov-client release page on github and download the latest version of ovbox_X.Y.Z-*_Darwin_x86_64.tgz. Once downloaded, doubleclick to unpack.

unpack downloaded file

You can start ovbox by clicking on the ovbox icon. Depending on your security settings you might need to press the command key when starting it for the first time.

start ovbox

Please keep in mind that the device identifier is different depending on whether you are on Wi-Fi or using a network cable.

Update

To update ovbox under macOS, it is usually sufficient to download the latest published version from Github and unpack it.

Compile yourself

Install the required dependencies via brew and compile the 'ov-client' from sources:

Install brew first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Then install all dependencies (see macos workflows for an up-to-date list):

brew install pkgconfig glibmm jack liblo libsndfile gtkmm3 eigen boost gsl fftw libsamplerate cpprestsdk nlohmann-json openssl coreutils libsoundio xerces-c cmake jpeg libltc libmatio

For access to the web mixer you also need node-js:

brew install node

Afterwards checkout this project:

git clone https://github.com/gisogrimm/ov-client
cd ov-client
git submodule update --init --recursive

Now compile it:

make

To start the binaries, some environment variables need to be set in a way that the plugins will be found. This is handled by the scripts

./start_ov-client.sh

for the command line version, and

./start_ovbox.sh

for the GUI version.

Alternatively, you make create an application bundle with

make packaging

The compressed bundle can be found in the directory packaging/Darwin/.

Installation on Archlinux

ov-client is available through the arch user repository. It can be installed using an AUR helper such as yay or paru as follows:

yay ov-client or paru ov-client

after installation, you will need to enable realtime privileges:

sudo usermod -a -G realtime $USER

Now after logging out and in again, you may start the ov-client by typing ov-client in a terminal.

for a minimal GUI, type ovbox instead.

Finally, proceed with claiming your device in the web frontend.

For the display of the web mixer, the package node-js is required.

Compiling from sources on Linux

For compilation instructions on Fedora, Debian and Archlinux please see Docker files on github: https://github.com/gisogrimm/ov-client/tree/development/docker


Documentation and images CC BY-SA 4.0.