Installing Subsample

By the end of this chapter, Subsample is installed on your computer, and it can name every audio and MIDI device you have.

Subsample has no window of its own. You set it up in text files and run it from a terminal, so installing it means typing a few commands, and this chapter gives every one of them.

What you need

• Linux or macOS. On Windows, Subsample runs inside WSL2, Microsoft's way of running Linux on Windows, and Microsoft's guide installs it. The Linux steps below then work unchanged, and your audio devices reach WSL2 as Microsoft's guide to connecting USB devices describes.
• A terminal, the window where you type commands: Terminal on macOS, and whichever your Linux desktop gives you.
• uv, which installs Subsample and keeps it apart from everything else on your computer. Its installation page has a one-line installer. It finds a Python for Subsample to run on, and fetches one if your computer has none that will do.

Your audio interface and your MIDI controller can wait: installing needs neither.

What your system needs first

Subsample is fetched from GitHub with Git, and some of the libraries it uses are compiled on your computer as it installs, which needs a compiler, Python's own headers and a few development packages. It also calls on two programs of your system's: PortAudio, which reaches your sound card, and Rubber Band, which shifts pitch and stretches time. Install them with your system's package manager.

On Debian and Ubuntu:

Example not checked: it is not run when this site is built.

$ sudo apt install git build-essential python3-dev pkg-config portaudio19-dev libasound2-dev libjack-jackd2-dev rubberband-cli

On Fedora:

Example not checked: it is not run when this site is built.

$ sudo dnf install git gcc-c++ make python3-devel pkgconf-pkg-config portaudio-devel alsa-lib-devel jack-audio-connection-kit-devel rubberband

On macOS, with Homebrew, where the compiler and Git come with Xcode's command-line tools:

Example not checked: it is not run when this site is built.

$ brew install portaudio rubberband

A sound server, on Linux

On Linux, PortAudio looks for a sound server as Subsample starts, and without one it stops Subsample with OSError: [Errno -9999] Unanticipated host error, even though Subsample never asked for JACK. A Linux desktop runs one already, PipeWire, and you can skip to the next section.

A server with no desktop, such as Ubuntu Server, has none. Install PipeWire and start it:

Example not checked: it is not run when this site is built.

$ sudo apt install pipewire pipewire-alsa pipewire-jack pipewire-pulse wireplumber
$ systemctl --user enable --now pipewire pipewire-pulse wireplumber

On a machine nobody logs in to, sudo loginctl enable-linger "$USER" keeps it running without a login.

Start Subsample with pw-jack in front of it, as pw-jack subsample, and it starts cleanly. Plain subsample works too, and prints a few harmless lines saying that a JACK server is not running. macOS needs none of this section.

Subsample

Install Subsample as a tool, with uv:

Example not checked: it is not run when this site is built.

$ uv tool install "subsample @ git+https://github.com/simonholliday/subsample@v0.6.7"

That line installs the release this guide is checked against, from Subsample's repository on GitHub, and puts one command on your PATH: subsample. The name subsample on the Python Package Index belongs to another project, so install from the line above rather than by name.

If your terminal cannot find subsample afterwards, uv tool update-shell adds uv's folder to your PATH, and a new terminal finds it.

Check that it works

Ask Subsample which devices it can see:

Example not checked: it is not run when this site is built.

$ subsample --list-devices

It prints three lists: your audio inputs, your audio outputs and your MIDI inputs. Above each list is the setting that one of its names goes in, and later chapters use them when Subsample first records and plays. Where it cannot open a MIDI system, as on Linux with no ALSA sequencer, it says why in place of the MIDI inputs, and what to do about it.

If it stops with Unanticipated host error on Linux, no sound server is running: see the section above.

With Subsample installed, the next chapter makes the folder that everything you record and play lives in.