Skip to content

Commit

Permalink
update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@gisogrimm
gisogrimm committed Oct 12, 2024
1 parent 32c75e8 commit 1d7b874
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 9 deletions.
29 changes: 20 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,34 @@

## The OVBOX system

The OVBOX system is a system for low-delay network audio communication. It features individual 3D virtual acoustics, integration of head tracking for dynamic binaural rendering as well as rendering of distributed moving sound sources.
The OVBOX system is a system for low-delay network audio communication [[1](#ref1)]. It features individual 3D virtual acoustics based on TASCAR [[2](#ref2)], integration of head tracking for dynamic binaural rendering as well as rendering of distributed moving sound sources. The system can be used for remote rehearsals as well as networked music performances. It has been used by the ORLANDOviols ensemble for a series of streaming concerts [[3](#ref3)], but also for academic research [[4](#ref4),[5](#ref5),[6](#ref6),[7](#ref7),[8](#ref8)].

The system consists of several components: the *client device*, which is this software (optionally running on a dedicated computer, see installation instructions), a *configuration server* with a web interface for the users and a REST API, and a list of *room servers*, which handle the session.

The source code of the configuration server can be found [here](https://github.com/gisogrimm/ov-webfrontend). The source code of the room server can be found [here](https://github.com/gisogrimm/ov-server).

## Installation instructions
## Installation instructions and user manual

For installation instructions see [Wiki pages](https://github.com/gisogrimm/ovbox/wiki/Installation).
For installation instructions see [Wiki pages](https://github.com/gisogrimm/ovbox/wiki/Installation).
A user manual for the ORLANDOviols configuration server can be found
on the [wiki](https://github.com/gisogrimm/ovbox/wiki).

The client software can run on Raspberry Pi (models 4B and 3B+), Ubuntu Linux and on MacOS. See installation instructions for details. A desktop client for Windows is currently under development.

## User manual
## References

A user manual for the ORLANDOviols configuration server can be found
on the [wiki](https://github.com/gisogrimm/ovbox/wiki).
<a name="ref1">[1]</a> Grimm, G. (2024). Interactive low delay music and speech communication via network connections (OVBOX). Acta Acoustica, 8, 1–7. [doi:10.1051/aacus/2024011](https://doi.org/10.1051/aacus/2024011)

<a name="ref2">[2]</a> Grimm, G., Luberadzka, J. & Hohmann, V. (2019). A toolbox for rendering virtual acoustic environments in the context of audiology. Acta Acustica United with Acustica, 105(3), 566–578. [doi:10.3813/AAA.919337](https://doi.org/10.3813/AAA.919337)

<a name="ref3">[3]</a> ORLANDOviols ovbox concers 2020-2022. [youtube playlist](https://www.youtube.com/playlist?list=PLrdgCEhKvxnX0Kio9mZPLEnyKz0ldaCa1)

<a name="ref4">[4]</a> Hartwig, M., Hohmann, V. & Grimm, G. (2021). Speaking with avatars - influence of social interaction on movement behavior in interactive hearing experiments. IEEE VR 2021 Workshop: Sonic Interactions in Virtual Environments (SIVE), 94–98. [doi:10.1109/VRW52623.2021.00025](https://doi.org/10.1109/VRW52623.2021.00025)

<a name="ref5">[5]</a> Grimm, G., Kayser, H., Kothe, A. & Hohmann, V. (2023, January). Evaluation of behavior-controlled hearing devices in the lab using interactive turn-taking conversations. Proceedings of the 10th Convention of the European Acoustics Association, Forum Acusticum 2023. [doi:10.61782/fa.2023.0127](https://doi.org/10.61782/fa.2023.0127)

<a name="ref6">[6]</a> Grimm, G., Kothe, A. & Hohmann, V. (2023, January). Effect of head motion animation on immersion and conversational benefit in turn-taking conversations via telepresence in audiovisual virtual environments. Proceedings of the 10th Convention of the European Acoustics Association Forum Acusticum 2023. [doi:10.61782/fa.2023.0126](https://doi.org/10.61782/fa.2023.0126)

## ovbox
<a name="ref7">[7]</a> Grimm, G., Daeglau, M., Hohmann, V. & Debener, S. (2024). EEG Hyperscanning in the Internet of Sounds:Low-Delay Real-time multi-modal Transmissionusing the OVBOX. 2024 IEEE 5th International Symposium on the Internet of Sounds (IS2), 1–8. [doi:10.1109/IS262782.2024.10704205](https://doi.org/10.1109/IS262782.2024.10704205)

ov-client is a re-implementation of the original ovbox. It can run on
Raspberry Pi (models 4B and 3B+), Ubuntu Linux and on MacOS. See installation instructions for details.
<a name="ref8">[8]</a> Müller, P., Haefeli, R., Schütt, J. & Ziegler, M. (2024). Telemersive Audio Systems for Online Jamming. 2024 IEEE 5th International Symposium on the Internet of Sounds (IS2), 1, 1–15. [doi:10.1109/is262782.2024.10704096](https://doi.org/10.1109/is262782.2024.10704096)
56 changes: 56 additions & 0 deletions tools/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# tool set for OVBOX on Raspberry Pi

This folder contains shell scripts to perform an installation on a Raspberry Pi. The folder `pi` contains autorun shell scripts, which will be installed on the Raspberry Pi.

## Preparation of installer image with apt repo, 32 Bit

Download Raspberry Pi OS lite image, 32 Bit, based on debian buster [here](https://downloads.raspberrypi.com/raspios_oldstable_lite_armhf/images/raspios_oldstable_lite_armhf-2023-05-03/), or run:

```
rm -f 2023-05-03-raspios-buster-armhf-lite.img*
wget https://downloads.raspberrypi.com/raspios_oldstable_lite_armhf/images/raspios_oldstable_lite_armhf-2023-05-03/2023-05-03-raspios-buster-armhf-lite.img.xz
unxz 2023-05-03-raspios-buster-armhf-lite.img.xz
./prepareimage.sh 2023-05-03-raspios-buster-armhf-lite.img /mnt
```

Tested on Ubuntu 20.04 host system, and Raspberry Pi 4B.

## Preparation of installer image with apt repo, 64 Bit

Download Raspberry Pi OS lite image, 64 Bit, based on debian bullseye [here](https://downloads.raspberrypi.com/raspios_oldstable_lite_arm64/images/raspios_oldstable_lite_arm64-2024-07-04/), or run:

```
rm -f 2024-07-04-raspios-bullseye-arm64-lite.img*
wget https://downloads.raspberrypi.com/raspios_oldstable_lite_arm64/images/raspios_oldstable_lite_arm64-2024-07-04/2024-07-04-raspios-bullseye-arm64-lite.img.xz
unxz 2024-07-04-raspios-bullseye-arm64-lite.img.xz
./prepareimage.sh 2024-07-04-raspios-bullseye-arm64-lite.img /mnt
```

Tested on Ubuntu 20.04 host system, and Raspberry Pi 4B.

## Preparation of installer image with installation from source code, development version

Download Raspberry Pi OS lite image, 64 Bit, based on debian bookworm [here](https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2024-07-04/), or run:

```
rm -f 2024-07-04-raspios-bookworm-arm64-lite.img*
wget https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2024-07-04/2024-07-04-raspios-bookworm-arm64-lite.img.xz
unxz 2024-07-04-raspios-bookworm-arm64-lite.img.xz
./prepareimage_pi5.sh 2024-07-04-raspios-bookworm-arm64-lite.img /mnt
```

Tested on Ubuntu 20.04 host system, and Raspberry Pi 4B. Installation takes at least 23 minutes due to compilation and installation of all packages required for compilation. Currently no LSL support. Compilation may fail on hardware with low memory.

Currently not working on Raspberry Pi 5B (ov-client crashes with "Bus error").

## Preparation of ready-to-use image

First, completely install an ovbox system using a method from above. Then remove the SD card from the Raspberry Pi and copy the disk image (make sure to replace `/dev/disk` by the name of the SD card drive):

```
sudo dd if=/dev/disk of=ovbox_ready.img status=progress bs=16M oflag=sync
sudo chown $USER ovbox_ready.img
```

See
https://superuser.com/questions/1373289/how-do-i-shrink-the-partition-of-an-img-file-made-from-dd

0 comments on commit 1d7b874

Please sign in to comment.