Skip to content

Commit bd316d3

Browse files
samaaronsamaaron
committed
Docs - simplify the Pi build instructions
@rbnpi - these instructions are very valuable, but I don't think this is the appropriate place for such detail. I think we should consider either an additional 'advanced deb building' document, or a long post on in_thread which we could link to for those that want the additional detail you're offering. I actually think that the Pi build instructions are simpler than ever now and it was nice to be able to remove the annoying elixir/cmake stuff.
1 parent f478e7a commit bd316d3

File tree

1 file changed

+68
-228
lines changed

1 file changed

+68
-228
lines changed

‎BUILD-RASPBERRY-PI.md‎

Lines changed: 68 additions & 228 deletions
Original file line numberDiff line numberDiff line change
@@ -1,270 +1,110 @@
11
# Building the Latest Sonic Pi on Raspberry Pi
22

3-
## BUILDING SONIC-PI 4.5 ON RASPBERRY-PI BOOKWORM OS 64Bit
3+
Hello there lovely Raspberry Pi user - welcome to our build instructions.
44

5-
These instructions are specific to building version 4.5 of Sonic Pi to run on a 64bit version of RaspberryPi Bookworm OS
6-
This version was released on October 10th 2023. Either the version with Desktop or the version with Desktop and Recommended Software.
75

8-
It will NOT work on the 32 bit versions, or on previous versions of Raspberry Pi OS
6+
### TLDR
97

10-
The built application will run on P3, Pi4, P400 or Pi5 models
11-
12-
Because it is rather different from previous builds I have included a lot of extra information on the usage of this version over and above the mere building which is fairly straghtforward if somewhat slow.
13-
14-
## Introduction
15-
16-
This version differs from previous ones in two main respects respects. First it use Qt6 which is available on the new OS rather than Qt5, and, since the Mac and Windows versions now use Qt6, this is now flagged as a requirement for future versions.
17-
18-
Secondly it runs under Wayland which is the default screen display system, and uses pipewire for routing the audio output, which again is default on the new OS
19-
20-
## Preparation to build
21-
22-
Download the sonic-pi source version tagged v4.5.0 either by direct download or by cloning
23-
eg
8+
If you're already familiar with the terminal and running shell scripts,
9+
etc., you can fetch, build and start Sonic Pi with the following:
2410

2511
```
2612
git clone https://github.com/sonic-pi-net/sonic-pi.git
2713
cd sonic-pi/app
28-
git checkout v4.5.0
29-
```
30-
Then load in the required packages to support the build
31-
```
32-
sudo apt update
33-
sudo apt-get install -y build-essential git libssl-dev ruby-dev elixir erlang-dev erlang-xmerl qt6-tools-dev qt6-tools-dev-tools libqt6svg6-dev libqt6opengl6-dev supercollider-server sc3-plugins-server alsa-utils libasound2-dev cmake ninja-build pipewire-jack libspa-0.2-jack qt6-wayland libwayland-dev libxkbcommon-dev libegl1-mesa-dev libx11-dev libxft-dev libxext-dev qpwgraph compton
14+
./pi-setup.sh
3415
```
35-
One feature in the build will NOT work at present under Wayland. That is the opacity slider which governs the translucency of the main window. If this is an issue for you, at present it can be worked round by changing the OS to run using X11 and Openbox Window Manager, in which case it will work. Details of how to do this are shown later.
3616

37-
## The build process
17+
Then close the terminal and open a new one and follow with:
3818

39-
This is simply achieved by running the script below in the app directory
40-
`./pi-build-all.sh`
41-
This will take quite a long time to complete (approx 1hr in a Pi400 but hopefully it will be quicker on a Pi5). If you want you can run the four scripts it contains separately, in which case be sure to add the flag -n with the first two.
42-
43-
Once the build has completed you can do an initial test to see if it works. It is located in a build directory inside the app directory. Frommyuour terminal in teh app directory type:
4419
```
45-
build/gui/qt/sonic-pi
20+
cd sonic-pi/app
21+
./pi-build-all.sh
22+
./build/gui/qt/sonic-pi
23+
4624
```
47-
All being well this will start Sonic Pi running, and you can test it by putting some code in the buffer window and pressing run. eg `play 72` or perhaps loading an example typing `load_example :compus_beats` and then pressing run twice, the first time to load the example and the second time to start it running. All being well you should hear sounds coming from your hdmi monitor speakers.
48-
If you do NOT hear anything, perhaps because you don't have sound built in to your hdmi monitor, then you can check what is going on as follows. First see if there is activity on the Sonic Pi scope window. If you can see "sound" traces there that is great. It probably means that Sonic Pi is running, but just not connected to a sound output device.
4925

50-
In order to help, you can use a program which was installed with Sonic Pi called qwpgraph. You can access it from the Sound Section of the Pi Main Menu
51-
The first time you open it with Sonic Pi running you will see rather a mess of various blocks and wires jumbled up on the screen. We are interested in the green ones which relate to audio connections. Zoom the graph window to full screen, and move the blocks around by dragging the grey bodies of the blocks (NOT the coloured bits in the blocks) so that you untangle any connecting wires. I usually align the output audio blocks with ports marked playback_FL and playback_FR to the right hand side and any blocks marked out or capture on the left. Yuu can move midi blocks coloured red or purple to the bottom out of the way, as well as any cyan coloured blocks. Hopefully you will see one block named SuperCollider with green outputs SuperCollider:out_1 and SuperCollider:out_2 These should have wires connecting them to a block "Built in Audio Digital Stereo..." If there are no wires connected to the block, or if you don't have audio on your monitor, then you should see a block representing your current audio device, either one for headphone output (on a Pi4 or Pi3) or one representing a usb audio device you have plugged in, or one representing a bluetooth speaker or headphones. You can connect SuperCollider by dragging a wire from the SuperCollider:out ports to each of the desired device input ports.
26+
Note this requires at least the 64bit version of RaspberryPi Bookworm OS - released on October 10th 2023. The built application will run on P3, Pi4, P400 or Pi5 models.
5227

53-
If you can see the SuperCollider block but you cant see any playback devices, then it is possible that your Pi OS has been switched to work with pulseaudio rather than pipewire. This is done using the command line file raspi-config which you can open in a terminal typing `sudo raspi-config` In teh resiulting screen you want to select option 6 Advanced Options followed by A7 Audio Config. Select the option pipewire then select OK. Select Finish. You need to reboot the machine to reinitialse it.
28+
### Installing vs Building
5429

55-
If you did't see any activity on the Sonic Pi scope trace and there is no SuperCollider icon in the qpwgraph screen, then something is amiss. Check that the build script completed without any error shown (warnings are ok and can be ignored). Quit and check the logs
30+
These instructions are for people wanting to build/compile their own
31+
version of Sonic Pi. If you're just looking to install and run it you
32+
can download our latest binary deb from the Sonic Pi website here:
33+
https://sonic-pi.net/#rp
5634

57-
## Making things easier
35+
However, if you want to use the absolute latest development version or
36+
get involved with modifying and changing the source code, you'll need to
37+
build things yourself and hopefully this document will help you do just
38+
that.
5839

59-
It is rather tedious finding the start command in the build folder and you can produce a leaner portable version of Sonic Pi by extracting just what is needed from the build process as follows.
40+
OK, so just to get you prepared, we're going to do a few things:
6041

61-
with your terminal window still open in the sonic-pi/app directory, first produce a release version by typing
62-
```
63-
./linux-release.sh
64-
```
65-
When this has completed (it will take some 30-40 seconds) you will see a message saying
42+
1. Clone Sonic Pi's source code using git.
43+
2. Fetch all the development dependencies
44+
3. Initiate the build by using a shell script.
45+
4. Start your new Sonic Pi app.
6646

67-
app/build/linux-dist is now ready for packaging: in the terminal type:
68-
```
69-
ls build/linux
70-
```
71-
and you will see three folders: app bin and etc These comprise a relocatable install of Sonic Pi which can be copied anywhere you wish on your computer. They will still leave the original build structure, which acts as an insurance backup. I suggest you move the linux_dist folder perhaps to your desktop and then rename it whatever you wish: for example
72-
```
73-
mv build/linux-dist ~/Desktop/my-sonic-pi
74-
```
75-
Finally you can now start your sonic-pi from the desktop graphical environment.
47+
All of these steps will require the terminal which can be found by
48+
clicking on the Raspberry Pi logo and then Accessories -> Terminal.
7649

77-
double click the mysonic-pi icon
7850

79-
double click the bin folder
51+
### Notes
52+
53+
* If you have any issues building Sonic Pi on Raspberry Pi OS please
54+
open up an issue on GitHub and we'll try our best to assist you:
55+
https://github.com/sonic-pi-net/sonic-pi/issues
56+
* These build instructions assume you're running the latest 64bit version
57+
of Raspberry Pi OS based on Bookwork released in October 2023. You may therefore need to update your distribution before continuing.
8058

81-
double click the icon sonic-pi
8259

83-
You will see a popup window with options
60+
## 1. Get the Sonic Pi Source Code
8461

85-
Execute, Execute in Terminal, Open, Close
62+
The first thing we need to do is to grab a copy of Sonic Pi's source code.
8663

87-
For a first run, to check all is well, choose Execute in Terminal. (Subsequently if all goes well you can choose Execute)
64+
The easiest way of getting this is to clone from GitHub
65+
into a local folder such as `~/Development/sonic-pi`:
8866

89-
## Other useful information
67+
```
68+
git clone https://github.com/sonic-pi-net/sonic-pi.git ~/Development/sonic-pi
69+
```
9070

91-
You will notice that the Sonic Pi splash screen only appears on the first run after you have booted your Pi. This is a known problem whose cause has been identified, but has not yet been solved. Be patient and Sonic Pi will still launch.
71+
By default this will check out the `dev` branch which contains all the
72+
most recent development work. If you'd like the latest stable release
73+
you'll need to checkout the `stable` branch with `cd
74+
~/Development/sonic-pi && git checkout stable`
9275

93-
Getting transparency to work. You need to configure your Pi so that it is not running under Wayland. To do this access raspi-config from a terminal window with `sudo raspi-config` Select "6 Advanced Options" followed by "A6 Wayland". Then select "W1 X11 Openbox window manager with X11 backend". Select "OK", confirm the option and the select the reboot option. When your Pi restarts Sonic Pi will behave the same, but you will find that the transparency slider works. However you will lose some of the nice features of Wayland. You can reverse the process by re-running raspi-config and selecting option "W2 Wayfire Wayfire window manager with Wayland backend".
76+
From now on these instructions will assume you're in the `sonic-pi`
77+
directory. For example, if you cloned into `~/Development/sonic-pi` you
78+
can change into this directory with:
9479

95-
Setting up an easier method to switch audio devices. Although qpwgraph is fine for switching the output of Sonic Pi, I have written a ruby script which will run on Sonic Pi and which you may like to install in the Sonic Pi init.rb file which is located in the folder `.sonic-pi/config` in your pi home folder. You can navigate to this file from the file manager and open it with the text editor or geany programmer's editor. Copy the code below and paste it into the file.
9680
```
97-
98-
#functions to aid connecting and disconnectiog SuperCollider under pipewire
99-
define :getCurrentData do
100-
#first input ports
101-
inputs = `pw-link -iI`.lines
102-
set :hdmiL,inputs.grep(/hdmi.*playback_FL$/).first.to_i
103-
set :hdmiR,inputs.grep(/hdmi.*playback_FR$/).first.to_i
104-
set :usbL,inputs.grep(/usb.*playback_FL$/).first.to_i
105-
set :usbR,inputs.grep(/usb.*playback_FR$/).first.to_i
106-
set :bluezL,inputs.grep(/bluez.*playback_FL$/).first.to_i
107-
set :bluezR,inputs.grep(/bluez.*playback_FR$/).first.to_i
108-
set :avJackL,inputs.grep(/audio.*playback_FL$/).first.to_i
109-
set :avJackR,inputs.grep(/audio.*playback_FR$/).first.to_i
110-
#now output ports
111-
outputs = `pw-link -oI`.lines
112-
scOutPorts=[]
113-
16.times do |i|
114-
scOutPorts[i] = outputs.grep(/SuperCollider:out_#{i+1}$/).first.to_i
115-
end
116-
set :scOutPorts,scOutPorts
117-
#now get all current links ids
118-
links = `pw-link -lI`.lines
119-
#extract SuperCollider:out links
120-
linkOutputs=links.grep(/-.*SuperCollider:out/)
121-
#extract id of each of these links to scLinks
122-
scLinks=[]
123-
linkOutputs.length.times do |i|
124-
scLinks[i]=linkOutputs[i].to_i
125-
end
126-
set :scLinks,scLinks
127-
end
128-
129-
define :displayCurrentID do
130-
#update current data
131-
getCurrentData
132-
#display current link id#
133-
puts "Current data. Note: a 0 signifies no ID found"
134-
puts "hdmi L and R",get(:hdmiL),get(:hdmiR)
135-
puts "usb L and R",get(:usbL),get(:usbR)
136-
puts "avJack L and R",get(:avJackL),get(:avJackR)
137-
puts "bluez L and R",get(:bluezL),get(:bluezR)
138-
puts "sc output ports (16 max)",get(:scOutPorts)
139-
puts "current SuperCollider output link Ids2",get(:scLinks)
140-
end
141-
142-
#display the data
143-
displayCurrentID
144-
145-
###################################################
146-
#function to connect or disconnect SuperCollider
147-
define :connectStereo do |output,input,type=1|
148-
#puts "data",output,input,type
149-
portlist=get(:scOutPorts)
150-
case output
151-
when :usb
152-
if get(:usbL) == ""
153-
puts "not available"
154-
return
155-
end
156-
o1=get(:usbL);o2=get(:usbR)
157-
when :hdmi
158-
if get(:hdmiL) == ""
159-
puts "not available"
160-
return
161-
end
162-
o1=get(:hdmiL);o2=get(:hdmiR)
163-
when :avjack
164-
if get(:avJackL) == ""
165-
puts "not available"
166-
return
167-
end
168-
o1=get(:avJackL);o2=get(:avJackR)
169-
when :bluez
170-
if get(:bluezL) == ""
171-
puts "not available"
172-
return
173-
end
174-
o1=get(:bluezL);o2=get(:bluezR)
175-
#puts "bluez",o1,o2
176-
else
177-
puts "not available"
178-
return
179-
end
180-
if input == ""
181-
puts "input not available"
182-
return
183-
end
184-
if portlist[input-1] == "9" or portlist[input] == "0"
185-
puts "outputs not available"
186-
return
187-
end
188-
i1=portlist[input-1];i2=portlist[input]
189-
action=["pw-link -d ","pw-link -L "]
190-
cmd = action[type]+i1.to_s+" "+o1.to_s
191-
puts cmd
192-
system(cmd)
193-
cmd = action[type]+i2.to_s+" "+o2.to_s
194-
puts cmd
195-
system(cmd)
196-
end
197-
198-
#function to delete all SuperCollider output connections
199-
define :deleteSCout do
200-
getCurrentData
201-
links=get(:scLinks)
202-
return if links.length==0
203-
links.each do |n|
204-
cmd= "pw-link -d #{n}"
205-
puts cmd
206-
system(cmd)
207-
end
208-
end
209-
210-
###########################################################
211-
#four functions that let you easily swap the main Sonic Pi output audio routing
212-
213-
define :gohdmi do
214-
getCurrentData #they may have changed
215-
deleteSCout
216-
connectStereo :hdmi,1,1
217-
end
218-
define :gousb do
219-
getCurrentData#they may have changed
220-
deleteSCout
221-
connectStereo :usb,1,1
222-
end
223-
define :gobluez do
224-
getCurrentData#they may have changed
225-
deleteSCout
226-
connectStereo :bluez, 1,1
227-
end
228-
define :goavjack do
229-
getCurrentData#they may have changed
230-
deleteSCout
231-
connectStereo :avjack, 1,1
232-
end
233-
234-
#PLACE BELOW WHERE YOU WANT SONIC PI TO CONNECT WHEN IT STARTS UP
235-
#IF YOU HAVE MORE THAN ONE USB OR BLUETOOTH IT WILL CONNECT THE FIRST ONE IT FINDS
236-
# choose from gohdmi, gousb, goavjack or gobluez (no audiojack on Pi5 or Pi400)
237-
gohdmi
238-
```
239-
With the script in the init.rb file, then all of its commands will be available for use in Sonic Pi once it has booted, so as well as being able to change the default sound device specified in the last line of the init.rb file, you can change the audio output easily whist Sonic Pi is running. Merely choose one of `gohdmi`, `goavjack` `gousb` or `gobluez` and it will connect Sonic Pi to the relevant output, provided of course that it is available on your system. If not, there will be no audio output and you will have to connect to an existing device. Note if you have more than one device of the same type, eg two audio usb devices, the command will choose one of them depending upon which port id is discovered first. To differentiate you may have to use `qwpgraph` instead, although you could temporarily remove the one you don't want to connect to, run the gousb command, then plug it in again. The command `connectStereo` has three parameters the third controls whether a connection is made (1) or disconnected (0) so you can you to make a connection without disconnecting others, or disconnect a connection without affecting anything else using this. This allows connection to multiple devices, although this can produce scratchy noises if they are ill-matched in characteristics. You can also print details of the current port IDs using the command `displayCurrentID`
240-
241-
The Raspberry Pi volume control: This controls the volume of the device to which it is currently connected, (shown by right clicking its icon). To control the volume of a different audio device you must select it with this volume control first. Another thing to note is that the audio output of other applications may switch automatically to follow the current device selected by the volume control, whereas the switching of devices for Sonic Pi is independant of that. Also the volume control will only control the volume of the device it has currently selected. If you find this tedios to use you can install the package pavucontrol, which is designed to work usually with pulseaudio, but the output devices tab of this control will let you adjust the volume of any of the avaliable output devices
242-
243-
## Adjusting samplerate and buffer for scsynth via pipewire settings ##
244-
245-
New setings have been added to the audio_settings.toml file in the .sonic-pi/config folder in your hime directory This will be created on your first sonic pi run. YOu can edit ait and chnage the defauilt values in the Linux Audio-Pipewire settings from the default. In particular you may find that a Pi4 or Pi400 may work well on lower settings for linux_pipewire_buff_size maybe 512. A Pi5 may be ok on 256, but I don't have one to tst this yet! Most devices work at 48000 for the Linux_pipewire_sample rate but you could try 96000 perhaps. Both these settings will affect latency.
246-
247-
## Portable Sonic Pi
248-
249-
As mentioned previously the linux_dist folder (copied to the desktop and renamed) can run in any location. It is in fact the basis of the binary deb file created for this version. If you have another micro SD card with the same OS installed, you can fairly easily transfer a working copy of Sonic Pi to it. I suggest that you compress the folder by opening a terminal on the Desktop and typing:
81+
cd ~/Development/sonic-pi
25082
```
251-
tar -zcf mysonic-pi.tar.gz mysonic-pi
83+
84+
## 2. Fetch the Development Dependencies
85+
86+
Now we're ready to fetch all the development dependencies.
87+
88+
```./app/pi-setup.sh
25289
```
253-
Then transfer it to your new sd card Desktop (could use a USB stick for this). Once there uncompress it
90+
91+
## 3. Running the Build
92+
To start the build process run the following command (which will likely take some time - approx 1hr on a Pi400):
93+
25494
```
255-
tar -zxf mysonic-pi.tar.gz
95+
./app/pi-build-all.sh
25696
```
257-
In order to get it to run you just need to install the set of runtime packages required on the second card. Although there seem to be more of them than for the build set of packages, they actually take up less space.
97+
98+
## 4. Start Sonic Pi
99+
100+
Finally, you can run your newly compiled Sonic Pi app with the following command:
101+
258102
```
259-
sudo apt install -y libqt6core6, libqt6dbus6, libqt6gui6, libqt6network6, libqt6opengl6, libqt6openglwidgets6, libqt6qml6, libqt6qmlmodels6, libqt6quick6, libqt6waylandclient6, libqt6waylandcompositor6, libqt6waylandeglclienthwintegration6, libqt6waylandeglcompositorhwintegration6, libqt6widgets6, libqt6wlshellintegration6, libqt6xml6, qt6-qpa-plugins, qt6-translations-l10n, qt6-wayland, qt6-gtk-platformtheme, ruby, supercollider-server, sc3-plugins-server, libspa-0.2-jack, pipewire-jack compton qwpgraph
103+
./app/build/gui/qt/sonic-pi
260104
```
261-
You then should have a fully working second Sonic Pi
262105

263-
### Notes
264106

265-
* If you have any issues building Sonic Pi on Raspberry Pi OS please
266-
open up an issue on GitHub and we'll try our best to assist you:
267-
https://github.com/sonic-pi-net/sonic-pi/issues
268-
* Good luck and please share your new live coding adventure with us over on:
107+
Good luck and please share your new live coding adventure with us over on:
269108

270109
https://in-thread.sonic-pi.net
110+

0 commit comments

Comments
 (0)