Plugins

LOOM plays effects and instruments from other makers: Audio Units and VST3 plugins installed on this Mac. You load them into the same slots as LOOM's own effects, and on an instrument track in place of LOOM's own instrument. LOOM draws each plugin's controls as its own, so you map them, automate them and put them on macros as you do LOOM's.

This chapter is where to start. It says what LOOM does with a plugin and links to the page that describes each part in detail.

Mapping, automating and macros on a plugin's controls

Right-click a control in a plugin's drawer to open its menu:

You can also hold Control and click the control.

The same menu is on an instrument plugin's controls in the editor dock. Mapping, automating and making a macro of a plugin's control describes each item in full.

You can also start from the chooser instead of the control. Each of these lists a slot that holds a plugin by the plugin's name, with its controls under it:

• The Map a control chooser, from + ADD MAPPING in the MIDI Mapping window. See Adding a mapping.
• The lane chooser, from the + on a track's row in the arrange view. See A plugin's controls.
• The macro chooser, from an empty macro in the side panel. See Assigning a macro.

A plugin can have hundreds of controls. Type part of a control's name in the chooser's search field to find it.

A plugin can mark a control as one a host must not change while it plays. On such a control, MAP…, ADD LANE and MAKE MACRO are greyed out, and the lane chooser lists it greyed. The Map a control chooser still offers it, because a mapping can still set it.

A lane, mapping or macro on a plugin's control is kept with the song when the plugin is missing or no longer has that control. It does nothing until the plugin is back, and you can point it at another of the plugin's controls. See Re-binding a lane or mapping.

How LOOM runs a plugin

Each plugin you load runs in a helper process of its own, outside LOOM. LOOM sends it each block of audio and plays the block it returns one block later. On a loop track, LOOM reads the loop that much earlier, so the plugin's output lands on time.

Because the plugin is not inside LOOM, a plugin that crashes or stops responding takes only its own slot with it. LOOM and the rest of the song keep playing, and LOOM restarts the plugin. See When a plugin crashes or stops responding.

LOOM finds your plugins the same way: it scans each one in a separate process, so a plugin that fails its scan cannot stop LOOM. See How LOOM finds plugins.

Finding your plugins

LOOM offers a plugin only after it has scanned it.

• The first time you open LOOM, it asks before it scans. See Look for plugins.
• To scan again, for example after you install a plugin, choose File ▸ Scan for Plugins… (⌥⌘P) or press RESCAN in GLOBAL › PLUGINS. LOOM never starts a scan by itself, and does not start one while any track is playing or recording.
• A plugin that fails its scan goes on the blocklist with the reason, and LOOM does not offer it. You can scan it again from there. See The blocklist.

GLOBAL › PLUGINS also holds the folders LOOM looks in, which formats the choosers offer, and the memory budget. See PLUGINS.

Putting a plugin on a track

Instrument plugins are listed only by KIND. The effect chooser lists effects.

When LOOM loads a plugin, the slot's tile shows a dashed outline and LOADING until the plugin is ready, then the time the plugin adds, such as +2.7 ms. A large plugin can take several seconds to load. While it loads, its drawer shows the plugin's name and maker, and LOADING… in place of the search field, with a short line that moves across under it for as long as the plugin loads. The controls appear when the plugin is ready. A screen reader gets the same state: the plugin panel's description, and a line of text in the search field's place, read Loading followed by the plugin's name. When a plugin whose loading you have seen in the drawer or the instrument dock is ready, LOOM announces its name followed by is ready. If it cannot load, LOOM announces the words its drawer then shows. The ANNOUNCE switch controls these announcements; see What "accessible" means in LOOM. If LOOM cannot find the plugin, the slot reads MISSING and the drawer shows the same words and buttons as for a song with a missing plugin. See A song with a missing plugin.

The plugin's drawer

Click a slot that holds a plugin to open it in the drawer, as you open one of LOOM's effects. For an instrument plugin, open the editor dock from the track's INST tab. The drawer draws the plugin's controls as LOOM controls, so you edit the plugin with the mouse and the keyboard as you edit LOOM's own effects.

From top to bottom, the drawer holds:

• The header. The plugin's name, its maker, its format and its version, then three readouts: CPU, MEMORY and LATENCY. See Memory and CPU. OPEN WINDOW opens the plugin's own window.
• The PRESET bar. It lists the plugin's own presets and the ones you saved in LOOM. See Presets, racks and sounds.
• The search field. Type part of a control's name, and the drawer shows only the controls that match, under RESULTS. MAPPED ONLY shows only the controls that a mapping, a lane or a macro uses.
• The controls. The ones the plugin's maker marks as its main controls come first, under IMPORTANT. Then come the plugin's own groups, under the names the plugin gives them, and last ALL OTHERS. When a plugin nests its groups, a group's heading shows its path, without the levels that every group shares, such as OSC 1 › ENVELOPE. A plugin with few controls shows them in one list, with no headings. A group with many controls shows them as compact rows, with a line such as + 12 MORE IN FILTER · SHOW ALL at its foot. In a compact row, a control that would be a knob is drawn as a horizontal slider, to save space. Press that line to show the rest. Press a group's heading to fold the group away.
• BYPASS SLOT and REMOVE, at the foot, as on LOOM's own effects. An instrument plugin has no BYPASS SLOT.

How the drawer draws a control

LOOM chooses a control for each of the plugin's settings from what the plugin reports about it: TOGGLE, SEGMENTED PAIR, CELLS, STEPPED KNOB, STEPPER, KNOB or BIPOLAR, a knob centred on zero. A plugin's own bypass is not drawn, because BYPASS SLOT does that job.

A knob's name stays inside the knob's own column. A name too long for one line takes a second line, and a name too long for two lines ends with …. To read the whole name, hold the pointer over the knob.

To draw a control another way, right-click it and open DRAW AS. The control drawn now is ticked, and the one LOOM chose reads inferred. In a compact group, the tick shows the control the parameter gets when its group is drawn as a grid; the compact row still draws a knob as a slider. A control that does not suit the setting is greyed out, with the reason beside it. RESET TO INFERRED goes back to LOOM's choice.

Your choices are kept for each plugin on this Mac, not in the song. Every song that uses the plugin draws it your way.

The plugin's own window

OPEN WINDOW opens the editor the plugin's maker drew, in a window of its own. A change you make in either place reaches the plugin. See A plugin's own window for where it opens, how long it stays open and which keys reach LOOM while it is in front.

⌘Z does not undo a change you make in the plugin's own window.

Presets, racks and sounds

• A slot's PRESET bar lists the plugin's own presets under FROM and the plugin's name, and the presets you saved in LOOM under USER. A USER preset holds the plugin's whole state. See Racks and presets.
• A rack holds the whole chain, with each plugin's settings, and can mix plugins with LOOM's own effects. See Racks and presets.
• An instrument plugin's programs are listed by the PROGRAM row in the editor dock, under FROM and the plugin's name. A program is not a sound: save the sound to keep the change. See The editor dock.
• A sound can hold an instrument plugin with its settings, and the plugins in the track's effect slots. See SOUND and Presets with effects.
• In the arrange view, a node on a slot's PRESET lane switches the plugin to one of its presets at a bar. See A plugin's presets. LOOM loads the plugins that rack and preset nodes need when you open the song, never while it plays. See Plugins at a node.

Memory and CPU

LOOM keeps the plugins in a song inside a memory budget, and does not load a plugin that would take the song over it. When a song or a rack brings back a plugin that does not fit, its slot reads OVERLOADED and keeps the plugin's settings. See A plugin's memory. You set the budget under MEMORY BUDGET in GLOBAL › PLUGINS. The line under it says how much memory the plugins in this song use now.

The drawer's header shows what the plugin uses now:

While CPU HIGH shows, the slot's tile carries an amber bar along its top and reads CPU HIGH with the same average. The warning clears when the average stays below 60% for about two seconds, so a plugin whose load varies from block to block does not switch it on and off. While a plugin is not running, all three readouts read —.

Latency

A plugin's output is later than its input. What that means depends on where the plugin is:

• On a loop track, LOOM reads the loop early, so the loop plays on time. The tile shows what the plugin adds, such as +2.7 ms.
• On an input, you hear the input later, because LOOM cannot read a live input early. The tile carries a small clock badge, and the input's drawer header says how late, such as YOU HEAR IN 1 +5.3 ms LATE. LOOM places the take where you played it. See A plugin on an input.
• On an instrument track, notes you play live sound slightly late, and the notice line says by how much when the plugin loads. Notes the loop plays are on time. See INSTRUMENT.

Some audio interfaces deliver their blocks unevenly. On one of those, LOOM gives every plugin one more block, and what you play live through a plugin is one block later. See A plugin and an audio device that delivers its blocks unevenly.

A song with a missing plugin

When you open a song that uses a plugin this Mac does not have, LOOM opens the song anyway and keeps the plugin's settings:

• An effect slot reads MISSING, with the plugin's name struck through, and passes the sound through unchanged.
• An instrument plugin leaves its track silent. What you play on the track is still recorded.

The notice line names the plugins that are missing. The slot's drawer says where LOOM looked for the plugin and lists the settings it kept, which you cannot change. Each kept setting has a dashed track, because you cannot move it. REPLACE… takes the plugin and its kept settings out of the slot and opens the chooser, so you can choose something else. For a missing instrument plugin, see The editor dock.

To load the plugin once it is installed, press RESCAN in the drawer or the instrument dock. RESCAN looks for the plugin where the song says it was installed: for a VST3, the path the drawer names. It does not scan your plugin folders; to do that, see Finding your plugins.

• While it looks, the button reads SCANNING… and you cannot press it, and SCANNING… with a short moving line appears under it. LOOM looks for one plugin at a time. A screen reader gets Scanning for followed by the plugin's name, and LOOM announces what it is looking for.
• If the plugin is there, the notice line says where LOOM found it, and the slot loads it with the kept settings. The drawer shows LOADING… until the plugin is ready.
• For an Audio Unit, LOOM can only find the plugin by loading it, so the slot tries to load it each time, and the notice line says that LOOM is looking for it again.
• If the plugin is not there, the drawer, the notice line and the announcement say what LOOM looked for and where. Install the plugin at that path, then press RESCAN again.
• If the plugin is there but does not load, the slot reads MISSING again, and the drawer says that LOOM found the plugin and it did not load, below the drawer's reason.

Saving the song keeps the missing plugin's settings, so the song plays as it did once the plugin is installed. Lanes, mappings and macros on its controls are kept too, and do nothing until it is back.

A sound or preset whose plugin is missing asks for a second Return before it loads. See The sound library.

Opening the song in an older LOOM

A version of LOOM that cannot automate a plugin's controls cannot read an arrangement that has lanes on them. It opens such a song with an empty arrangement, and the notice line reads the Score could not be read (RefusedUnknownControlDestination). To get the arrangement back, open the song in this version of LOOM or a later one.

A plugin that did not start

LOOM connects each plugin to the audio device's timing, so that the plugin keeps time with the device. Some audio devices do not let LOOM do this. This can happen when two audio devices have the same name. LOOM then does not start the plugin, and keeps its settings:

• An effect slot reads NOT STARTED and passes the sound through unchanged. An instrument plugin leaves its track silent. The plugin's name is not struck through, because the plugin is installed.
• For an instrument plugin, the editor dock's header and KIND show the plugin's name followed by · NOT STARTED, where a plugin that is not installed shows · MISSING.
• The notice line says the plugin did not start because LOOM could not connect it to the audio device's timing. It does not say the plugin is missing, because LOOM did not look for it.
• The slot's drawer says why the plugin did not start and lists the settings it kept. It offers REPLACE… and no RESCAN, because looking for the plugin again does not change the audio device.
• A plugin you load on that device is refused for the same reason.

Choose another audio device in LOOM. When LOOM can connect to the new device's timing, each of these slots loads as it was, with its settings, and you do not need to quit LOOM.

When a plugin crashes or stops responding

A plugin that crashes, or stops returning audio, takes only its own slot with it:

• An effect passes the sound through unchanged until the plugin is back.
• An instrument plugin is silent until the plugin is back. The notes it was holding stop.

LOOM restarts the plugin by itself, with the settings it had a moment before. While it restarts, its tile reads RESTARTING with a count, such as RESTARTING 1 OF 3, and the notice line says so, for example:

Plate 140 on TRACK 2 · SLOT 3 stopped responding and is restarting with its last settings. It passes dry until it is back.

When it is back, the notice line says it restarted and is playing again. If the plugin's own window was open, it opens again in the same place.

A plugin that stops responding is treated as a crash: LOOM ends its process and starts it again.

If a plugin crashes again and again within a minute, LOOM stops restarting it. Its tile reads STOPPED · CRASHED in red, the slot passes the sound through unchanged, or an instrument stays silent. The notice line says so, for example Plate 140 on TRACK 2 · SLOT 3 crashed 3 times in a minute and has stopped. It passes dry. Open its drawer to restart or remove it. The drawer says why the plugin stopped and shows its settings, read only.

To start the plugin again, press RESTART in its drawer. It loads with the settings it had when it stopped, and its count of crashes starts again. To take it out, press REMOVE: the slot then opens the chooser. A stopped instrument plugin has the same two buttons in the editor dock, where REMOVE takes the plugin off the track and the track plays the synth at its default settings.

When a plugin is late

A plugin that misses a block, without crashing, plays nothing for that block: an effect passes the sound through unchanged and an instrument is silent. Its tile shows an amber notch and reads MISSED with how many blocks it missed and when, for a few seconds. The notice line says how many blocks were late, for example Plate 140 on TRACK 2 · SLOT 3 was late 3 times; those blocks passed dry.

A plugin that takes too long to load is not loaded. The notice line says so with the red tag NOT LOADED.