Orac : module developers guide

This thread is for discussion about developing modules for Orac.

When I created my first patches for the Organelle, I found I spent a frustrating amount of time patching the UI,
and then still lacked featurs I thought end users would ‘expect’ , such as midi control, preset loading/saving.

This really was the starting point for Orac…
I wanted something I could create modules for quickly, without having to worry about the UI, just concentrate on the module functionality,
and get things midi, presets all for free, and I wanted this ‘support’ almost invisible to the module, so you dont have to worry about complex apis etc.

Having now written/converted over 50 modules for Orac, I personally feel Ive achived this, I hope you will too.

Here is a video, which walks you through how to create a module,

p.s. as an example, a few of the C&G patches I converted in about 10 minutes :slight_smile:

and a video on how to convert existing organelle patches (in this case Nori Sampler)

Why write a module rather than a standalone patch?

  • its quicker :slight_smile:
  • is musicians get to use your patch in interesting ways, by combining it with other patches
  • you can focus on the core functionality, get midi learn, presets, remote control (via osc), cross platform - for free

What is a module?

well it can be anything, including a complete patch.
but the best module (imo) are ones which are focused, e.g. a synth module doesnt need to include a reverb, since the user can include a reverb of their choosing. so if you have a unique sequencer, fx, synth release as separate modules.
not a cpu hog, ok reality is some modules are going to be hungry for CPU, and thats ok… but just be aware if you use 90% cpu, the user is not going to be able to add many other modules. (another reason to split things up)

Distribution of modules

so basically to use a new module, all you need to do is drop it in the Modules directory … so you can release on Patch Storage

in v1.0 be aware re-installing/upgrading Orac will remove custom modueles… Im going to change this in v1.1

Another possibility, will be to include in the ‘factory’ modules for future release,
though they will need to meet a few criteria (e.g. open source, maintainable), we can discuss this later.

Module installation

ok, so to install nicely the best option is to use the organelle installer package
(this is particularly important for modules with large/more files, since it correctly checks that files are not corrupted)

to do this, we first need a deploy script in the module directory, this is very simple
its called deploy.sh, and can contain as little as:

oscsend localhost 4001 /oled/aux/line/2 s "installing"
oscsend localhost 4001 /oled/aux/line/3 s "orac module"
cd ..
mv $1 orac/modules
exit 1

then on the organelle we need to create the zop file, we so this in the modules directory (so above your module directory, so for S-norisample we use

~/scripts/create_install_package.sh S-norisampler 

it will report something like

[root@organelle2 modules]# ~/scripts/create_install_package.sh S-norisampler 
create install package for S-norisampler
move existing manifest away
  adding: S-norisampler/LICENSE.txt (deflated 49%)
  adding: S-norisampler/deploy.sh (deflated 38%)
  adding: S-norisampler/manifest.txt (deflated 40%)
  adding: S-norisampler/module.json (deflated 53%)
  adding: S-norisampler/module.pd (deflated 68%)
  adding: S-norisampler/samplervoice.pd (deflated 66%)
  adding: S-norisampler/sound.wav (deflated 24%)

this will create the file S-norisampler.zop which is what we ‘ship’

for user they then just put this in the same directory as orac (not in the modules directory!), so for most this will be /usbdrive/Patches.
(the reason for this is placing in the orac or modules directory would mean you cannot see it in the Organelle menu to be able to see it)

you can find the S-norisampler example on PatchStorage here


Can I ask a dumb question? How are you editing on your mac and previewing changes live on the organelle?

he, he - not a dumb question at all - its magic :wink:

no, I use another project of mine called ‘OscProxy’

its two parts running over wifi

  • one part runs on the Organelle and sends all the knobs/encoders/keys to the Mac
  • another part runs on the Mac, which sends all the screen messages etc to the Organelle.

so actually the PD patch is running on the mac, but all the interaction is done on the Organelle…

I do this for the video, because I can then screen capture the mac (which I dont have for the Organelle)

I need to put out a new release of OscProxy as the last one is a bit difficult to setup… more a personal dev tool, but Ive an idea how to make it simpler - now all i need is time :wink:


i just saw this
i will try to drop the ZOIA clone project into this i assume
it’s supposed to be minimal quick and i think they would fit nicely

I’ll take a crack at adding them to this because turning them all into standalone patches does not sound fun, so this should be way nicer


So brutal!

Is there a list of available value types?
How does the scaling work? I would like to use percentages, but with maximum resolution instead of stepped. This may be standard functionality, but don’t have a chance to check for a bit.

Also interested in a way to work in GFX overrides so that there will be more flexibility with the screen. Probably further along.

Looks fun!

The scaling / resolution is only for the screen, the user still defines the resolution of the audio engine.

+1 for value types.

types are (off top of my head :wink: ) - pct, time, pitch, freq(or is it hz?) , int, bool
all can have defaults
all except bool, can have any range they want

i will be adding more types, and im thinking about custom display.
(however, please note… ive very particular design goals in this area related to remote control/displays., more on this later)

resolution - display rounds, but there is no stepping (currently, it could be added)
the stepping you see, is actually the pot resolution (or more specifically, how Organelle rounds before sending over serial and osc), so its the highest it can be.

(orac uses 32 bit floats, so for example when using a push 2 as a control surface, the resolution is much higher)

yeah, please ‘bare with me’… i know from Kontrol about requirements for things like enums, but the priority then was Orac (which really is the ‘product’ of kontrol).

#1 priority now, is to support new users, and also module patch developers, to get Orac in use.

#2 priority is probably the web app, so Orac can be controlled from an iPad/iPhone, but hoping (and got some interest) others might help on this.

after that, more features for Kontrol, is probably the thing most needed.

so lots on my plate…

if there are any developers interesting in helping, this is open source, so contributions are most wanted.
mostly at the moment this is in the C++ field, and web development,

also all users can help, by fielding questions from others, helping build the community around orac - this would be really awesome.


I’m here for the last part of your post ;-)…

1 Like

Can I use floats as default values and min / max values in the .json files?

Thanks @keymanpal much appreciated

@wo3, yes ( If understand correctly),
oh float is also a type , but i don’t use as it has no units.
generally , if you have a look at the modules there are examples of all types in use.

+1 for fielding questions if I can. Also trying to spread the message on other forums where appropriate.

I really think adding modulation busses would open up the Organelle further, so really looking forward to what you come up with here. All in good time I hope. :slight_smile:


Ahah always that little extra, something more :wink: yeah but I’m guilty here also :wink:

Haha, it was @thetechnobear who raised the prospect, has got me salivating!

1 Like

Trying U-clock > Arper > Analog mono. Isnt behaving how I’d expect when I alter bpm in U-clock. Can anyone shed some light on what/why it’s not like changing the bpm on a regular Arpeggiator? Have I missed something out that’s needed in another module/settings?

Edit - wrong thread… Mods feel free to move to the other one. Thank.

Is there a module that has a volume level boost param lurking in it? Finding some of the synth levels hard to balance how I’d like them when layering.

Edit - wrong thread… Mods feel free to move to the other one. Thank.

The routing modules has all Gain control over each individual module.


Cool, thanks!

Gain staging is controllable for each module in the routing module (e.g. 1x10 ect), just scroll encoder to the page for the module you wish to boost. You can also edit midi note thru for each module here.
Edit: Whoops, too late!


Are you sure you’re only using one U-clock?