1Building SuperCollider on Raspberry Pi
2======================================
3
4SuperCollider can be built with the IDE and Qt GUI components on Raspbian Desktop, or without them on Raspbian
5Desktop or Raspbian Lite. However, the project cannot be compiled with the QtWebEngine library, which means that the
6help browser in the IDE, and the HelpBrowser and WebView classes in sclang, are unavailable.
7
8Build requirements
9------------------
10
11* Raspberry Pi 2, 3 or 4 (Raspberry Pi 0 and 1 will also work, but note that compiling will take a _long_ time)
12* SD card with [Raspbian Desktop](https://www.raspberrypi.org/downloads/raspbian) Stretch or Buster, or Raspbian Lite for a GUI-less build
13* Router with Ethernet internet connection for the RPi
14* For a GUI build: screen, mouse and keyboard
15* For a GUI-less build: an empty dummy file called `ssh` on the root level of the SD card, to enable ssh, and a laptop connected to the same network as the RPi
16* Optional: USB soundcard with headphones or speakers connected
17
18Building
19--------
20
21### Step 1: Hardware setup
22
231. Connect an ethernet cable from the network router to the RPi
242. Insert the SD card and USB soundcard. For a GUI build, connect screen, mouse and keyboard
253. Connect USB power from a power supply
26
27### Step 2: Update the system, install required libraries
28
29For a GUI-less build, first ssh into the RPi from your laptop by opening a terminal and typing:
30
31    ssh pi@raspberrypi # default password is 'raspberry'
32
33In a terminal, type (or copy-and-paste):
34
35    sudo raspi-config # change password and optionally edit hostname and enable ssh and/or vnc
36    sudo apt-get update
37    sudo apt-get upgrade
38    sudo apt-get dist-upgrade
39
40Install required libraries:
41
42    # For GUI builds:
43    sudo apt-get install libjack-jackd2-dev libsndfile1-dev libasound2-dev libavahi-client-dev \
44        libreadline-dev libfftw3-dev libxt-dev libudev-dev cmake qttools5-dev qttools5-dev-tools \
45        qtdeclarative5-dev libqt5svg5-dev qjackctl
46    # For GUI-less builds:
47    sudo apt-get install libsamplerate0-dev libsndfile1-dev libasound2-dev libavahi-client-dev \
48        libreadline-dev libfftw3-dev libudev-dev cmake git
49
50### Step 3: GUI-less builds only: compile and install jackd (no d-bus)
51
52    cd ~ # or cd into the directory where you'd like to build jack2
53    git clone git://github.com/jackaudio/jack2 --depth 1
54    cd jack2
55    ./waf configure --alsa --libdir=/usr/lib/arm-linux-gnueabihf/
56    ./waf build
57    sudo ./waf install
58    sudo ldconfig
59    cd ..
60    rm -rf jack2
61    sudo sh -c "echo @audio - memlock 256000 >> /etc/security/limits.conf"
62    sudo sh -c "echo @audio - rtprio 75 >> /etc/security/limits.conf"
63    exit # and ssh in again to make the limits.conf settings work
64
65### Step 4: Compile and install SuperCollider
66
67    cd ~ # or cd into the directory where you'd like to clone and build supercollider
68    git clone --recurse-submodules https://github.com/supercollider/supercollider.git
69    cd supercollider
70    mkdir build && cd build
71
72    # For a GUI-less build:
73    cmake -DCMAKE_BUILD_TYPE=Release -DSUPERNOVA=OFF -DSC_ED=OFF -DSC_EL=OFF -DSC_VIM=ON -DNATIVE=ON \
74        -DSC_IDE=OFF -DNO_X11=ON -DSC_QT=OFF ..
75
76    # For a GUI build:
77    cmake -DCMAKE_BUILD_TYPE=Release -DSUPERNOVA=OFF -DSC_ED=OFF -DSC_EL=OFF -DSC_VIM=ON -DNATIVE=ON \
78        -DSC_USE_QTWEBENGINE:BOOL=OFF ..
79
80    cmake --build . --config Release --target all -- -j3 # use -j3 flag only on RPi3 or newer
81    sudo cmake --build . --config Release --target install
82    sudo ldconfig
83
84### Step 5: Set up JACK
85
86    # `-dhw:0` is the internal soundcard. Use `-dhw:1` for USB soundcards. `aplay -l` will list available devices.
87    # Use `nano ~/.jackdrc` to edit jack settings.
88
89    # For GUI builds:
90    echo /usr/bin/jackd -P75 -p16 -dalsa -dhw:0 -r44100 -p1024 -n3 > ~/.jackdrc
91
92    # For GUI-less builds:
93    echo /usr/local/bin/jackd -P75 -p16 -dalsa -dhw:0 -r44100 -p1024 -n3 > ~/.jackdrc
94
95For GUI builds, another way to set up and start jack is to open a terminal and type `qjackctl`. Click 'setup' to
96select soundcard and set periods to 3 (recommended). Then start jack before the SC IDE by clicking the play icon.
97
98Usage
99-----
100
101To use SuperCollider, just open a terminal and execute `scide` (GUI) or `sclang` (GUI-less).
102
103When you boot the server jack should start automatically with the settings in `~/.jackdrc`.
104
105**Done!** See below for other usage notes and tips.
106
107Running a GUI build headless
108----------------------------
109
110If you want to ssh in and start SuperCollider headless, run:
111
112    export DISPLAY=:0.0
113    sclang
114
115sc3-plugins
116-----------
117
118To compile and install sc3-plugins, follow the instructions in the [sc3-plugins README](https://github.com/supercollider/sc3-plugins).
119
120Autostart
121---------
122
123To automatically run SuperCollider code at system boot:
124
125    cat >~/autostart.sh <<EOF
126    #!/bin/bash
127    export PATH=/usr/local/bin:$PATH
128    export DISPLAY=:0.0
129    sleep 10 # can be lower (5) for rpi3
130    sclang mycode.scd
131    EOF
132
133    chmod +x ~/autostart.sh
134    crontab -e # and add the following line to the end:
135        @reboot cd /home/pi && ./autostart.sh
136
137    nano ~/mycode.scd # And add your code inside a waitForBoot. For example:
138        s.waitForBoot{ {SinOsc.ar([400, 404])}.play }
139
140    sudo reboot # the sound should start after a few seconds
141
142Login with ssh and run `killall jackd sclang scsynth` to stop the sound.
143
144Benchmarks
145----------
146
147These are rough benchmark tests. The server should be booted and jackd running with settings: `-P75 -p1024 -n3 -r44100`
148
149Also for comparison it is important to set CPU scaling to 'performance', by running:
150
151    echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
152
153Start sclang or scide and run:
154
155    s.boot
156    {1000000.do{2.5.sqrt}}.bench // ~0.56 for rpi3 headless, ~0.7 for rpi3 scide, ~1.7 for rpi0 headless, ~3.8 for rpi0 scide
157    a= {Mix(50.collect{RLPF.ar(SinOsc.ar)});DC.ar(0)}.play
158    s.avgCPU // run a few times. ~12% for rpi3, ~18% for rpi2, ~79% for rpi1, ~50% for rpi0
159    a.free
160
161With the default cpu scaling (ondemand) these benchmarks perform much worse, but 'ondemand' also saves battery life so
162depending on your application, this might be the preferred mode.
163
164To set 'performance' scaling mode permanently see the "Gotcha..." section of [this StackExchange
165post](https://raspberrypi.stackexchange.com/questions/9034/how-to-change-the-default-governor#9048).
166
167Notes and Troubleshooting
168-------------------------
169
170This applies to both GUI and GUI-less builds above:
171
172* An easy way to burn the zip file (no need to unpack) to an SD card is to use [etcher](http://etcher.io).
173* The internal soundcard volume is by default set low (40). Type `alsamixer` in terminal and adjust the pcm volume to
174  85 with the arrow keys. Press escape to exit.
175* The audio quality of rpi's built-in sound is terrible. Dithering helps a bit so add `-zs` to the jackd command if
176  you are using the built-in sound.
177* If building with `-j 3` stops or returns an error the compiler might just have run out of memory. Try to reboot and
178  run the make command again without `-j 3` or decrease the gpu memory in raspi-config under advanced (set it to 16).
179* If you get `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!` when trying to ssh in, type `ssh-keygen -R
180  raspberrypi` to reset.
181* For lower latency, set a lower blocksize for jackd. Try, for example `-p512` or `-p128`. Tune downwards until you
182  get dropouts and xruns (also watch cpu%).
183* To avoid SD card corruption one should always shut down the system properly and not just pull out the power. When
184  running headless you can either ssh in and type `sudo halt -p`, use a GPIO pin with a button and Python script, or
185  set up an OSC command from within SC that turns off the RPi. See
186  [here](https://github.com/blacksound/VTM/wiki/Raspberry-Pi-Instructions#shutdown-for-raspberry-pi).
187* For the older Raspbian Jessie system use a [previous](https://github.com/supercollider/supercollider.github.io/blob/1f578b5fa71e1acae0ce40d14bc0ef116062093d/development/building-raspberrypi.md)
188  version of these instructions.
189* To quit sclang after starting via the commandline use `0.exit`.
190