Pure Data Party Publisher

Pd best practices

Sun, 15 Nov 2015 00:00:00 +0000

To fully benefit of all the features of the project you will want to use some custom made abstractions, available to all users. Those abstractions are the core of our system to developp apps, you will find stuff to deal with the beat sharing clock, saving presets, and specific abstractions to interact with a touchscreen or display a list of symbols.

They are all located in the /puredata release folder, and each one has a help patch.

But first let’s talk a bit how to workflow to interface pd with the code hierarchy of the eclipse project.

First you should prefer to work in a project folder, that is to say in the assets folder of a new project in folder named after you app name.

We advise you to create a pd ‘launcher’ patch at the base of your project, to simulate the way it works on android when working on your desktop computer. In the AcidBass example project it is called AcidBass_launcher_desktop.pd, and it looks like this :

TODOC : change path to “puredata” folder ? Yes ! you are right :)

This pd patch is only for use in desktop, and in developpement mode, it is not embeded in your application.

It contains a path to our project folder containing the abstractions listed below.

It also contains a path to the assets/Acid_Bass folder which contains each gui-view of the patch built as an abstraction containing only gui objects. And a core abstraction which contains all the audio, the logic, and the saving system implementation.

This setup will help you to build several gui view stacked in tabs for your app. You can check the ‘how to configure your launcher post’ to learn more about this view system.

How to use multiple views

Sun, 15 Nov 2015 00:00:00 +0000

First in the launcher you have to create a config variable :

 
PdDroidPartyConfig config = new PdDroidPartyConfig();

right after the line :

 
super.onCreate(savedInstanceState);

then we will use this variable to call methods like this config.myCustomisationMethod.

To use the multi-view support we strongly advise to follow the pd best practices mentionned in the Pders Guide.

The best way to benefit from the multi-view feature, is to break your patch into several abstractions. You will probably want to seperate the gui from the audio core, and probably break the gui into pannels as hinted in the post mentionned above.

This is the case in the Acid_Bass project :

AcidBass_core.pd : is the full pd patch. It contains the dsp code, the logic of the sequencer, the clock instanciation, the load and save mechanism instanciation … well pretty much everything except the gui.
AcidBass_audioControls, AcidBass_noteOptions.pd, AcidBass_noteSelector.pd : are each a pannel of the gui views, containing pd gui objects, and custom abstractions. Each object communicates with AcidBass_core.pd via the global pd [send] and [receive] system.

Notice the [declare -path ../../../../pd-party/droidparty-abstractions] object again, in each of those abstractions.

Now in eclipse in your launcher file (ie MainActivity.java) right after the line

  PdDroidPartyConfig config = new PdDroidPartyConfig();

you can begin the instanciation of your views :

 
config.guiPatches.put("Harmony", "Acid_Bass/AcidBass_noteSelector.pd");
config.guiPatches.put("Note Options", "Acid_Bass/AcidBass_noteOptions.pd");
config.guiPatches.put("Audio Controls", "Acid_Bass/AcidBass_audioControls.pd");

This is the code for the gui view, the first argument passed is the name of the view, the second one is the path to the abstraction to be loaded in this view.

Once it is done, you can instanciate your core patch :

 
config.corePatches.add("Acid_Bass/AcidBass_core.pd");

And finally proceed with the launch :

 
PdDroidPartyLauncher.launch(this, config);

Note 1 : It is best to load your gui views before your core patches for initializations issues that will be discussed in more details in the Persist saving system section.
Note 2 : Currently we adivse you not to duplicate gui elements from one view to another as tempting as it may be. This stands more specifically for arrays, as pure-data does not allow you to have multiple arrays with the same name. You can report here if you want to comment on that.

How to use the clock

Sun, 15 Nov 2015 00:00:00 +0000

TODOC

How to save presets

Sun, 15 Nov 2015 00:00:00 +0000

For the saving system we choose to developp our own system, mainly because sssad was very slow when saving arrays with a lot of samples (saving 1s of audio was taking too much time for instance). The system is built to be as simple as possible, and allow to deal with several preset banks - that is to say that you can save your sequencer patterns and synth presets separatly

On the pd side you can check the help patches in /puredata release folder. It relies on the same mechanism as sssad, and it probably cannot do eveything sssad can, but it has pretty much the same limitation and it’s best to know about it … sssad and persist rely on the fact that a single instance of an abstraction will save a value that is received and sent via the messages given as arguments : that means that if you don’t send anything at some point … well, nothing will be saved, and nothing will be restored on load. So the lesson is : ** if you want to save a value be sure to initiate it with a default value on startup.**

With something like this for instance : You could also probably create an empty preset, and load it on startup.

That being said there is two main abstractions that you will be interested in to actually save values :

[persist-map] : it takes 3 arguments the first one is the name of the preset bank, the second one is the send value of the gui object you want to save, the third one is the receive value of the object you want to load. If you create an object [persist-map synth decay.s decay.r] : you will save your decay value in a the preset bank called ‘synth’.
[persist-table] : it takes 2 arguments, the first one is the name of the preset bank, the second one the name of the table object that you want to save/load (regardless of its size - even if it is not made to save to much audio, play nice !)

Now let take a pragmatic example from the acid_bass sample app. As stated before we want to save our parameters in two separate banks : one for sequencer patterns and one fo synth presets. So the first thing to do is to create two objects [loadsave synth] and [loadsave pattern], those act as ‘routers’ for messages.

In the GUI we have three pannels : two of them are for the sequencer, and only one for the synth. We chose to use a bang to activate the display of dialog pannels one for the save action and one for the load action. That makes for bang that send those messages ‘save_pattern’, ‘load_pattern’, ‘save_synth’, ‘load_synth’.

Now we can interface this with persist :

1- we receive a message from a bang, and we create a new message sent with the tag ‘pattern-load’ (two first words), and it sends a path ‘presets_pattern’ and a file format extension ‘cbs’ 2- we receive this message and put it in the input of a [persist-load] object (or [persist-save] depending on the context) with the name of the preset bank as argument. 3- repeat 1 and 2 for other actions, and other banks !

Note : the file format ‘cbs’ will have to be added manually to save on destkop, wether it will be automatically added on android. That is mainly when you want to see a preset saved on a desktop computer in an android application, which will probably be the case of some of factory presets.

For the eclipse part, you just have to reference the path to the preset folder in your configuration :

 
config.presetsPaths.add("Acid_Bass/presets_pattern");
config.presetsPaths.add("Acid_Bass/presets_synth");

Congratulations you have finished your training and can now save presets !

How to customise your gui

Sun, 15 Nov 2015 00:00:00 +0000

We will cover :

the config variable
aspect ratio
color themes
factory components
custom overrides

We provide several level of gui customization by adding a few lines of code to you launcher (ie MainActivity.java). By default you have some simple pd classic gui, with the default colors from your original patch.

Create a config variable

First you need to import the config class from ppp, add the following line at the top of your main *.java file the one located in your /src folder in eclipse.

 
import net.mgsx.ppp.PdDroidPartyConfig;

After that you can create a new config variable, right after this line :

 
super.onCreate(savedInstanceState);

in the main java class. You just need to copy this line :

 
PdDroidPartyConfig config = new PdDroidPartyConfig();

this will give you access to new customization function !

Aspect ratio

By default ppp will strech you view to match the size of you screen. If you want the gui to keep the same look by not getting stretched away by several screen ratios once you’ve created the config variable below.

 
config.guiKeepAspectRatio = true;

Apply a color theme

Here is how to apply one of themes shipped with ppp, again you need to have created the config variable :

 
config.theme = new MonochromeTheme(MonochromeTheme.RED, true);

We have a few colors already setup for you, in eclipse you can remove the .RED part and press ctrl + space to activate auto-completion and check which other colors are available.

You can also create a theme with your own colors, you will then have to specify 3 colors, first the main background color, then the widgets background color, and finally the widgets foreground color expressed in hexadecimal form :

 
config.theme = new MonochromeTheme(0xff101933, 0xff202943, 0xff004ce6);

To find the hexadecimal code you can consult a website like this one. An hexadecimal color code is composed of 6 characters numbers or letters, and you have to add the prefix 0xff. In the above line the colors are different kinds of blue.

TODOC : more about SVG and/or PNG theming. even if SVG is not fully supported it’s an experimental feature …

Use factory components

Those are ready to be used for slick look, almost out of the box. You can refer to this post to get a list of all possible overrides.

To take a simple example, you can apply a custom look, on all the sliders of your patch by using typeOverrides, for instance the line of code below once added to you launcher will make your app draw all sliders as filled rounded rectangles.

 
config.typeOverrides.put(Slider.class, RibbonSlider.class);

You can also apply this look to only one slider, the slider with the label ‘mySlider’, set via properties directly in Pure-Data.

 
config.objectOverrides.put("mySlider", RibbonSlider.class);

After adding a line like this one in your launcher you may end up with an error, you just have to use the keyboard shortcut ctrl + shift + o to import the missing classes in you package.

FYI this manipulation (for a slider) will just write those two lines of code at the top of the MainActivity.java file.

 
import net.mgsx.ppp.widget.core.Slider;
import net.mgsx.ppp.widget.custom.RibbonSlider;

Develop custom overrides of components

You can developp custom overrides of components, those overrides can be graphical, but also on the interaction level. At this level you might want to consult the wiki.

The AcidBass example features a simple override to draw an array with a custom grid. The Wobbler example features a more advanced example combining two horizontal radio buttons linked to a slider to select the wobbling speed !

User Guide

Fri, 13 Nov 2015 00:00:00 +0000

This guide help music performers to setup and use applications. No programming skills are required here.

Pd Designer Guide

Fri, 13 Nov 2015 00:00:00 +0000

This guide is for Pders (Pure Data designers) and explain how to build application from your Pd patches.

We try to keep it as simple as possible to quickly get an application from Pd patch. You first need to configure your developpement environnement, then build your patches, customize it and finally publish it.

Advanced design

Fri, 13 Nov 2015 00:00:00 +0000

This guide is about the customization of the looks and behavior of gui components. It implies using the PdDroidPartyConfig class that will get us access great cutomisation possibilities.

How to publish !

Fri, 06 Nov 2015 00:00:00 +0000

This post will help you to put your application on the app store. To publish you’ll need a developper account for the play store, and have access to this kind of interface.

Port a patch ! (big recap)

Thu, 05 Nov 2015 00:00:00 +0000

Getting Ready

In this post we assume that you have completed all the steps of the ‘How to setup your publishing stack’ post. At the last step name your new app “hillageizer”, you’ll probably want to change the name of the main class in src folder to ‘bubbles’ using refactor/rename, and finally change the name of the folder and the patch in th assets folder, within your system explorer this time. (if it has not change in eclipse, just click on the project and hit F5 - refresh).

Your workspace should look like this :

and we are now ready to get started.

Remember your source code is where you put the zip you extracted, your project files should be in here this is your code, and the eclipse workspace is something else, that helps eclipse remembering where you were.

Pd actually means Pd Vanilla

This post is not about how to code in pd, so if you are a complete noob to pd you may want to build up your pd skills a bit before continuing. We will see how to port a patch to our system and for this we will use an example from the amazing Andy Farnell ! Check out this ressource ! if you don’t know this website yet, I suggest you take a look around :)

So just download the pd file, at the end of the page. We are lucky this patch a vanilla-friendly, if you are not familiar with the difference beetween ‘extended’ and ‘vanilla’ just look it up. We want ‘vanilla’ as libpd tracks ‘vanilla’, hopefully you’ll find help on the web if you need to port patches from extended to vanilla.

Setup you files and paths

Now we are going to integrate the patch in our project to start using the abstractions, to rig the clock, the saving system and the several views.

So just copy the hillgeizer.pd file in your assets/hillageizer/ directory. And rename hillageizer.pd to hillageizer-core.pd. Now open a new patcher window and save it as hillageizer-launcher.pd at the root of your project, add a path by creating an object [declare -path assets/hillageizer/] (this is to access the abstractions of your patch), and an object [declare -path ../pd-party/droidparty-abstractions] (this to access the project abstractions, like the clock), then save close the patch and reopen it.

You should now be able to create an abstraction called [clock-gui], and create the [hillageizer-core] object in your launcher patch.

Preparing the patch

We have a great sounding patch with a lot of parameters, we will want to organize everything in several views, make it compliant to with our clock, and add our own saving system.

If you look a bit at the patch we have three main parts :

eventshaker : the clock.
3 scale elements : which do scaling operations on the count.
phasors : the synth.

The first thing we need to do is to separate the gui from the logic. Here everything is built in GOPs, we want the sliders to be alone in their own abstractions. That also means that we need to get rid of all the ‘$0’ from the send and receive names of each gui … We also get rid of the tempo element in the subpatch ‘eventshaker’ to replace it with a [clock] object.

Here is what he can look like once it’s done :

Now have a patch conforming to the best practives we have described.

Setting the views

The pd side of things as already been done before. We now just have to tell our android launcher which are which.

First we have to declare a config variable :

 
PdDroidPartyConfig config = new PdDroidPartyConfig();

the line is likely to be marked as an error, you can click on the error icon and select the import proposition to fix it. (It will import the PdDroidPartyConfig class from our base code).

This being done, you can move on to add your views, first the gui-view, and then the core-patch.

 
config.guiPatches.put("Sequencer", "hillageizer/hillageizer-sequencer.pd");
config.guiPatches.put("Effects", "hillageizer/hillageizer-effects.pd");
config.corePatches.add("hillageizer/hillageizer-core.pd");

At this point you can launch you app, by right-clicking on the project and select Runs as/Android Application. It should run with two views.

Pure Data Party Publisher

Pd best practices

How to use multiple views

How to use the clock

How to save presets

How to customise your gui

Create a config variable

Aspect ratio

Apply a color theme

Use factory components

Develop custom overrides of components

User Guide

Pd Designer Guide

Advanced design

How to publish !

Port a patch ! (big recap)

Getting Ready

Pd actually means Pd Vanilla

Setup you files and paths

Preparing the patch

Setting the views

Presets saving

Gui cutsomization

Publishing