Pure Data patch with parameters in the Pisound App



Image found on https://www.pexels.com/photo/multicolored-smoke-1020315/

Goal: Build a simple PD patch demonstrating the different kinds of parameters available and getting them into the App.

Difficulty: Intermediate

Optimized for Headless Use: Yes

Recommended Raspberry Pi Models:

  • Raspberry PI 3B+
  • Raspberry PI 3B

Required Hardware:

  • Pisound
  • Raspberry Pi w/ power supply and micro SD card
  • Windows, macOS or Linux computer to connect via VNC, or monitor, keyboard and mouse to work directly.
  • Android device to run the Pisound App.

Required Software:

Patch Download:

You may download the full patch here: https://patchstorage.com/basic/, but do go through the steps, they contain useful information in case you’d like to develop a patch from scratch.

Step 00: Updating if necessary

Make sure you have 1.03-2 version of the pisound-ctl package, in a terminal, run:

dpkg -s pisound-ctl

it should say:

Version: 1.03-2

If it’s a lower number than that, run:

sudo apt-get update
sudo apt-get install pisound-ctl

and it should upgrade it.

Step 01: Creating the patch files

In this step, we’ll create a set of files as a starting point for a brand new patch. You may find more detailed information on blokas.yml here.

  1. Launch a terminal, or connect via ssh

  2. Execute the following commands:

     cd /usr/local/puredata-patches
     sudo mkdir -p basic
     cd basic
     echo "#N canvas 2 95 450 300 10;" | sudo tee basic.pd
     sudo wget https://community.blokas.io/uploads/default/original/1X/8ea6c9dba43a1dcbf74232635bba1260d0524a62.jpeg -O basic.jpeg
     sudo nano /usr/local/puredata-patches/basic/blokas.yml

    This will create a placeholder basic.pd file, and open blokas.yml for editing, fill out the information and hit ctrl+o to save and ctrl+x to exit:

     name: Basic patch
     author: Giedrius
     entry: basic.pd
     image: basic.jpeg
     description: |
         A demo patch for the controls.
         - simple
         - controls
         - demo

    The file is following YAML syntax and should be self explanatory. The only 2 required fields are ‘name’ and ‘entry’, the rest of the information is used for nice display of the patch in the App.


Step 02: Launch the placeholder patch via the App


Make sure you are connected via VNC or are using monitor, keyboard or mouse with Pisound before launching the patch via the App, otherwise, Pure Data will get launched with ‘-nogui’ option, in that case, you can stop and start the patch again once the graphical environment is up.

Once launched, basic.pd should appear on the top left corner of the screen as an empty Pure Data patch.

Step 03: Get the Virtual MIDI keyboard in the App to appear

If on launching, the patch launched uses either [r notes] or [notein] Pure Data objects, the Virtual MIDI keyboard will be enabled in the App, so let’s create a [notein] object in the patch and relaunch it:

  1. In basic.pd, create [notein] object.
  2. Save now, stopping the patch via the App won’t show confirmation dialog.
  3. Stop and start the patch via the App, to get the Virtual MIDI keyboard to appear.


Step 04: Build a basic patch

Let’s first build a simple patch, and we’ll add in the controls that are visible in the App in the next step.


This patch uses 4 kinds of controls:

Symbol Type Range Description
sound_on bool 0, 1 Sound on / off control
transpose int -12 - 12 Transpose amount of MIDI Note value
volume float 0 - 1 Volume control
middle_c_btn bool / button 0, 1 Plays Middle C (MIDI Note 60) when triggered

The graphical controls in the patch have send/receive symbols set to match the symbol names in the above table, for example the Properties window of Volume looks like this:


Step 05: Adding the controls to the App

Real-time controls and MIDI mapping functionality are implemented using @thetechnobear MEC package. You may find more information on the -rack.json, -module.json, the [monorack] abstraction here.

  1. First we have to pick the name that we’ll use to define the module, it will be needed to name the param definition files and creating the [monorack] object. In our case, we can pick ‘basic’.

  2. Now let’s create the param definition files:

    sudo touch /usr/local/puredata-patches/basic/basic-rack.json
    sudo nano /usr/local/puredata-patches/basic/basic-module.json

    Fill in the parameter data:

        "name" : "basic",
        "display" : "Basic",
        "parameters" : [
            ["bool","middle_c_btn","Middle C",0]
        "pages" : [
            ["pg_main_inv","Main Inv",["middle_c_btn","transpose","volume","sound_on"]]

    This defines the 4 parameters as described above, and puts them in 2 pages, just to demonstrate how to have more than one page of parameters. Keep an eye on the ‘,’ at the end of the lines, JSON syntax is very strict on their placement.

  3. Now let’s get the controls plugin loaded into the patch, to do that, we have to first declare that we’ll be using PD externals from ‘blokas’ subfolder in PD standard externals folder (’/usr/lib/pd/extra’) and afterwards create the [monorack basic] object to load in the parameter definitions:


At this stage, restarting the patch will display the controls in the App, and they will be already usable, because we used [r param_name] and param_name for send/receive symbols in the GUI controls. Hitting the refresh in [monorack] object causes reload of the param definitions file, if it was changed, and there is no syntax errors, the controls should get updated in the Pisound App immediately.


For easier debugging / testing of the patch, we may add [ktrl param_name] objects, in case param_name is a valid parameter, it will automatically set the lower and upper range of the horizontal slider according to what is set in -module.json, as well as shows the display name. In case the param_name was not found, it will show <unknown> instead of the param display name, hinting at a typo or syntax error in -module.json.


Step 06: Rules of thumb for great control integration into a patch

Here’s a few good guidelines to keep in mind when adding controls to patches:

  • The controls should be integrated in such a way that the App or simply [ktrl] objects should be enough to start playing around with the patch.
    • If the patch can be fully controlled using [ktrl] objects, that generally means it will work great with the App too, as long as the pages are defined correctly.
  • If a patch already has GUI controls (like MiniMoog or ArpOdyssey did), working with either the pre-existing GUI controls or [ktrl] objects or the controls in the App should cause the changes to appear in all places, regardless of which input method was used.

This is it!

Once you get the hang of the param definitions file and the [monorack] object, getting controls integrated into new or existing patches will become a pretty straightforward thing to do. To get a better hang of it, you may practice adding controls by retrofitting some of the existing patches with control objects.

Start Here: Pisound Tutorials Index
Using the Knobs With A Pure Data Patch
Patch launching issue via the app
Pisound app - can't import from USB --> collections
[solved] Can't see patch parameters in app
listed #2

split this topic #5

4 posts were split to a new topic: MEC and Orac integration possibilities


I think I’m going to have to find an android device somewhere… :slight_smile:

MEC and Orac integration possibilities