Complete Minimal Setup Instructions


Since many people have asked about my set up, and I recently helped someone replicate it…I thought I’d write up the full process.

While the Pisound parts are nicely documented on this site… the bits beforehand… especially for creating a minimal, headless (mostly) set up, are scattered all over the web. So I put together a complete step-by-step guide:

Still has some holes and some editing needed. Love to know what people think.

Prebuilt Pure Data image

Some notes about the Pisound parts:

  1. I include alternate installation instructions for Puredata and SuperCollider because the pisound-config scripts end up installing way too much. (Including a PDF renderer!!)

  2. After and installing Puredata… hitting the button is rather unsatisfying! It tries to run the _main.pd script inside GarageBeat… which doesn’t work launched like that.

  3. Would this sort of complete, step-by-step be a useful addition to the standard documentation site for Pisound? I could re-format it for that and submit a pull request if folks think it belongs there.


cool stuff… and a really useful write up, thanks for putting in the effort to document.

you might want to have a look at the Norns on a Raspberry PI, as ive been doing something similar using the norns image, so that might have some other things to try.

particularly, you might want to consider building a custom kernel, to add full preemptive

also i would suggest explicitly setting the cpu governor to performance

there are also a bunch of services you will probably want to disable.

I think this would be a great topic for blokas @Pranciskus to get involved in.
i.e. head toward and minimal and high performance system

Ive noticed with my Norns installation, the PiSound does not appear to performing as well as the Norn hardware (i don’t have a norn to check though), which i think theoretically it should.
so if we could narrow this down , on a minimal setup, then i think we might all learn something on how to get optimal performance from pisound.

note: we are trying for low latency here, im at -p 256 -n 3 and at -95 priority, but we want to be down to -p 128 !

(for my part, i need to go look at the modep install, see if its doing anything im not :slight_smile: )


I haven’t seen the need for a custom kernel yet: I’m running jackd with -p 64 -n 2 and see no xruns when playing live! Perhaps my SC and Pd patches aren’t that huge… but they aren’t trivial.

I don’t see any services being disabled in either your or the Norns’ setups. In any case, with given the minimal packages I have installed, pstree reveals not very much is running! I didn’t yet find a nice way to have X not run at all when headless, but it is running nothing but login widget - and takes fractions of a % of CPU.

Interested to hear what you learn from modep - as I don’t have that set up, and it seems tuned.


Thanks a lot for this! Since I keep having weird problems with my setup I’ll probably try this when I have a spare evening.
Actually it would be really cool if Blokas could offer an “official” tuned Raspbian image for Pisound, so hopefully maybe they can take a few clues from this.

Do you mean that the button is “broken” when following your instructions? Not that it would bother me much, since I now have the app to deal with that.

And another question. Theoretically I can also just hook the rpi up to a display and keyboard/mouse to do all the initial steps until SSH and VNC works, can’t I?

  1. No, the button system itself is working just fine. The problem is that the sample patches that are now in supplied in /usr/local/puredata-patches have a .pd file that matches the search the button script is using. But that file is _main.pd which is part of GarageBeat, but not the file that actually runs it. So if you press the button, it launches this file, which doesn’t do anything on its own.

  2. Yes, if you have a display & keyboard for the Pi, you can skip or simplify some of the steps. My aim was to do this all headless. (Because I don’t have a spare HDMI display and keyboard at my desk!)


Thanks alot for this. As someone new to the whole Linux arena and puredata in general this kind of a post is very useful. nice to have all thr required info located in one place rather than scattered around the place as you have said.

I notice you are using realvnc in your setup and you haven’t specifically mentioned disabling your encryption, this seemed to be causing me a lot of performance issues strange that you haven’t encountered the same. perhaps it was something to do with the bloated build I installed?
I’ll try your slim version when I get a chance . Thanks again for going to this effort.


Oh I see! Easy fix, just rename the file and update the name in the yaml file.

That totally makes sense, since the rpi realky shines as a headless computer system!


actually they kind of do…

their modep is forked off of RPi-Distro/pi-gen
if you want to build an image this is a really great way of doing it.

basically blokas have taken out a number of packages, and substituted in the modep ones, if you look at how its structured its really easy to swap in and out packages that you need.
(I.e. go back to RPi-Distro/pi-gen if you need a package it has, but modep has dropped)

its a bit like buildroot but much simpler.

the advantage of this approach is you dont need users do x, y, z - the whole thing is automated, so you ‘click a button’ and out pops your new image :slight_smile:

probably the missing ‘step’ there is how you use this, as im sure many are unfamiliar with docker etc.


I suppose my point was that it would be nice if the example patches (by way of @Patrick_Pagano, if I’m not mistaken) that are installed with pisound-ctl would work with pisound-btn.


I think I was told they are working on the BTN but it currently has nothing to do with Pd FWIW. I think it turns on the wireless etc but pretty sure I was told it does not work with pd And is a system thing not in my powers yet :stuck_out_tongue_closed_eyes:


The button has always launched a PureData patch that it goes hunting for.
It hunts on all the mounted USB drives… and then in /usr/local/puredata-patches, hence finding the patches shiped with pisound-ctl.



i don;t really use that yet probably because i am on IOS and still excited for the impending IOS app but i guess what i meant to share is that the BTN is not addressed inside patches
at this point. Are you saying that the button is NOT launching patches any longer??
I am confused about what the issue/non-issue is

let me know how i can help :slight_smile:


@Patrick_Pagano: I’ll check that out, though I fear it might be a bit above my current time availability. While it seems easy to make an image with RPI-Distro/pi-gen it still requires that you know what you want to be on the image, which is probably not such a trivial task. Or can I just use the MODEP image and install the Pd / Sc things in it? Still, mzero’s setup looks simple enough for me, so there’s no real need for a ready-to-go image now.

I see what the issue is now. Since the location of the Pd patches used by the app are in the search paths of the button script, that creates some confusion if there’s one or more patches names main.pd there.
In fact the app supports just dropping a patch in the folder without the accompanying blokas.yml file, in which case you need to name it main.pd. But of course since the default Pd-button-action is scripted in a way that is expects only one main.pd file to be there, how can it know which one you want to pick if there’s more than one?

Yes that would be nice for people who do not want to use the app. But as mentioned above, how can it be done?
One possible solution would be to allow Pd files to be names sequentially (main1.pd, main2.pd) so with each press the script would close the current patch and load the next one, in the order as they are numbered.
But I guess I’m derailing the thead here, am I?


@mzero Great write up! This is definitely something that we could include in our documentation.

What’s making it difficult to have a generic image for use with Pisound is the vast amount of options for the way you may want to make use of Pisound, and a lot of them are in conflict with one another.

It makes total sense to have MODEP as an image, as it has a single purpose to run the MOD software, and we don’t recommend using it for something else. What I do myself, is keep a few sd cards with specific images, and swap as needed. Adding Pure Data into MODEP would not be trivial, because MODEP uses JACK as the audio backend, so Pure Data has to be configured appropriately, and also having a GUI would make sense, for patch editing, so the image would grow significantly.

That’s easy to fix, the scripts for installing PD and SC are here, should we add --no-install-recomends to both and gem package to PD?

We are aware of this issue and the file will be renamed after the next update is released.

Clicking the button once searches for the first main.pd file it can find, looking in USB storage first, then in /usr/local/puredata-patches on the SD card.

As there is no real possible interaction to understand what’s going on and which patch you’re on, it makes sense to launch the first one found. So to switch between patches, you should be able to swap one USB stick with another one, containing a different patch. (double click the button to stop the patch and safely unmount the storage)

You may customize the button to launch patches based on the number of clicks (similar to MODEP loading a specific pedalboard layout), as @oootini did here: Adding more button clicks


That totally makes sense, thanks for elaborating on that.
But why not offer a Puredata oriented image? Something intended to work out-of-the box with the App/button? Right now there’s many rough corners to the current rpi/pisound experience for people with medium-level linux/rpi skills. The main issues I have encountered so far are: how to properly set things up so it works as a tuned headless system (though mzero just solved that), how to get samba working for file exchange (or is there any other solution?), plus various small tweaks, which have taken me hours to figure out. I did of course know that I was in for a bumpy ride when getting a rpi+pisound, and it’s not really something I criticize (there’s plenty of options out there if I had wanted something that just works out of the box), but after trying out MODEP it really makes me wonder, why there is not such a thing for the basic Puredata use. Especially since that’s what seems to be your focus anyway.


We consider the “Pure Data” image to be pretty much Raspbian Lite / Desktop with ‘’ executed and sudo pisound-config used to install PD, SC, and/or other software. We will likely produce a ready made image some time soon after releasing the app update.

Could you elaborate a bit on what those were? When building an image with PD preinstalled it’s kind of difficult for us to know where to stop with the system customization. :slight_smile:

In general, that’s a lot of good feedback for us, we will be updating the documentation with various tidbits of good stuff to know when working with Pisound and Linux, like sharing files between your PC and RPi (my favorite is scp command line tool (part of ssh) and WinSCP for Windows which allows browsing RPi just like an FTP server, there must be equivalents for other desktop OSes).

I will open a separate topic for Pure Data prebuilt image feature suggestions. [edit: here it is: Prebuilt Pure Data image]


Yeah I guess it’s not easy.
Let me backtrace my steps and see which were the issues. I can’t remember them in detail except for the samba thing I mentioned earlier. Samba does seem to be kind of weird to set up on linux in general, it always requites several tries for me to get it to run (at least in conjunction with MacOS computers having to access the share). No idea why. The steps I find in all the guides online never work (i.e. the share is never visible when looking for network shares). Eventually it will work, but usually it implies doing stuff that you shouldn’t and I can’t figure out what the pattern is.

Didn’t know about that, but I’m still learning, thanks a lot for the heads up!

Yes good idea! thanks!


I did make a new Raspbian SD using your guide and it worked like a charm, so huge thanks again!
I did skip the initial part and went for the easier “burn with Etcher + do the initial setup directly on the box instead of via SSH”, but your guide was still super helpful in getting the right things installed and avoiding the useless ones.