Toybox Editor Manual

The Toybox Editor is included with every Toybox plugin. It's a patching workspace where you can add new features to the instrument, rebuild the Utility Strip panels that come with it, or build an instrument of your own from scratch, all without writing any code.

Everything in the Editor is live. There's no build step and no waiting, changes take effect as you make them, even while a note is sounding, and everything you do can be undone with Command+Z (Ctrl+Z on Windows). It's an advanced feature and you don't need to use it, if you never open it the plugin behaves exactly as it always has.

Contents

Opening The Editor

To open the Editor select 'Open Editor' from the 'Settings' menu (the icon with 3 vertical lines at the top right corner of the GUI), or press Shift+Option+E (Shift+Alt+E on Windows). It opens in its own window, so you can keep it beside the plugin while you work. Tick 'Show Editor On Open' in the Editor's 'View' menu to have it open automatically whenever the plugin's window opens, and 'Keep Window On Top' to stop it disappearing behind other windows.

Tooltips

Before you start, enable 'Show Tooltips' in the Editor's 'View' menu. Almost everything in the Editor is documented with tooltips:

  • Hover the mouse over a module's header to see a description of what that module does.
  • Hover over a port (either the dot or its name) to see a description of what that port expects, along with a live readout of the value that's currently on it, which updates as the value moves.
  • Hover over a cable to see the same live readout, or a meter, scope or latency display (see 'Wire Debugging' below).
  • Hover over any row in the Properties palette to see a description of that property.

Tip: the live readouts on the ports and cables are the quickest way to find out why a patch isn't doing what you expected, just follow the signal along and see where it stops moving.

The Window

The Editor window has 3 regions, and the 'View' menu lets you show or hide each of them (the last one showing can't be hidden):

  • The Patcher Canvas fills the middle of the window. This is where the patch is built, we'll just call it the Canvas from here on.
  • The Library, down the right hand side, lists everything you can add to the patch, arranged into collapsible categories with a small coloured swatch showing which family each module belongs to. Any snippets you've saved are listed at the bottom. Press the 'Tab' key to show or hide it.
  • The Drawer, down the left hand side, has 3 tabs along its top. The Editor tab holds the 3 palettes described below, the Browser tab lists the files in your plugin's user folder and the Snapshots tab holds the plugin's snapshots (see 'The Browser And Snapshots Tabs' below).

The Editor tab can show up to 3 palettes, each one toggled from the 'View' menu:

  • Properties palette: Lists every property of whatever is currently selected, including properties that don't have a port on the node's box.
  • Tree Editor palette: A tree view of the whole patch, handy for finding things in a big patch or inside Views.
  • MIDI Triggers palette: A list of the MIDI Triggers in the patch.

Across the top is the menu bar: a padlock icon (see 'Building And Editing Panels' below) followed by the File, Edit, View and Snippets menus. A small pill at the top left corner of the Canvas shows which part of the patch you're currently looking at. The window remembers its position and size, and which palettes and tabs you had open, between sessions.

Modules And Nodes

A quick word on words. A module is a thing in the Library, an oscillator, a filter, a knob, a calculator. A node is that same thing once it's on the Canvas, placed and connected. They're the same object seen from two sides, so this manual uses whichever reads better in context.

Inputs run down the left hand edge of a node and outputs down the right hand edge. Some nodes have more than ports: modules that carry a control (a knob, a button or a menu) display the real working control inside the box so you can set it while you patch, calculator modules display their expression inside the box (click on it to edit it), sample modules have a sample menu under their header, and some modules have a level meter or an envelope display built into the box.

Adding Modules

There are 4 ways to add a module to the patch, they all do the same thing:

  • Press Return with the mouse over the Canvas. A search box opens at the mouse position, type a few letters and the matching modules are listed underneath. It matches the module's name, any word in the name, and its short symbol, so typing "+" will find 'Add'. Use the arrow keys to move up and down the list, Return to add the highlighted module at the mouse position and Escape to cancel. This is by far the quickest way to build a patch.
  • Right-click the Canvas to open the full 'Add' menu, which is arranged into folders with the most commonly used modules listed at the top.
  • Drag a module from the Library onto the Canvas.
  • Drop a module onto a cable to splice it in (see 'Live Patching' below).

Note: modules that have had all of their instances used up are greyed out in the menus and in the quick-add list (see 'Audio Collections' below).

Selecting And Moving

  • Click a node's header to select it. Shift-click adds or removes nodes from the selection, and dragging on an empty part of the Canvas lassoes everything inside the rectangle. Hold 'Shift' while you lasso to add to what's already selected.
  • Dragging any node that's part of a multiple selection moves the whole group together.
  • Nodes snap to a fine grid as you drag them, hold the 'Command' key ('Ctrl' on Windows) while dragging to snap to the coarse dot grid on the background instead. The arrow keys nudge the selection by one grid step.
  • Hold 'Option' ('Alt' on Windows) while you drag a node to pull off a duplicate of it, or of the whole selection.
  • Drag the bottom right corner of a node sideways to make it wider, handy for modules with long port names. Drag the same corner downwards to reveal the node's hidden ports one at a time, and back up to hide them again.
  • Double-click a node's header to minimise it down to a compact box, and double-click again to expand it. Simple modules with a single input and output arrive minimised already.
  • Press 'F2' (or Shift+Return) to rename the selected node. The name is just for your own reference, it's displayed on the box and in the Tree Editor.
  • Right-click a node's header to open its menu, with rename, cut, copy, paste, duplicate, delete and minimise.

Pasted and duplicated nodes land somewhere sensible: next to the place you last clicked on the Canvas, or just offset from the nodes you copied, or in the middle of the view if neither applies. Pasting again stacks each copy a little further along.

Ports And Cables

The colour of a port tells you what kind of signal it carries:

  • Audio (white): A signal that moves every sample. Every output port on an audio module is an audio port, and so are the plugin's main outputs.
  • Property Value (grey): A single value that only changes when something changes it. These are the same values that the Panels and Triggers pass around, and the same thing that a knob on the GUI holds. Property Values always have a ':' in their name.
  • Audio + Value: Most of the input ports on the audio modules are this type. They'll take an audio cable if you connect one, and if you don't they'll sit at a fixed number that you type in, or follow a Property Value that you point them at.
  • MIDI (blue): A stream of notes and CC (continuous controller) messages passing between the MIDI modules.
  • Buss: The 'Buss' port on the Send and Receive modules. Instead of a signal this port takes a name (see 'Busses' below).

To connect two ports drag from one port's dot to the other, it works in either direction. Cables can only be connected between compatible ports, so if a connection isn't allowed nothing will happen when you drop it. A Property Value can drive an Audio + Value input, but audio can never drive a plain Property Value input directly, for that use the 'Audio To Value' module, which turns an audio signal into a Property Value that the GUI can follow (a meter or an LED, for example).

An output port can be connected to as many inputs as you like. An input port can only take a single cable, so dropping a second cable onto it will replace the first one.

Note: some modules keep their less commonly used inputs hidden so that the box stays small. A small '+' appears at the bottom edge of the node to reveal them, click the one on the left for inputs or the one on the right for outputs and choose from the list, or drag the bottom right corner downwards to reveal hidden ports.

Connecting Several Cables To One Input

If you hold down 'Shift' as you release a cable onto an input that's already connected then the new cable joins what's already there instead of replacing it, so both connections end up on the same wire.

The easiest way to think about this is that it isn't 2 cables meeting at a point, it's one long wire that all of those ports are connected to, and it doesn't matter where along the wire you touch it. So if you connect one of the outputs that's already on the wire to another node's input, that new node joins the same wire too, along with everything else that's already connected to it. Disconnecting a port just removes that one port from the wire, everything else carries on as before.

This works for Property Value and MIDI connections. It isn't available for audio connections, where each wire can only carry a single source. If an audio wire does end up with 2 sources driving it a red dot is displayed on the ports to warn you. To sum audio signals together use a 'Mixer', an 'Add' or a buss.

Named Connections And Fixed Values

You don't have to draw every cable. Click on a port's name (rather than its dot) to open the port menu and select 'New Connection From Here'. Then open the port menu on any other port, anywhere in the patch and at any level of nesting, and select 'New Connection To Here', and the two ports are connected. No cable is drawn, the connection's name is simply displayed next to each port, and you can keep pasting the same connection onto as many ports as you like.

This is the quickest way to get a signal across a busy patch, or into a node that's nested a few Views deep, and it keeps everything tidy. Under the hood every connection is just a name that the ports share, which is also why a port can follow one of the plugin's own values: select 'Add Value' on an input and type a Property Value name such as "playhead:bpm" and the port follows it. Property Value names always have a ':' in them.

The 'Add Value' box is also where you type in a fixed number for an input, an oscillator's frequency or a filter's cutoff for example, for any input that you don't want to patch (it reads 'Edit Value' once there's a number in it). The rest of the port menu has 'Clear', which disconnects the port, and 'Hide' for a revealed port you aren't using.

There are some shortcuts for working with fixed numbers:

  • Option-click a port's dot to set it to 1, and again to set it back to 0. Shift+Option-click sets it to 0 straight away. Handy for switches and gates.
  • Command-click a port's dot to clear it, whether it holds a number, a name or a cable.
  • Hold Shift or Control and drag a number up or down to change it, the same way you'd drag a knob.
  • Hover over a number and press the up or down arrow keys to nudge it: 'Shift' steps by 1, 'Control' by 0.1, 'Option' by 0.01, and 'Shift+Control' by one semitone on a pitch value.

Busses

Busses are handy for mixing several signals together and picking them up somewhere else in the patch.

Add a 'Send To Buss' module, patch a signal into it and give its 'Buss' port a name, either by typing the name into the 'Buss' row in the Properties palette or by using 'Add Value' on the port itself. The name can be anything you like: "pitch", "fx", "sub". Then add a 'Receive From Buss' module and give it the same name, and its output will carry that signal. Any Sends that use the same name are summed together, and any number of Receives can pick up the result. Names aren't case sensitive.

Live Patching

Because nothing is ever compiled, the Editor lets you move modules in and out of the signal path while the sound is playing. There are 3 gestures worth learning:

Drop a module onto a cable to splice it in. Drag a module that has no cables of its own, either a new one from the Library or one that's already on the Canvas dragged by its header, over an existing cable and the cable lights up. Drop it and the module is inserted into that cable: the cable's source is connected to the module's first suitable input and the module's first suitable output carries on to the cable's original destination. If the cable doesn't light up then there was no compatible pair of ports, so nothing will happen if you drop it. Adding the module and re-routing the cable are undone together in a single step.

Hold 'Shift' and drag a node by its header to patch it live. This is the splice above, but it happens while the mouse is still down and it works in both directions. Drag a node that's in a signal path away from where it sits and it pops out, the wire heals itself through the gap and the sound carries on as if the node were never there. Keep dragging and hover over any other cable and the node is spliced in on the spot, so you can try a filter or a shaper in several places in a single gesture and hear each one as you go. Drag along a cable and the node stays put in it, drag away and it pops out again. Only the node's first input and first output (or its stereo pair) take part, any other cables into the node stay where they are. Let go where you're happy, and the whole gesture is a single undo step.

Shift+Delete removes a node and heals the wire. Whatever was feeding the node's first input is connected straight through to whatever its first output was feeding, so deleting a filter from the middle of a chain doesn't break the chain. Stereo pairs heal channel for channel. A plain Delete just removes the node and leaves the gap.

Wire Debugging

The tooltip that appears when you hover over a cable has 4 modes, chosen from the 'Wire Debugging' submenu in the 'View' menu, or cycled with Shift+W:

  • Text: A live readout of the value on the cable, the same readout you get on a port.
  • Meter: A level meter, showing the last second or so of the signal.
  • Scope: A scrolling scope of the signal. It switches between a 0 to 1 and a -1 to 1 range by itself, and anything that goes over the range is drawn in red at the edge.
  • Latency: The number of samples it takes the signal to arrive at the far end of that cable, counted from the start of the Collection that the cable belongs to. Useful when you're building parallel paths that need to line up, and for seeing where a feedback path adds its one sample of delay. Note that it counts within a single Collection only, so a cable arriving from another Collection starts the count again from 0 (see 'Audio Collections' below).

Views (Patches Inside Patches)

A View is a container, and on the Canvas it behaves like a sub-patch. Double-click a View to go inside it and see its contents, and double-click on an empty part of the Canvas to come back out again. You can also select some nodes and press Command+G to wrap them up inside a new View, or Shift+Command+G to unwrap one.

When you wrap up a selection any cables that crossed the edge of the selection are turned into ports on the new View automatically, so the patch keeps working exactly as it did, and unwrapping a View turns them back into ordinary cables. Wrapping and unwrapping are each a single undo step.

When you're inside a View, move the mouse near the left or right hand edge of the Canvas and a small round '+' button appears in the corner. Click it to add a port to the View, which opens a strip down that edge listing the View's ports, inputs on the left and outputs on the right. Connect a cable to one of the ports on the strip and the signal is passed out through the View's own box on the Canvas outside, where the same port appears as an ordinary port that can be patched like any other node's. Click a port's name on the strip to rename it. On the outside of the View a port that isn't yet connected to anything is drawn hollow, and fills in once it's wired.

Views are the way to build your own modules: wrap a handful of nodes up, give the View a name and some ports, and it can be patched, duplicated and saved as a snippet just like anything else.

Audio Collections

The audio modules aren't separate objects that are created and destroyed as you patch. They come as a 'Collection', a curated, fixed rack of DSP modules built into the plugin, with a set number of instances of each one already there waiting to be used. Each plugin ships with its own Collection, or its own set of Collections, chosen to suit that instrument, and the plugin's manual lists what's in them. A plugin might ship a Monophonic, a Polyphonic and an Effects Collection for example, one running before the synth engine, one inside its voices and one after it.

Patching doesn't build anything, it simply decides which module listens to which, and because of that the Editor behaves quite differently to a patching environment that has to compile its patches:

  • Nothing is ever compiled: There's no build step, no waiting and no progress bar, your changes are live as you make them.
  • Re-patching doesn't interrupt the audio: You can rewire the patch while a note is sounding without any clicks or dropouts.
  • State is always kept: Filters, delays and envelopes carry on running while you change the patch, because they were never torn down and rebuilt.
  • It runs a sample at a time in a fixed order, so a signal can be fed back into itself with a single sample of delay, which is what makes feedback FM, resonators and similar structures possible.
  • Idle modules cost nothing: Any instance that you haven't patched is switched off, and a whole Collection is skipped when nothing is reaching its Output.

Each module type has a limit to the number of instances you can use. Once they've all been used up that module is greyed out in the 'Add' menu, in the Library and in the quick-add list, and duplicating or dropping another one displays a brief message on the Canvas. The limits are set generously, and are much higher for the small building blocks than they are for expensive modules like the filters and delays.

When a plugin has more than one Collection each one has its own category in the Library and its own module colour on the Canvas. Buzz Zone and FM Zone, for example, each come with 3 Collections: a Monophonic Collection that runs before the synth engine, a Polyphonic Collection that runs inside each of the engine's voices, and an Effects Collection that runs after it. Modules from different Collections can sit side by side on the Canvas and be cabled to each other directly, so to add an effect after a polyphonic patch you simply cable the last module of the poly patch to the first module of the effects patch. A buss named in one Collection can be received in another too. The quick-add list follows whichever Collection you last added from or clicked on, so it isn't cluttered with the same module three times over.

The Collections run in a fixed order, Monophonic, then Polyphonic, then Effects. A cable that runs with that order, from mono to poly, from poly to effects, or from mono to effects, arrives with no delay at all. A cable that runs against it, from the poly patch back to the mono patch, or from an effect back to the mono patch to modulate something, arrives one buffer late, in the same way that a feedback path within a single Collection arrives one sample late. That's fine for modulation and for feedback, just worth knowing if you're lining up audio paths.

A few conventions run through every Collection, so you only have to learn them once. Most signals run from -1 to 1 or 0 to 1, pitch runs at 0.1 per octave, times are in seconds, and a gate triggers as it rises past 0.

Patching Into The Plugin

Three modules act as the way in and out of the plugin:

  • MIDI Input: Gives you note pitch, gate, pressure, pitchbend, mod wheel and some CCs as patchable signals.
  • The plugin's engine, as a module named after the plugin, with its knobs as input ports and its outputs as output ports, so you can take the engine's output off on its own or drive one of its controls from something you've built yourself. The plugin's manual lists its ports.
  • Output: Where the sound leaves the plugin.

There's also a 'Per-note Expression' module, which gives you the same per-note expressions that the Expression Panels write to.

The plugin plays as normal until something reaches the Output module. From that point on the patch is the signal path, so the engine is no longer connected to the output unless you connect it yourself. The smallest patch that gets you back to the normal instrument is the engine's MIDI inputs fed from MIDI Input and its outputs fed to Output, usually 3 modules and 4 cables, and it's a good place to start from. From there you can insert a filter between the engine and the output, ring-modulate the engine with an oscillator, or drive one of its knobs from an envelope follower.

Building And Editing Panels

The same Canvas holds the plugin's Panels and Triggers, so the MIDI modules, the on-screen controls and the audio modules all appear side by side and can be patched to each other. You can open up any of the factory Panels or Triggers, take them apart, modify them and save them back out as your own, or start from an empty Panel and build your own.

The padlock icon at the top left of the menu bar unlocks the plugin's own GUI so that you can drag and resize the controls while the patch is open (Command+E does the same thing), lock it again when you've finished. While the GUI is unlocked the arrow keys nudge the selected controls rather than the nodes, and the 'Align' and 'Distribute' items in the 'Edit' menu work on the controls (the 'Align Nodes' submenu works on the nodes at any time).

A few more items in the 'Edit' menu are there for GUI work:

  • Insert View adds an empty container of one of 3 kinds: 'Contents' for freely placed controls, 'Flexbox' for controls that lay themselves out in a row or column, and 'Tabbed' for a set of pages.
  • Paste Dimensions, Paste Item Properties and Paste Styling copy just the size, the properties or the look of one control onto another, and Paste Replace swaps the selection for what's on the clipboard.
  • Duplicate Unique and Paste Unique make a copy with fresh identities, for when you want a second copy of a Panel that works independently of the first rather than sharing its values.
  • Edit Utility Strip Only is ticked by default and limits the Editor to the Utility Strip. Untick it to open up the whole of the plugin's GUI to the Editor, which is how you rebuild the instrument's own layout.
  • Use Container Overlay switches the Utility Strip's own drag bars and overlays on and off. Untick it when you've built a single layout of your own in the Strip and don't want the overlay sitting on top of it. The setting is saved with the preset.

Controls that use an image (buttons, knobs with a film strip, backgrounds) have 'Load Image...' and 'Load SVG...' entries in their image menu, and list controls have 'Load Text File...'. Anything you load this way is stored inside the preset, so a Panel you've built with your own artwork can be shared with anyone who has the plugin.

The Browser And Snapshots Tabs

The Browser tab in the Drawer lists everything in the plugin's user folder: presets, Utility Strip Panels and Triggers, Strip Presets, samples, wavetables (on plugins that have them), sequences, renders and MIDI exports. Click a preset to load it. Everything else is dragged out of the Browser and dropped onto the plugin's GUI, a sample onto a sample slot, a Panel or Trigger onto the Utility Strip, a sequence onto a sequencer, just as you'd drop a file from the desktop, so you can build and audition a whole preset without leaving the Editor. The up and down arrow keys step through the list and the left and right keys open and close folders, so you can audition presets from the keyboard. Right-click any file to favourite it (a small heart marks your favourites), rename it, duplicate it, make a new folder, show it in the Finder or Explorer, or delete it.

The Snapshots tab holds the same snapshots as the plugin's own snapshot list. Drag one snapshot onto another to copy it, and click the 'X' on a snapshot to clear it.

Saving Your Work

Everything you patch is saved with the preset, and with the Strip Preset, in exactly the same way as the rest of the Panels and Triggers, and it's saved in your DAW project along with the plugin's state. So you can close the Editor, close the project or save a preset at any point, and when you come back the patch, the Panels and any images you've loaded are exactly as you left them, ready to carry on with. Presets you build in the Editor can be shared like any other preset, and everything the patch needs travels inside the preset file. The 'File' menu can also save and load the whole workspace as an XML file, and the 'Snippets' menu saves the current selection as a re-usable snippet and lists any snippets you've already saved, ready to drop into another patch (they're listed in the Library too). Snippets are stored in the plugin's own folder, at "~/Library/Application Support/Toybox/[Plugin Name]" on macOS and "C:\Users\[your username]\AppData\Roaming\Toybox\[Plugin Name]" on Windows, and 'Open Snippets Folder' in the 'Snippets' menu takes you straight there.

Keyboard Shortcuts

'Command' is 'Ctrl' on Windows and 'Option' is 'Alt'.

  • Return: Quick add at the mouse position
  • Tab: Show or hide the Library
  • F2 or Shift+Return: Rename the selection
  • Arrow keys: Nudge the selection (or the GUI controls while the GUI is unlocked)
  • Shift / Control / Option + Up or Down: Nudge the number under the mouse by 1, 0.1 or 0.01 ('Shift+Control' for one semitone)
  • Shift+Drag a header: Live patching in and out of cables
  • Option+Drag: Duplicate the selection
  • Command+Drag: Snap to the coarse grid
  • Shift+Drop a cable: Join an input that's already connected
  • Option-click a port: Set it to 1 or 0 ('Shift+Option-click' for 0, 'Command-click' to clear it)
  • Delete: Delete the selection ('Shift+Delete' heals the wire through the gap, 'Command+Delete' deletes a node's contents)
  • Command+Z / Shift+Command+Z: Undo and redo
  • Command+X / C / V: Cut, copy and paste
  • Shift+Command+V: Paste Unique ('Option+Command+V' Paste Replace, 'Shift+Option+Command+V' Paste Item Properties, 'Shift+Option+Command+D' Paste Dimensions, 'Command+T' Paste Styling)
  • Command+D: Duplicate ('Option+Command+D' Duplicate Unique)
  • Command+A: Select all ('Command+P' selects the parent, 'Command+U' deselects)
  • Command+G: Wrap the selection in a View ('Shift+Command+G' unwraps one)
  • Command+N: Insert a Contents View ('Shift+Command+N' Flexbox, 'Option+Command+N' Tabbed)
  • Command+E: Unlock or lock GUI editing
  • Command+[ and Command+]: Send backward and bring forward, add 'Shift' to send all the way
  • Shift+W: Cycle the Wire Debugging mode
  • Command+S / Shift+Command+S / Command+O: Save, save as and load the workspace XML
  • Command+R: Refresh the Editor
  • Shift+Option+E: Open the Editor window
  • Command+W: Close the Editor window