xr-abstractions

This is a collection of Pure Data abstractions. It includes sequencers, GUIs, general utilities, and a few effects and synths. I’m still in the process of writing and updating them to fix bugs and add functionality, so consider this collection to be in the “alpha” stage. You should also expect changes if you update the library later (which will hopefully be mentioned in commit messages); some objects might get renamed, removed, or end up working/looking completely different later.

Feel free to open an issue for any bugs you come across.

Some of the abstractions I find most useful:

• map - Map to the elements of a list; provide a list as arguments (or send one to the second inlet), then send numbers or bangs to the first inlet to get the list item at the specified index.
• unmap - The inverse of map; provide a list, then send items to the first inlet to get the index of the item in the list.
• rmap - Receive map; dynamically generate a subpatch of receive objects just by specifying their names as the arguments.
• snd~ - Convenient sound file access; provide a filename as the first argument to load it, then send a signal in the range 0-1 to the first inlet to read from the buffer.
• o~ - Output a mono signal to your DAC (speakers), with a few conveniences like a volume slider, mute toggle, and a small volume meter.
• so~ - Like o~ but for stereo signals.
• view~ - Waveform view; basically a simple oscilloscope.
• tview - Text view; a simple GUI showing the last 5 messages to the inlet.
• drumseq - Four-track variable-length multi-pattern step sequencer GUI.
• rrange - Random range; outputs random integers within the specified range.
• rchoice - Random choice; outputs random elements from the provided list.
• bpmm - Tempo clock GUI to generate bangs, floats, and a synced phasor signal to the specified BPM. Made for use with sequencers like drumseq, anaseq, etc.
• tb303~ - Basic Roland TB-303 imitation.

Requirements

Here’s a list of the libraries that this one depends on. All of these should be installed automatically if you’re using Pd 0.48 or above.

• cyclone
• ext13 (for receive13, …)
• iemguts
• iemlib (for dollarg, any, …)
• motex (for getenv, …)
• zexy (for drip, <~, …)
• list-abs (for list-drip, list-drip2, …)

Installation

Once you have the requirements listed above and have added this library and its subdirectories to your Pure Data path, the abstractions should “just work”.

Overview

Below is an overview of all of the included abstractions.

Abstractions whose synopsis below is capitalized have been checked and are known to be good. Abstractions with a lowercase synopsis still need to be reviewed/quality-checked, and may have major changes or possible removal in the future.

ctrl

Abstractions related to controlling things.

• ca - control interface. 1st arg is MIDI CC number, 2nd (optional) arg can be B to output bang when the CC hits 127, I to invert the CCs, a number to change the range from 0 to that number, or … (FIX: how is this different from c?)
• capslock - shows whether capslock is on or off and also outputs 1 or 0 depending.
• cb - control bend. shows the current value of the MIDI bend parameter, also adjusting its range to 0-127.
• cnum - control number. use your keyboard’s numpad to increase or decrease a number. use 8 to increase it or 2 to decrease it. probably won’t work if your numlock is on.
• c - midi continuous controller interface
• crossfade~ - graphical “crossfader”. see also: scrossfade~
• editmode - detect whether edit mode is on or off.
• inputd - input accumulator deluxe
• inputn - input accumulator for numbers
• input - input accumulator (similar to the symbol atom, but without a built-in GUI)
• ispigot~ - graphical audio spigot (left inlet is for the audio, right inlet is to open or close the spigot)
• ispigot - graphical message spigot (left inlet is for the messages, right inlet is to open or close the spigot)
• kbdm - convert numbers from key into midi note numbers so you can use your keyboard to play notes.
• keydrum - use squares of the keyboard as drum pads.
• keynum - get numbers from the keyboard. if “h” is provided as the first argument, also allows hexadecimal numbers (a-f).
• keyonchg - outputs a bang when the specified key is pressed.
• keyonoff - outputs 1 when the specified key is pressed and 0 when it is released.
• keyrow - converts numbers from key into the numbers 0-9. in other words, use a row of keys as numbers.
• kfilename - Deprecated. Expand filenames that begin with an abbreviation. For example, ~/foo is abbreviated to the full path of foo in your home directory. This abstraction is used in snd~, drumseq, anaseq and others to allow filename abbreviations.
• mono - monosynth implementation (keeps track of which keys are held down, only sending the most recent, including if more than one has been pressed/held down)
• monos - simpler version of mono. should work better with synths expecting input from something like notein.
• mspigot - multi-spigot. has 5 message inlets and allows you to graphically control which of them are mixed to the outlet.
• mstr - master. don’t use it. i’ll make a better version eventually, maybe.
• nems - non-edit mode spigot. only allows messages to pass when edit mode is off.
• numlock - shows whether numlock is on or off and also outputs 1 or 0 depending.
• polys - similar to pd’s built-in poly but allows you to specify a specific voice with note-offs (i.e. so you can have multiple voices with the same note). WIP: voice stealing is not yet implemented.
• router - routes one input (left inlet) to either the left or right outlet, depending on the state of the ratio control. the right inlet allows you to switch the outlet.
• scrossfade~ - graphical stereo “crossfader”. see also: crossfade~
• sndsel - sound selector. allows you to select a sound by browsing folders graphically, because playlist kind of sucks. it’s a work-in-progress, but it’s probably ready for regular use.
• switcher~ - graphically switches between 2 audio inputs. there are 3 inlets: the middle is a message inlet accepting floats to select the input to send to the outlet, while the left and right inlets are the audio inputs.
• switcher - switches between outputting the left inlet or the right inlet graphically via a ratio control. you can also change the inlet by sending a “switch” message to the first inlet.

demos

Demonstrations of the included abstractions (definitely open these if you want a tour of this library).

fx

Various small effects, or GUIs for them. See also: pd-ladspa-abstractions, a set of LADSPA-wrapping abstractions.

• autocap~ - automatic capture.
• bitcrush~ -
• bitflip~ -
• chaospad~ -
• chebys~ -
• chorus~ -
• delay~ -
• dist1~ -
• dist2~ -
• flanger~ -
• gater~ -
• icomb~ -
• ifilter~ -
• ifv~ -
• ilattice~ -
• imoog~ - Graphical interface for the moog~ low pass filter.
• isvf~ -
• mcomb~ -
• mfv~ -
• mmf~ -
• phaser~ -
• pingpong~ -
• pitchshifter~ -
• rateshift2~ -
• rateshift~ -
• sdly~ - Simple delay. Delay time and feedback are settable by arguments and signal inlets.
• shaper~ -
• sidechain~ -
• skip~ -
• soft~ -
• sqtremolo~ -
• stautocap~ -

gen

Abstractions for generating sound.

• analog~ - analog “simulation”. Basically supposed to be like quiet line noise and a small dc offset, for providing as input to your synths to make them not as static. [FIX - improve this]
• noisef~ - Noise with a frequency input. Effectively just white noise through sample+hold.
• playsf~ - play a file from the argument. Effectively just a slightly more convenient wrapper around readsf~.
• pm~ - Basic sine-based phase modulation oscillator.
• psndm~ - polyphonic midinote-based sound player. You can send it midi numbers to play the sample at different rates. It has 8 voices. [FIX - can this be improved with poly~?]
• psndp~ - polyphonic sound player. Similar to sndp~ but with 6 voices. [FIX - can this be improved with poly~?]
• pulse~ - Basic pulse wave oscillator with modulatable pulse width.
• rec~ - basic “sampler”. Record a snippet of sound to a table.
• recp~ - basic “sample player” for rec~. Just plays the a snippet of sound from rec~. [FIX - can this be merged into rec~?]
• recsnd~ - allows access to the sound recorded with rec~ in a similar manner to the way snd~ allows. [FIX - can this be merged into recp~?]
• saw~ - Basic saw wave oscillator. Effectively just a bipolar version of phasor~.
• sine~ - basic sine wave oscillator. Based on phasor~ and cos~. [FIX - this is redundant with pm~.]
• snd~ - convenient sound file access; provide a filename as the first argument to load it, then send a signal in the range 0-1 to the first inlet to read from the buffer.
• sndcf~ - snd~ control based on multiple of the sound’s base rate. [FIX - rename to =sndcr~=]
• sndcl~ - snd~ control based on line~. Allows you to specify the start and end points and the time between them.
• sndcm~ - snd~ control based on midi note numbers. 60 is the default midi note number [FIX]
• sndd~ - sound duplicate. Like snd~ but does not re-load the file; simply re-uses the existing table containing the already-loaded file. Useful for polyphony.
• sndf~ - sound frequency. Play a sound at a rate multiplied by the normal rate. Effectively just shorthand for snd~ and sndcf~.
• sndl~ - sound line. Play a sound or snippets of it based a line~. Effectively just shorthand for snd~ and sndcl~.
• sndm~ - sound midi. Play a sound based on midi note numbers, with 60 being the default base note. Effectively just shorthand for snd~ and sndcm~.
• sndp~ - sound play. Loads a sound into a table and accepts bangs to play the whole sound. Handy for one-shot samples like drums.
• stsnd~ - stereo sound. Similar to snd~ but for stereo samples. [FIX - check if this works]
• timestretch~ - “timestretch” a sound by going back and forth through it.
• tri~ - Basic triangle oscillator. Can be smoothly morphed to an upward or downward saw wave using its second signal inlet.

guis

Abstractions whose primary purpose is to display information.

• cpuload - Shows the current 1-minute load average (basically CPU usage %) of the system.
• cview - ctlin gui (works as drop-in replacement!)
• ifiddle~ - fiddle~ gui (works as a drop-in replacement!)
• lview - list view. shows the whole list received and its length.
• nview - notein gui (works as a drop-in replacement!)
• scroll~ - scrolling amplitude view.
• siga~ - signal analysis. shows the current value, average value, maximum and minimum values, and a vsl to plot the input. there is also a bng to reset the recorded maximum and minimum.
• spectrum~ - shows the FFT spectrum of the input.
• tview - text viewer. scrolls the last 5 received inputs.
• view~ - waveform view.
• vsig~ - “view signal”. shows a graphical representation of the signal from -1 to 1.

math

Abstractions for altering or generating streams of numbers.

• atc~ - “audio to control” - converts a bipolar signal (-1 to 1) to a unipolar signal (0 to 1)
• atc - “audio to control” - converts bipolar numbers (-1 to 1) to unipolar numbers (0 to 1)
• atr~ - “audio to range” - converts a bipolar signal (-1 to 1) to an arbitrary range specified as arguments or via inlets.
• atr - “audio to range” - converts bipolar numbers (-1 to 1) to an arbitrary range specified as arguments or via inlets.
• coin - “Flip a coin” with a specific probability of landing heads. Outputs 1 on heads, 0 on tails. Defaults to 50% probability. Similar in operation to maybe.
• cta~ - “control to audio” - converts a unipolar signal (0 to 1) to a bipolar signal (-1 to 1)
• cta - “control to audio” - converts unipolar numbers (0 to 1) to bipolar numbers (-1 to 1)
• ctr~ - “control to range” - converts a unipolar signal (0 to 1) to an arbitrary range specified as arguments or via inlets.
• kinv~ - signal inverter. 0 becomes 1, 1 becomes 0, and everything in between.
• kinv - number inverter. 0 becomes 1, 1 becomes 0, and everything in between.
• maybe - Maybe pass the left input through with a specific probability. The right inlet sets the probability; floats between 0 and 1 specify the probability as a percent (i.e. 0.25 is 25% chance); integers above 1 specify 1 in n chance (i.e. “5” is a 1 in 5 chance or 20%). Banging the inlet is a 50% chance. Similar in operation to coin.
• minv - “midi invert”. 127 becomes 0, 0 becomes 127, and everything in between.
• mrange - scale 0-127 to an arbitrary range.
• num - Store and change a number with messages. Supports addition, subtraction, multiplication, and division.
• rangem - scale a range to midi (0-127).
• reciprocal - outputs the reciprocal of the input.
• round - Round a float to a multiple of the specified number (default: 1).
• rrange - random within a range (inclusive).
• rtr - “range to range” - scale one arbitrary range to another arbitrary range.
• runningmax~ - output the highest value seen in a signal.
• transposer - outputs number to multiply a frequency by in order to shift it by a number of semitones (provided as input or argument)

seq

Sequencers and similar high level control objects.

• adsr~ - attack decay sustain release envelope… well, kinda.
• adsr - same as adsr~, but outputs messages instead of audio signal.
• aline~ - automatic line. like line~ but floats don’t jump, they start a line whose time is provided by the first argument.
• aline - automatic line. like line but floats don’t jump, they start a line whose time is provided by the first argument.
• amap - advanced version of map. has more features like random selection, insertion, deletion, and dumping the contents.
• anaseq - a sequencer made of vertical sliders; supports saving, loading, multiple patterns and more.
• beat~ - make beats from a phasor by dividing the phasor into $1 sections and outputting a bang every $2 sections.
• boxseq - 6x6 “box” sequencer. can be played in any direction, even diagonally. was an experiment. might change it later.
• bpma - “bpm any”. WIP.
• bpmm2 - was supposed to be the next version of bpmm with fewer outlets but I might delete this actually.
• bpmm - metro/gui for outputting bangs on the downbeat, bangs on each quarter note, and numbers for each quarter note. try connecting the third outlet to anaseq or drumseq
• burst - burst generator a la modular synths: when a bang is received, it outputs N bangs, spaced M milliseconds apart.
• drumseq - Four-track variable-length multi-pattern step sequencer GUI. Supports saving, loading, and more. Formerly known as drumseq2; the old version of drumseq is deprecated but still temporarily available as old-drumseq.
• dust - output bangs at random intervals lower than the provided argument.
• edger~ - basically a convenient interface to edge~. left outlet bangs on a zero to non-zero transition, while the right bangs on a non-zero to zero transition.
• ft - “friendly table”. abstraction to make it easier to edit a table. need to redo this.
• hash - hash table. operates similarly to table except keys and values can be any symbol, rather than just integers. see also: hashread, hashwrite
• hashread - read from hash’s hash table. analogous to table’s tabread.
• hashwrite - write to hash’s hash table. analogous to table’s tabwrite.
• iadsr~ - interface ADSR envelope. WIP.
• ilist - indexed list manager. insert into or remove from a list by index, just by sending messages.
• listman - list manager. you can add elements to a list, remove them, check for their existence within the list, etc. you can’t remove by index, only by value, so don’t use this if you want to have multiple of the same element.
• lmap - line map. was supposed to be used to generate a complex line. but I might delete this.
• map - map bangs or floats to elements of a list provided as arguments or set via the right inlet. probably the most useful abstraction you’ll ever find.
• ometro - “on metro”. a metro that is on by default.
• pattseq - graphical sequencer similar to drumseq but outputs numbers rather than just bangs.
• pb - processor for betablocker. basically a little computer.
• pmap - program map. related to pb.
• proll - piano roll-like sequencer. WIP.
• queue - a first-in-first-out queue. you can enqueue things onto the queue or dequeue them from it. see also: stack.
• rchoice - random choice from either the arguments, or from the incoming list.
• rmap - receive map. takes as arguments a list of names to receive from, and outputs data received from them with numbers prepended.
• sbox - box abstraction used by boxseq and pattseq.
• seqfill - abstraction used by drumseq’s “e” command. might remove this in the future.
• srush - “snare rush” abstraction. might redo this to make it simpler.
• stack - a last-in-first-out stack. you can push things onto the stack or pop them off of it. see also: queue.
• taptempo - tap or send bangs to get the tempo.
• td~ - table draw. supposed to draw into a table via messages, but it’s not finished yet. probably never will be. might delete this.
• tmap - timed map that plays through the whole list with one bang.
• tracker - DEPRECATED; just use messages instead. A tracker-inspired GUI that was a bad idea, isn’t actually very useful, and is glitchy (can even crash Pd sometimes). Don’t use it!
• unmap - get the index of incoming values in a list provided either as arguments or via the right inlet. This is the opposite of map.
• vslz - extremely simple 8-step vsl-based sequencer.

synths

“Full-featured” synthesizers, many of which actually aren’t even completed yet.

• hoover~ - hoover synth. WIP.
• kick1~ - extremely basic kick drum synth.
• kick2~ - another extremely basic kick drum synth.
• kick3~ - yet another extremely basic kick drum synth.
• snare1~ - extremely basic snare drum synth.
• snare2~ - another extremely basic snare drum synth.
• tb303~ - TB303 clone. probably doesn’t sound much like the real thing. WIP.
• wavesynth~ - Convenient interface to generate and play a sinesum-generated tone.

utils

Miscellaneous utilities.

• *+~ - multiply and then add to a signal with one object.
• *+ - multiply and then add to a number with one object.
• autosend - use the first item in a message as the destination for the rest of the message.
• chars - separate a symbol into a list of its characters.
• colors - outputs a pd color when the left inlet is banged. otherwise, the inlets take floats: from left, the red amount, green amount, and blue amount.
• e - “Every”. Pass through every $1-th input, with an offset of $2.
• emptysymbol - Test if a symbol is the empty symbol.
• hue_to_rgb - convert a hue to rgb colors. see also: colors
• interval - outputs time between bangs, measured with realtime.
• itimer - interface timer. shows minutes, seconds, and milliseconds.
• ktimer - timer abstraction. outputs minutes, seconds, and milliseconds from an internal realtime object. this is used by itimer but I might delete this.
• lb - loadbang abstraction. lets you output a specific number or value on load, rather than just a bang.
• limit~ - handy limiter abstraction. basically just outputs a signal limited by limiter~ in case you’re lazy like me. be warned that this introduces a delay of 64 samples, of course.
• list-find-1 - basically the same as list-find but only finds the first instance of an item in the list.
• list-replacer - replaces all instances of one item in a list with another list.
• lists - list store. basically works how float and symbol work, except, of course, that it’s for lists.
• list-without - returns a list without all instances of the specified element.
• marquee - display elements of a list at regular intervals.
• mp3conv - use the lame command-line utility to convert an mp3 to wav, storing the wav in /tmp and outputting the filename of the wav when conversion finishes. you’ll need to have lame installed in order for this to actually work.
• o~ - interface for mono output to dac~.
• parser - parses lisp-style commands from within the incoming message (i.e. “(function argument1 argument2 … argumentN)”) and outputs the original message with the output of each command replacing the command. currently accepts “rc” for rchoice and “rr” for rrange. it’s a decent start but I will probably add memory to it as well. maybe eventually it will be a full-fledged lisp implementation! ha.
• parse-arguments - parse dash-prefixed “arguments” from a list.
• porta~ - portamento. might need work.
• qtabwrite - quick tab write. specify a table as the argument, and then you can send messages to the inlet or to qt-$1 in the format “INDEX VALUE”
• qtimer - quantizible timer. similar to interval but allows you to specify the granularity of output values.
• quote - surrounds the input with quotes.
• rporta~ - relative portamento. might need work.
• si~ - interface for stereo input from adc~. see also: so~.
• so~ - interface for stereo output to dac~. see also: o~.
• spacesym - outputs a symbol that has a character that looks blank. thus, you can make symbols with “spaces” in them without them being lists. it’s one of pd’s quirks. don’t know if this’ll work everywhere.
• span~ - simple panner. like pan~ but lets you specify the panning position as an argument if you’re lazy.
• sreceive~ - settable receive~.
• ssend~ - settable send~.
• sym - turn a list into a symbol (basically just l2s with an empty symbol sent to the right inlet. see also: chars)

scripts

Various Pure Data utility scripts.

• pd-objects-search - Get objects used in the specified file(s) or files that reference the specified object.

Future

There is a lot of work to be done for this library to clean it up, fix bugs, add features, and remove deprecated/broken/unneeded abstractions. If you’re using this library, keep an eye on the commit log when updating to note potentially breaking changes.

Here is a list of tasks and ideas for the future of the library:

cleanup

• make sure all of these abstractions work with the new version of Pd (vanilla).
• sort through these folders: ctrl, demos, examples, fx, math, seq, utils
• remove incomplete/broken/unneeded extensions.
• rename adsr and adsr~ to just adr and adr~ and remove the sustain functionality
• remake adsr and adsr~ into actual ADSR envelopes
• atc, cta, atr, and the others should probably be renamed to something like btu, utb, and btr, since the technical term for a signal from 0 to 1 is “unipolar” and the technical term for a signal from -1 to 1 is “bipolar”
• remove a lot of the stuff in “fx”, since a lot of it either sucks or isn’t even original material.
• remove usage of fiddle~ since it is now deprecated in favor of sigmund~ or bonk~.
• use swap instead of a “$2 $1” message when possible.
• maybe change this readme into markdown format? it’s more common but org provides export options and other potentially-useful features, and is easier to write.
• document alternatives to this library, and to individual objects. for example, how does sequencer from ELSE compare to map?
• ensure there are no object name conflicts with other popular libraries
• finish removing kfilename - only anaseq still uses it (need to implement savestate support in it).
• rename tview to view
• delete chars and sym in favor of list fromsymbol and list tosymbol
• remove use of deprecated % object

decrease library dependencies

some of the functionality used by them can either be reproduced myself, or may be part of modern versions of pd.

• dollarg can be replaced by pdcontrol args
• maybe list-drip (list-abs) can be replaced by drip (zexy)?

general/ideas

• make an “examples” folder full of better examples instead of cramming as many abstractions as possible into crappy “demos”
• make abstractions for “patterns” inspired by the pattern libraries of SuperCollider/cl-patterns (this might be best done as a separate library; perhaps it could be called “pd-patterns” or “sequencing-patterns”?)
• make cline (controllable line using mc and keyboard shortcuts or messages)
  • make o~ and the like use cline for the volume controls
• consistent color coding for different types of GUI abstractions. (is there some already-existing convention that can be followed for this?)
• update all abstractions that contain state (drumseq, anaseq, etc) to make use of savestate.
• update all abstractions to handle multiple channels using the new multichannel functionality in Pd 0.54.
• add the library to Deken.
• write help files for all abstractions.

object improvements

• see if there are better ways to analyze the “volume” of a sound for scroll~
• rename scroll~ to something more descriptive
• re-add mc for o~? - or see if there is a way to get the name of the parent patch so the o~ can receive13 from a variant of that name.
• make a better analog~
• remove seqfill maybe.
• redo ft maybe.
• implement voice stealing in polys
• make randomsong~ use mp3conv (and fix mp3conv).
• finish proll (improve GUI; maybe rename to piano-roll?)
• add keyboard shortcuts to drumseq and other “bigger” abstractions.
• update snd~ so that you can also index the sound by samples, or maybe just make a separate version of snd~ that always indexes by samples or time (seconds/etc).
• finish looper~.
• finish grain~ and granular~
• finish tb303~ (add accent function, perhaps improve GUI further) and hoover~.
• figure out if there is a way to avoid tri~ making loud clicks/NaNs when its shape is -1 or 1.
• make a stereo version of snd~.
• remove use of cursor object (i.e. in sndsel, inputd)?

testing

Ideas for (unit) testing the library.

• pd supports the following command line flags which will likely be useful for this:
  • -path - add to the search path.
  • -nostdpath - don’t include the standard search paths (i.e. “extra”).
  • -open - open a specific patch on startup.
  • -verbose - increase verbosity when starting up and searching for objects.
  • -nogui - don’t open the gui.
  • -send - send a message on startup after patches are loaded.
  • -noprefs - don’t load preferences.
  • -batch - run offline, as a batch process.

not possible?

Ideas I have and would like to implement, but which I don’t think are possible in Pure Data yet, either due to bugs or missing features, or perhaps just my lack of knowing how to do so.

• make keyonchg, keyonoff, etc work properly. Pd’s keyname, key, keyup, etc, all detect keyboard “repeat” events and it doesn’t seem to be possible to easily filter them to only detect “key pressed” and “key release” events.
• remove span~. motex’s pan~ object would need to accept panning as an argument for this to be possible.

More

Here are a few other (unassociated) libraries and resources worth a look.

Intelligent patching demonstrations

intelligent patching in Pd-vanilla

More intelligent patching in Pd-vanilla

Less intelligent patching for Pd

ELSE

Includes a lot of functionality, including a SoundFont object (sfont~), Mutable Instruments Plaits (plaits~), and many other useful utility and audio objects. There is also a tutorial for doing live electronic music using Pure Data with ELSE.