Klipspringer platform installation

The Klipspringer software platform includes:

Klipspringer hub (klipspringer-hub command), for launching other components to play or record sound remotely via a web interface.
Track player (kliptrack command), for playing or streaming audio files.
Device player/recorder (kliptune command), for capturing audio from a PCM input such as a microphone or stereo equipment.
File encoder (klipcook command) for converting between audio file formats.
Device list (klipdevices command), to find devices available for audio output and input.
FLAC picture extraction utility (flacpics command), to get pictures from FLAC file metadata.
Track-splitting program (klipsplit command), to split an audio file into tracks by detecting inter-track silence.

It should normally be installed on a computer that has some or all of the following:

Access, in the file system, to audio files you want to play. Klipspringer is primarily designed for FLAC files but also works with WAV, AIFF, Ogg Vorbis, and Opus.
An audio output connected to speakers you want to use for playback.
If you want to record or stream from an external audio source: an input connection from that audio source.
A connection to your local network to expose the HTTP interface.

You can use a small single-board (like a Raspberry Pi) or barebone (like an Intel NUC) computer without any screen or keyboard. (Obviously you need some way to log in to make the installation, but network login via ssh is fine for instance). It also works with a desktop computer of course.

Klipspringer is tested on Ubuntu, Raspberry Pi OS, and macOS, and shouldn’t be difficult to install on any Unix variant. It’s free software, released under GPL3 or later.

Installation Prerequisites

Normal use of Klipspringer requires some or all of the following to be installed before the Klipspringer platform. Suggested commands for installing them on Linux or macOS are in the following sections.

Basic commands to download, unpack and compile: curl, tar, make, and a C compiler (gcc or clang).
Java version 17 or later is required.¹ It’s most straightforward to install a JDK. (But you can get by with just a JVM if you follow the more detailed instructions.) Open JDK is suggested but Oracle’s Java engine also works.
External codec APIs. None of these is strictly necessary, but without any of them Klipspringer can only play WAV and AIFF files, only write WAV files, and not stream at all.
- libFLAC allows playing, writing, and streaming FLAC (.flac) and Ogg FLAC (.oga).
- Vorbis API allows playing, writing and streaming Ogg Vorbis (.ogg).
- Opusfile API allows playing Ogg Opus (.opus) files. (Writing or streaming Opus is not supported.)
- LAME API allows writing and streaming MP3. (Playing MP3 files is not supported.)
Recommended on Linux: ALSA API. Provides direct access to audio devices via ALSA, an interface which most Linux systems have. (But it also works to let Klipspringer access audio devices via the Java sound system.)
Node.js, required for deploying the Klipspringer hub. Version 18.12 or later is recommended. (Some older versions may work but have not been tested.)

Linux

The following commands are suggested to install prerequisites for Debian-based systems, which includes Ubuntu and Raspberry Pi OS (also known as Raspbian). For other distributions, please read the descriptions and do things your way.

Basic tools to download, unpack and compile, in case they are not already installed.

sudo apt-get install curl
sudo apt-get install tar
sudo apt-get install build-essential

Open JDK. The following installs the minimum required version 17. You can check for available versions with apt-cache search openjdk.
```
sudo apt-get install openjdk-17-jdk
```

Codec APIs. Select the ones you want for FLAC, Vorbis, Opus (decoding only), and MP3 (encoding only) support.

sudo apt-get install libflac-dev
sudo apt-get install libvorbis-dev
sudo apt-get install libopusfile-dev
sudo apt-get install libmp3lame-dev

ALSA API (recommended).
```
sudo apt-get install libasound2-dev
```
Node.js. The version you can get from the standard package manager is probably too old. The following command installs the latest LTS version packaged by NodeSource, but if this doesn’t work for you, you can find several alternatives on the official Node.js website.
```
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
```

MacOS

Since macOS doesn’t have a canonical package manager, there are different choices for how to install most of the prerequisites. I suggest using Howebrew, and install packages from the command line (in a terminal), but if you prefer some other method of installation, please substitute the brew commands with your way.

Apologies that some of the points are a bit vague with several things you “may” need to do, but macOS differs a bit between versions so it’s hard to be general.

The curl and tar commands should be preinstalled. You may need to install build commands make and clang. If you type the following at the command line, it should get the installation going, but the same thing (a popup window asking you to confirm the installation) may also happen if you just attempt to run clang for instance.
```
xcode-select --install
```
Homebrew, if you haven’t used it before, can be downloaded and installed with:
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
If you get “command not found” for brew after this, you need to add the Homebrew to your executables PATH. If your command shell is Zsh, which it is in newer installations, you can do something like the following, and then restart Terminal.
```
export PATH="/opt/homebrew/bin:$PATH" >> ~/.zshrc
```
If you (like I do) use Bash rather than Zsh, you can put that in your ~/.bash_profile instead.
Open JDK.
```
brew install openjdk
```
You may need an additional command or two for Open JDK to get fully integrated with your system. If you get “command not found” for java , you probably need to set a symbolic link. You can type brew info openjdk and read what it says, but the part needed on the most recent installation I tried was the following command:
```
sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
```

libFLAC API (recommended).

brew install flac
brew install libvorbis
brew install lame
brew install opusfile

ALSA API is, as far as I know, not available for macOS, so skip it.
Node.js. I personally prefer to install via a .pkg file from the official Node.js site but you can also do:
```
brew install node
```

Note: the Klipspringer dynamic library will most likely point to the specific version of libFLAC, Vorbis, or LAME you have installed at build time, and must therefore be rebuilt after any of these libraries gets upgraded.

Install

Download the latest full Klipspringer tarball. You can do it with a web browser by clicking this link, but if you are installing via an ssh connection you will prefer the curl command:
```
curl -O https://klipspringer.avadeaux.net/builds/klipspringer-4.3.2.2.tar.gz
```
Unpack the tarball, enter the unpacked directory, and run configure:
```
tar xf klipspringer-4.3.2.2.tar.gz
cd klipspringer-4.3.2.2
./configure
```
Check what was printed to see if there were any problems that you want to do something about.
Build and install.
```
 make
 sudo make install
```

Verify and configure

The first thing to verify is that you get any sound at all from Klipspringer (unless you are only going to use the installation for streaming). Try kliptrack with some audio file (FLAC, WAV, AIFF, Ogg Vorbis, or Opus):

kliptrack some_music_file.flac

If you get an error, no sound, sound from a differnt output than you want, or low-quality sound, you may need an -output parameter. Use the klipdevices List available alternatives with:

klipdevices

If no devices are listed, you may have to give yourself permission to access audio devices. On many Linux systems, you need to be a member of the audio group, which you can fix with:

sudo usermod -a -G audio myusername

When you verified that you can play audio, you are ready to configure your Klipspringer hub.

Details for more esoteric configuration

Options for installation of third-party runtime executables Java, Node.js, and VLC.
Control where make install places files with build parameters.
Use a infrared remote control or keyboard to control server playback.

Un- or reinstalling

The following steps can be used to uninstall Klipspringer or to reinstall it in a new version or with a new configuration.

If you are running the Klipspringer hub service with systemd, first stop and disable it:

sudo systemctl stop klipspringer-hub.service
sudo systemctl disable klipspringer-hub.service

Remove the directory of any previous installation under /usr/local/lib:

sudo rm -r /usr/local/lib/klipspringer-*

If you are reinstalling, your system is now ready for a new make install. After that you can enable and start the systemd daemon again.

If you are completely removing Klipspringer in an operating system with systemd, you may also want to delete the user klipspringer-hub and the group with the same name (which are created for the sole purpose of running the Klipspringer hub as a service) and the systemd service script. Also, you may want to remove the /var/log/klipspringer directory. The Makefile produced by ./configure has an uninstall target that can be used to take care of all this with

sudo make uninstall

Notes

The exception would be if you are only interested in using the Klipspringer hub for dispatching VLC sources, without any of the audio playing and capturing capabilities that Klipspringer is primarily intended for. In this case, you only need VLC and Node.js.