uapmd-app UI Guide (AI slop)

NOTE: it is an AI-slop documentation where the screenshots are all taken at v0.5.6+. uapmd-app is a quickly moving target and the sshots will quickly get outdated. Please bear with that.

This is a screen-by-screen reference for uapmd-app, the ImGui-based reference host that ships with UAPMD. It describes what each control does and where to find it.

For the wider picture -- what UAPMD is, how to obtain audio plugins on each platform, and what source separation needs from you -- read USERS_GUIDE.md first. This document assumes you already have the app running.

Screenshots were taken on macOS with the dark theme. Layout is identical on the other desktop platforms; on Android, iOS and Web the same widgets are laid out for the available screen space.

• Starting the app
• The main window
• The toolbar
• The timeline
• Tracks
• Clips
• Clip editors
• Plugins
• Projects and rendering
• Settings
• Addins
• Automating the app

Starting the app

On desktop the executable takes a few optional arguments:

A positional argument is treated as a project file to load.

The main window

Everything lives in a single window with four bands, top to bottom:

1. The toolbar -- engine power, transport, global commands, display scale, theme.
2. The navigator row -- the time-unit switcher, the zoom slider, and the whole-song position controller.
3. The track list -- the master track followed by your tracks, each with a legend on the left and its clips on the right.
4. The footer -- add a track, and open the Mixer Monitor window.

Auxiliary windows (Settings, Plugin Selector, editors, and so on) open as floating panels inside the main window. They can be moved and resized like ordinary windows, and their positions are remembered between runs.

At launch you get three empty tracks and an empty master track. Nothing is loaded and nothing is playing, but the audio engine is already running.

The toolbar

Audio Engine

The leftmost button reports and toggles the audio engine. It is green when on and red when off. Turning it off releases the audio device and disables the transport buttons; turning it back on re-activates the device and the plugins on it.

If parallel processing fails -- audio workers miss their deadline, or a plugin fails on a worker -- the button reads Audio Engine: Restart. Its tooltip says what to change in Settings (fewer workers, a larger buffer, or Serial); click it to restart.

System

System is the catch-all menu:

• Undo / Redo at the top, labelled with the operation they will reverse (for example "Undo Add track"). They are greyed out when there is nothing to undo, and a "History operation in progress..." note appears while one is still running. The keyboard shortcuts work anywhere outside a text field: Ctrl+Z / Cmd+Z to undo, Ctrl+Shift+Z / Cmd+Shift+Z or Ctrl+Y to redo.
• Device Settings, UAPMD Addins, Scripting, and MCP Settings -- toggles for the four floating panels described later in this document. A check mark shows which of them are open.
• Application commands contributed by addins, below the separator: JSFX Settings (JSFX effects), Virtual MIDI Devices (virtual MIDI devices), and Augene2 Integration (MML import), depending on the build and the enabled addins.

Project

Project offers:

• New Project, Load Project, and Save Project. Starting a new project or closing the app while there are unsaved changes prompts you first, unless you launched with --no-confirm-on-quit.
• Render To File.
• Import MIDI Tracks (SMF) -- pick a MIDI 1.0 .mid file; each of its tracks becomes a track holding a MIDI 2.0 clip.
• Import Split Audio Tracks -- opens the split-audio import window. This item only appears while at least one stem separation addin is enabled.
• Project commands contributed by addins. What appears here depends on which addins are enabled: master-track population (libsonare and librosa.cpp) and audio-to-MIDI transcription of all audio clips (pitch-detection for monophonic, basic-pitch for polyphonic, DrumScript for drum material).

Scale and theme

UI: picks the UI scale factor -- x0.5, x0.8, x1.0, x1.2, x1.5, x2.0, x4.0. Changing it rescales every widget and font, and resizes the window to match. The button next to it (a half-filled circle) switches between the dark and light themes.

Plugins

Plugins toggles the Plugin Selector.

Transport

Three buttons, all disabled while the audio engine is off:

During playback the playhead marker moves along the ruler, a vertical line tracks it in the position controller, and the two spectrum analyzers right after the transport buttons show input and output activity.

Spectrum analyzers

In and Out at the right end are live spectrum displays of the audio input and the final output bus.

The timeline

Time units

The View: Seconds / View: Beats button switches the ruler and the clip positions between absolute time and musical time. The two views are independent -- each keeps its own zoom.

Snap

The combo beside the view switcher is the timeline snap. When you move or resize a clip with its grips, the edge you drag -- the start, for a move -- lands on the nearest multiple of that note length, counted from the start of the timeline through the tempo map, in either view. It offers the piano roll's divisions -- Free, 1/8, 1/16, 1/24, 1/32, 1/48, and 1/64 -- and defaults to 1/16. Free turns snapping off, and holding Alt while dragging places freely.

Zoom and position

The slider after the snap combo is the timeline zoom, showing pixels per unit. It is logarithmic and spans four orders of magnitude, so small drags near the left end still move a useful amount.

The wide bar filling the rest of the row is the position controller. It shows the entire song: one lane per track, each clip a small bar, with a translucent rectangle marking the region currently visible below. Drag it to scroll the track list.

The master track

The first row is the master track. It carries the tempo and time-signature meta events that the beats view is built from, and it can host its own plugin chain via Add Master Plugin. It has a gain slider but no mute or solo.

The footer

+ adds an empty track. Mixer Monitor opens the mixer window described below.

Tracks

A track owns an audio plugin graph and a set of clips. It is not "a plugin" -- a track typically holds one instrument plugin followed by zero or more effects, or, for audio material, just effects.

Each track legend has two rows of controls.

Row 1 -- clipboard icon, graph icon, gain slider, M, S:

Row 2 -- snowflake icon, the plugin button, ⋮:

The ⋮ menu holds the two actions that are destructive or easy to hit by accident: Bypass Track Processing (which stops the track's plugins from processing while leaving them loaded) and Delete Track.

Most of these controls are disabled while a track is busy -- for example while a freeze render is running.

Clips

A track can hold both audio and MIDI 2.0 clips at the same time. On playback both are fed into the track's graph, sliced per sample block. The usual reason to mix them is automation: an audio clip carrying the material, plus a MIDI 2.0 clip carrying Assignable Controllers that drive the effect plugins.

The clip menu

The clipboard icon in the track legend opens the clip menu, which applies to the track as a whole:

• Edit Clips... -- opens the per-track clip editor window.
• Add an Empty MIDI2 Clip / Add Empty Audio Clip.
• Create Audio Clip From File... -- .wav, .ogg, .flac.
• Add a MIDI Clip from File... -- a MIDI 1.0 .mid file, translated to MIDI 2.0.
• Add MIDI2 Clip from File... -- a MIDI 2.0 clip file (.midi2).
• Clear All -- removes every clip on the track, after a confirmation.

The master track offers the same menu minus the audio-clip and Clear All entries.

Selecting and editing clips

Drag across the lanes in either timeline view -- from empty space or from a clip -- to select the clips the rectangle crosses. A drag that starts on empty space and crosses no clips is a range instead, and offers Add New MIDI Clip and Add Empty Audio Clip sized to the dragged span on release; in the beats view the range snaps to the nearest quarter-note beat. Alt-drag always takes the range reading and leaves the selection alone. Shift-click or Shift-drag adds to the selection; Ctrl-click (Cmd-click on macOS) toggles a clip. Click an unselected clip to select it alone. Click empty space, or press Escape while hovering the timeline, to clear selection. The track's Clips and More menus include Select All Clips.

Clips move and resize through the grips at their two ends, never by dragging the clip itself. The upper half of a grip resizes that end; the lower half moves the whole clip. A grip sits just outside its clip, or just inside it where the clip meets a neighbour or the start of the timeline. Resizing the start keeps the content where it is on the timeline: shortening it hides the beginning, and lengthening it brings that back. A MIDI clip can be lengthened past the start of its content, down to the start of the timeline, and the content shifts along so the new space can hold notes; an audio clip stops at the start of its file. While you drag, an outline shows where the clip will go, and every edge follows the snap.

Right-click or double-click a clip to open its context menu; on Android and iOS, press and hold it too. Opening the menu on a selected clip keeps the other clips selected, so the commands below that act on the selection act on all of it. Press and hold is how touch devices reach these menus: hold for half a second without moving, and the press opens the menu instead of selecting. The desktop has no press-and-hold menu, since a held press is how a drag starts there:

• Show Dump List -- the MIDI event list editor.
• Edit Audio Events -- the audio marker and warp editor. Enabled for audio clips only.
• Open Piano Roll -- the piano roll editor.
• Open Step Sequencer -- the step sequencer. Enabled for MIDI clips only.
• Cut, Copy, and Delete apply to all selected clips. Disable Clip / Enable Clip applies to the clicked clip; a disabled clip stays on the timeline but is not played.
• Paste here inserts copied clips relative to the clicked track, preserving their track offsets. For multi-track copies, its submenu previews the source-to-destination track mapping, destination plugins, and clip counts. Choose Paste into these tracks to apply it.
• Paste to original tracks follows the original tracks by persistent identity, even if tracks have been reordered since copying. If an original track was deleted, nothing is pasted.
• Both paste modes start at the clicked time, preserve time spacing, and select the new clips. Destinations must exist and be visible. Pasted clips get fresh identities and absolute positions. Cut, paste, and group deletion each form one undo step.
• Add an Empty MIDI2 Clip Here, Add Empty Audio Clip Here, Create Audio Clip From File Here..., Import SMF Here... -- these use the timeline position you double-clicked as the new clip's start.

Right-clicking, double-clicking, or pressing and holding empty space also offers selection and clipboard commands. Paste from a track header's Clips or More menu uses the playhead position. The internal clip clipboard is cleared when the project is cleared.

Clip editors

The piano roll

The piano roll edits the notes of a MIDI 2.0 clip. Its toolbar carries H Zoom in pixels per second, V Zoom as the height of one semitone row, and a Snap division. Snap defaults to 1/16, with Free, 1/8, 1/16, 1/24, 1/32, 1/48, and 1/64 available. The header also reports the clip length, the note count, and how many clip-level events it holds. Snap labels denote musical note durations relative to a whole note; for example, 1/16 is a sixteenth-note grid.

Drag across empty grid space to select notes. Shift-click or Shift-drag adds notes; Ctrl-click (Cmd-click on macOS) toggles a note. Clicking an unselected note selects it alone. Click empty space or press Escape over the grid to clear selection. Selection highlights use the note rectangles, and selected notes remain selected when an edit changes their event order. Reloading changed clip content, including undo/redo, clears note selection; refreshing unchanged content preserves it.

Right-click a note or empty grid space (long-press on Android and iOS) for Cut, Copy, Paste here, Delete, and Select All Notes. Opening a menu on a selected note preserves the selection. The clipboard belongs to that open clip: it does not transfer notes between clips, and closing the piano-roll window discards it. Paste preserves pitches, durations, relative timing, MIDI group/channel, velocity, release velocity, note attributes, and attached per-note automation. It starts at the clicked time, snapped to the grid, and selects the pasted notes. Clip-level controllers are not included in a note copy. Each cut, paste, or group deletion is one undo step.

While the pointer is over the note grid, Ctrl/Cmd+A selects all notes, Ctrl/Cmd+C/X copies/cuts, Ctrl/Cmd+V pastes at the pointer's snapped time, and Delete/Backspace deletes selected notes. Double-click still creates a note in empty space or requests deletion of the clicked note. Dragging a selected note moves all selected notes in time and pitch, preserving their spacing, durations, and pitch intervals. Attached per-note automation follows each note. The clicked note anchors grid snapping; the whole group stops at time zero or MIDI pitch limits. Release commits one undo step and keeps the moved notes selected; Escape cancels the drag. Edges also move the group when multiple notes are selected. Group resizing and property editing are not included: the property popup and lower panel edit the primary note. Single-note edge dragging still resizes that note.

Selecting a note fills the lower pane with that note's per-note events, where you can insert an event before the selected one, edit its type and value, or delete it. With no note selected the pane lists the clip-level automation events instead.

The step sequencer

Open Step Sequencer edits a MIDI clip as a grid of steps: one row per note, one button per step. The toolbar sets the Note set (GM Drums or All Notes), the pattern Steps (1-128), its loop Repetitions (1-64), the step Division (1/1 to 1/32), and the Default Velocity and Default Gate given to newly activated steps. The header reports the pattern length and the expanded length in ticks.

Clicking a step toggles it. An active step opens an inline editor for its velocity and a MIDI 2.0 note attribute type and value; double-click a slider to type a value. Edits apply to the clip immediately, and Reload re-reads the clip. The Velocity / automation pane below the grid shows the velocity of each active note as a bar.

The step sequencer records its pattern in the clip as Flex Data metadata. Opening a clip that was not made by the step sequencer first asks for confirmation, since editing it may discard notes or other data the step grid cannot represent; opening alone changes nothing.

The MIDI event list

The dump list is the raw view of the same clip: one row per UMP, with its tick position, its absolute time, its delta from the previous event, and its message bytes. The example above shows MIDI 2.0 note-ons and note-offs (40 90 3C 00 60 00 00 00 is a note-on for note 60).

Edits here are staged, not applied immediately -- change what you need, then Apply Changes, or Discard Changes to reload the clip as it stands. The ⋮ button on each row inserts an event before it or deletes it.

Audio events

For audio clips, Edit Audio Events opens an editor for the clip's markers and warps. Markers name a position in the clip; warps map a position in the clip to a position on the timeline. Both are edited as lists, with Add Marker / Add Warp, and applied with Apply.

Plugins

Finding and loading plugins

The Plugins button opens the Plugin Selector. UAPMD always performs a fast scan at startup, which discovers plugins without instantiating them -- this covers CLAP, LV2, AUv2, AUv3, and those VST3 bundles that ship a moduleinfo.json.

Everything else needs a real scan, which is what Scan Plugins does. Two checkboxes control it: Force Rescan discards the cached results, and Remote scanner process runs the scan in a separate process on desktop, so that a plugin which crashes on load cannot take the app down with it. Timeout (s) bounds how long a single bundle may take.

Bundles that failed are collected under Blocked bundles, which expands to list them and offers Clear blocklist, Show scan report, Copy as Markdown, and a table preview.

Search: filters the table, which sorts by format, name, vendor, or ID. Select a row and press Instantiate Plugin.

Destination below the button says where the plugin will go. It reads New Track (new UMP device) by default; opening the selector from a track's Add Plugin entry instead targets that track, and from the master track's entry it targets the master track. When a new track is created you can give its virtual UMP device a name and pick the MIDI API to expose it on.

JSFX effects

Where the build includes JSFX support, REAPER JSFX effects appear in the plugin list as the JSFX format, and open their own graphics in a JSFX editor panel. System -> JSFX Settings manages where they come from:

• Copy effects in -- Copy in files or a .zip... copies effect files into the app's own content folder, optionally under a name given in Copy into.

• Where effects are looked for -- register folders to search, Re-read registered folders, and Also look in this platform's usual locations. Each listed folder has a Remove button.

• Plugin list -> Duplicate scripts -- Prefer latest version collapses copies whose paths differ only by a semantic-version directory, Hide exact copies only, or Show every script. Hidden copies stay available to projects that use them.

Every change rescans, and the window reports how many JSFX effects are available.

The plugin menu on a track

The plugin button in a track legend lists every plugin instance on that track, each with:

• Show / Hide <name> Details -- the instance details window.
• Show / Hide <name> GUI -- the plugin's own editor. Disabled when the plugin has no GUI.
• Delete <name> (at [n]) -- n is the plugin's position in the chain.

Add Plugin at the bottom opens the Plugin Selector targeting this track, appending to the chain.

Instance details

The details window is a playground for one plugin instance:

• Show UI opens the plugin's own editor, and the toggle next to it bypasses the instance.
• Save State / Load State write and read the plugin's own state.
• Delete removes the instance from the track.
• Pitchbend and Chan.Pressure sliders, and a MIDI keyboard you can click to audition the plugin.
• Presets lists the presets the plugin reports; selecting one loads it.
• UMP Group picks which UMP group of the track's virtual MIDI device drives this instance. Groups already in use are disabled.
• Parameters lists every parameter with its current and default value and a Reset button. Context and Value/Key narrow the list to per-note or per-key parameters where the plugin supports them, and Filter Parameters is a text filter over the names.

The plugin GUI

Plugin editors open as dedicated native windows, sized to whatever the plugin asks for and resized along with it when the plugin requests a new size.

The track graph editor

The graph icon in a track legend opens that track's audio graph. Nodes are the graph input, the built-in track volume node, each plugin instance, and the graph output; edges are audio and event connections. Ports are listed per node, so a plugin's channel layout is visible directly.

A track starts as a simple chain, and editing the connections turns it into a general DAG. Revert to Simple Graph puts it back to a plain chain. A minimap in the corner helps when the graph outgrows the window.

Virtual MIDI devices

Virtual MIDI Devices in the System menu opens a flat list of every plugin instance in the project, grouped by track, showing the format and the virtual UMP device each is exposed as. Disable unregisters its virtual MIDI device and Show opens its details window.

Create virtual MIDI 2.0 devices automatically is off by default. Turn it on to create devices for subsequently instantiated plugins, including plugins loaded from projects. Changing the checkbox leaves existing devices unchanged; use each row's Enable or Disable button to control them manually. Enable All and Disable All apply to all current instances without changing the automatic creation setting. Enable All uses the names entered in the device list. Default device names include a track suffix, such as sforzando [VST3] T1; master-track devices use Master. Custom device names are kept as entered.

Disabling the Virtual MIDI Devices addin unregisters its devices and removes the command. Re-enabling the addin creates devices for existing instances only when automatic creation is on.

Note that this window lists plugin instances, not tracks -- one track with two plugins appears as two rows.

The mixer monitor

The Mixer Monitor reports latency compensation. The header shows the audible and render positions and the current playback phase; below it, Playback Compensation and Input Monitoring select the compensation strategy, and the table breaks down each track's reported latency, render lead, holdback, tail, and routing.

Projects and rendering

A project saves the tracks, their audio and MIDI 2.0 clips, and the plugin graphs with their state. Save Project and Load Project live in the Project menu, along with New Project, which resets to the launch state after prompting about unsaved changes.

Rendering to a file

Render To File renders the timeline to a WAV file using offline processing -- faster than real time, and independent of the audio device.

• Output is the target path; Browse... opens a file dialog.
• Range is Entire Project, Loop Region, or Custom. The detected project length is shown underneath, and Custom lets you type absolute start and end times.
• Tail / Guard (s) extends the render past the end of the material, so reverb tails are not cut off.
• Infinite Tail decides what to do with plugins that never fall silent.
• Stop after silence, with Hold Length (s) and Threshold (dB), ends the render once the output has stayed below the threshold for that long.

A progress bar sits above Start Render, which becomes a stop button while a render runs.

Settings

System -> Device Settings opens audio and MIDI configuration:

• Input Device and Output Device, with their Sample Rate selectors.
• Buffer Size, or Use Platform Buffer Size to let the platform decide.
• MIDI Input Connections and MIDI Output Connections -- each row binds a platform MIDI port to a track, so you can play a track from external hardware or send its output out.

Changing the audio device restarts the engine, which reactivates every loaded plugin.

On desktop, two more controls govern parallel processing:

• Audio Workers -- Serial, or the number of worker threads used to process independent tracks concurrently. The default is a quarter of the CPU count, up to four. Graph providers or extensions that are not compatible with parallel processing keep their tracks serial.
• Stop audio engine on deadline overrun -- off by default: late blocks are silenced until the workers catch up, then processing resumes. Turn it on to stop the engine instead and require a restart. Overruns are always logged.

Addins

Several features are addins rather than built-in code, and the Addin Manager lists them all with their package ID, the extension point they implement, their state, and the library they come from. The checkbox in the first column enables or disables each one.

Addins ship built-in (the piano roll, the MIDI event list, ARA support, the Demucs and BS-Roformer stem separators, Basic Pitch), or come from a shared library placed in one of the directories named at the top of the window.

ARA support covers ARA-capable plugins on desktop, and AAP plugins that advertise the ARA extension on Android.

Disabling an addin removes what it contributes -- turn off both stem separators, for example, and Import Split Audio Tracks disappears from the Project menu.

MML import (Augene2)

Where the build includes Augene2, System -> Augene2 Integration compiles MML (Music Macro Language) sources into clips of the current project.

Import MMLs... adds compiled inputs and Import included MML... adds files they include; Resource folder optionally names where to resolve their resources. Each source is either linked to an external file or kept as a bundled copy in the project, with Relink... and Remove. Compile regenerates the clips; on failure the previous clips are kept and the diagnostics are listed. Track mapping shows which track each MML track went to. Automatic synchronization is not available yet, so press Compile after editing linked files.

Automating the app

Everything the UI does is also reachable programmatically, which is how UAPMD is meant to be driven for anything repetitive.

The script editor

System -> Scripting opens a JavaScript editor with Run and Load, plus Preset with the bundled Demo, PluginState, and TestDAG scripts. The demo script documents the API:

There is also an object-oriented wrapper (PluginScanTool, sequencer) imported from remidy-bridge; both styles work.

MCP

System -> MCP Settings exposes the app as an MCP server, so an agent can inspect and edit the project.

• Server mode listens on a port on 127.0.0.1 -- desktop only.
• Client mode connects out to a relay over WebSocket, with an optional auto-reconnect. This is the default on platforms without an embedded HTTP server.

Press Connect to start and Disconnect to stop; the status line above the button reports what it is doing. Launching with --mcp-server [port] starts server mode without visiting this window.

The tool surface covers tracks (list_tracks, create_track, add_plugin_to_track), clips (list_clips, add_midi_clip, create_empty_midi_clip, add_ump_event, remove_ump_event), transport (play, stop, jump, set_tempo), the graph (connect_track_graph, ensure_dag_track_graph, revert_track_graph_to_simple), history (undo, redo, begin_compound, end_compound), projects (save_project, load_project), presets, freezing, latency compensation state, and run_script for the JavaScript API above.

On the Web build MCP is always active as a JavaScript export instead, called through Module.ccall('uapmd_mcp_call', ...), with Module.ccall('uapmd_eval', ...) for scripts.