SHR-DAW

You can start with a Raspberry Pi and a terminal. A MIDI keyboard, control surface, audio interface, mixer, and dedicated display are optional.

Configure and start#

After installation, run:

shr-setup
shr doctor
shr

shr-setup keeps controller input and musical keyboard input as separate choices. It also asks about note spelling, MIDI output, JACK Audio Connection Kit (JACK) playback, audio capture, and optional CPU tuning. The wizard seeds four starter loops and ten cleared demo Projects. You may also choose a private MusicRadar loop download after reading its redistribution limit.

Run setup again when a controller, interface, sound card, or port layout changes. Remembered hardware choices are not replaced just because a device is temporarily disconnected. If the preferred playback pair is missing, SHR tries the configured fallbacks in order and reports which one it used.

shr doctor is a strict check of the complete setup. Missing JACK therefore produces a failing result even though the preset browser and external MIDI tracker can still open. Software instruments, WAV loops, effects, and audio recording require JACK. SHR-DAW never starts or restarts JACK.

Doctor groups its report into CORE / EDITOR, MIDI, JACK AUDIO, and AUDIO TUNING. It does not change policy or services. Each problem includes the relevant inspection or recovery command. The optional CPU policy and its rollback are documented in Raspberry Pi audio-system optimization.

The effects graph starts disabled. Software instruments, SHR Drums, and loops first use their configured direct routes. Read How SHR-DAW works before enabling the final bus or Input software monitoring.

Play something#

• Use the computer keyboard to navigate and enter notes. The tracker note keys are Z S X D C V G B H N J M.
• A configured MIDI keyboard adds velocity, chords, and live recording. Its musical messages bypass controller commands.
• A configured control surface provides the four-page menus, main encoder, pads, and mapped synth controls.
• In the FastTracker II (FT2)-style tracker, open FILES to load a seeded demo Project. Its portable AUTO routes use the destinations and channels configured on this machine.
• Open LIVE to perform existing Patterns without changing the saved Arrangement. Open LOOP for the selected Pattern's four WAV slots.

? and F1 open contextual Help. The Using SHR-DAW guide continues from here without repeating every screen action.

Terminal size#

The native layout is 40 columns by 13 rows. SHR adapts to the terminal cell size and reports when the window is too small. The installer does not change the console font, display resolution, desktop, window borders, scaling, or fullscreen mode.

Pixel resolution alone does not determine the available row and column count. Adjust your terminal settings if fewer than 40 columns or 13 rows fit.

Run a development checkout#

For a repository-local setup:

cargo build --locked --release
./scripts/setup-local.sh
./scripts/local.sh

The local helpers keep configuration, logs, Projects, Ideas, recordings, downloads, loops, and private presets below ignored $SHSYNTH_USER_DIR/. They preserve existing private files and do not install packages or start JACK. setup-local.sh configures the checkout. local.sh launches its target/release/shr, identified as REL in the TUI. Set SHSYNTH_USER_DIR to use another private root, or explicitly set SHSYNTH_BIN=target/debug/shr for a development launch.

Unusual hardware or recovery#

The installer and setup wizard are the normal path. For an uncommon controller, complex route, or recovery problem, follow the Codex-assisted setup brief. It keeps hardware inspection, audible tests, and system changes behind explicit permission.

After installing and signing in to Codex CLI, start that brief from the checkout:

codex -C . "$(cat docs/CODEX_ASSISTED_SETUP.md)"

Known USB controllers are matched during setup. Unknown devices can use the non-audible MIDI learner; learned mappings remain private. See Automatic controller setup and MIDI learn.

For a larger rig, continue with Physical connections.

Back to detailed guides

SHR-DAW is a Raspberry Pi groovebox and song-sketching workstation built around a 40×13 terminal. It supports a control surface, MIDI keyboards, the computer keyboard, and terminal pointer input. It is meant for quick musical work, not as a desktop production DAW.

From an idea to a sketch#

1. Start a Project or load one from FILES.
2. Choose a software instrument or a routed external MIDI instrument.
3. Play freely, record a MIDI Idea, enter tracker notes, add drums, or attach Pattern-owned WAV loops.
4. Build an Arrangement or perform the existing Patterns through LIVE.
5. Add only the effects and final processing the sketch needs.
6. Record the final stereo performance or synchronized raw stems.
7. Share the resulting files with tools outside SHR-DAW.

The intended idea-to-sketch target is roughly 10 to 15 minutes. That is a design goal, not a measured guarantee or a promise of a finished production.

Boundaries#

SHR-DAW has no desktop timeline, plugin windows, waveform editor, free-wiring matrix, unlimited mixer, offline song renderer, upload service, or messaging system. It does not replace Ardour, Ableton Live, Reaper, Bitwig, or another full production workstation.

The program helps you play, sequence, arrange, shape, and record your own choices. Proposed musical assistants remain in Future improvements; they are not current features.

Terms used in the guides#

• FT2 means the vertical Pattern editor inspired by FastTracker II. SHR-DAW is not an FT2 clone and does not read XM files.
• MTR is the on-screen performance meter and final-bus control surface.
• JACK is the JACK Audio Connection Kit, the low-latency audio server and connection graph. ALSA is the Advanced Linux Sound Architecture layer used for Linux MIDI and audio devices.
• A MIDI CC is a Control Change message. PPQN means pulses per quarter note and describes MIDI clock resolution.
• LUFS measures perceived loudness relative to full scale. dBTP means decibels true peak.
• XDG directories are the standard Linux locations used for private configuration and data.
• Owned means SHR-DAW started or created something and may safely change or stop it. An exact route is one saved endpoint that SHR never guesses.

Instruments and Playback#

The installed SHR-DAW sound system presents five melodic instrument families in Presets:

• synthv1 presets;
• Yoshimi .xiz banks;
• FluidSynth .sf2 and .sf3 SoundFonts;
• Moj Sint .mojsint Model D, Six-Op PM, Strange Oscillator, Swarm Machine, and Bass Matrix presets;
• SHR Sampler .shrinst packages.

Browsing is silent. LOAD is the only managed start or replacement action. Only one SHR-managed melodic engine runs at a time. The loaded instrument continues when you leave Presets or Playback and stops on replacement, Panic, shutdown, or an FT2 route that needs a different backend.

Playback shows held notes, decimal MIDI strike velocity, chord names, a keyboard-state strip when space permits, and 12 controls for the active backend. SAVE offers Overwrite, Save New, and Cancel for synthv1 and Moj Sint. Factory and system sounds stay read-only; saving them creates the next private User NNN sound for that engine and Moj model. The saved values become the current RESET baseline without restarting the engine. The new sound appears immediately in Presets and under its Moj model in FT2 ROUTE. When the running sound belongs to an FT2 route, only that active owner is retargeted; saving a standalone Player sound never rewrites unrelated Project routes. Cancel or a failed save preserves list/cursor state, values, held notes, and the live session. Unsupported engines remain visibly read-only. Idea capture and saving remain on the Ideas screen. SOUNDS returns to Presets and its visible LOAD.

Playback's PLAY page also owns the optional external-sync controller arpeggiator. PLAY sends Start even when no MIDI take exists, RECORD starts the same clock before capture, STOP ends it without unloading the instrument, and TAP changes tempo without silently starting transport.

Moj Sint keeps its own preset format and controls. Its current source catalog has 21 authored starts across six editable model families. SHR-DAW's public installer pin supplies the first 16 through Bass Matrix; the five Dual Filter starts require a compatible newer Moj Sint checkout. SHR Sampler packages are read-only and use their own strict format; the installed project-authored factory package is a neutral first-load sound. SHR Drums is separate from the managed melodic engine and runs in process. See SHR-DAW instruments and drums for the complete sound-system guide: Moj controls and saves, Sampler validation, Drums kits, routing, ownership, recovery, and public provenance.

Explore with N00B#

Playback N00B filters live melodic input to a selected root plus major or natural-minor scale. Allowed notes keep their pitch; other notes stay silent. The screen still shows the normal notes, chords, velocities, keyboard, and controls.

FT2 uses the same scale on melodic pages in Play, Record, and Edit. Record and Edit write only accepted notes. Moving to a percussion page turns the filter off. The Project stores its tonic and scale mode; SHR does not infer a key from audio or a finished Arrangement.

For a silent theory view of that stored key, open FT2 TOOLS, select the PAGE controller page, and choose HARMONY. It lists the neighbouring fifths, relative and parallel keys, and seven diatonic triads without changing the Project or playing anything. Back or Exit returns to the exact FT2 context.

For offline Pattern generation, open FT2 TOOLS, select PAGE, choose HISTORY, switch to RHYTHM, and open GEN. Euclidean triggers, accumulator progressions, seeded mutation, controlled drum fills, bounded EVEN/ACCENT/CRESCENDO drum rolls, cursor-row arpeggios, Project-key triads, and bounded diatonic harmony voices remain a visible draft while you adjust or inspect them. ARPEGGIO exposes order, octaves, row rate, gate, and repetitions; CHORD exposes degree, inversion, close/open voicing, three-lane placement, rate, and repetitions; HARMONIZER copies a selected lane span to another lane as a third/fifth above/below and makes out-of-scale refusal or skipping explicit. APPLY commits the draft to the current Pattern as one undoable edit, CLONE appends an independent Pattern and Arrangement step, and CANCEL writes nothing. The result is ordinary editable FT2 cells; playback does not regenerate it.

ROLL is the deliberate exception to the normal EMPTY ONLY default: its visible default is NEW CLONE because the selected source cell is already occupied. With that policy, APPLY performs the same independent Clone transaction. Choose EMPTY ONLY or REPLACE NOTE first only when you intend to target the current Pattern.

The practical loop is simple:

press -> hear -> see -> change -> compare -> ask why

Workspaces#

Home opens Software Synths, FT2, Recorder, Performance, MIDI Learn, Routing, Effects, Ideas, and Help. The main encoder browses; press it to select. Back returns one level. Controller MIDI never quits the application.

Shift plus the main rotary changes a second reversible browse axis only where one exists, such as Preset engine, FT2 column, Live lane, Loop slot, drum genre, FX target, or MASTER STRIP section. It stays inert where an accidental turn could trigger transport, confirmation, or a destructive action.

Ordinary overlays preserve their caller and discard unconfirmed drafts. FT2 ROUTE is the live-audition exception: valid active-field choices change the Project and live route at once, Apply keeps them, and Cancel restores the route snapshot from when the overlay opened.

Use these focused guides for exact actions:

• Screen and menu manual for every screen and controller page;
• Tracker guide for FT2 editing, routing, Patterns, Arrangement, drums, loops, and files;
• Controller interface for the complete physical action contract;
• Configuration and routing for machine settings and persisted route fields.

Live Patterns, Loop Mix, and Ideas#

Live Patterns lets you browse without launching, then queue activation at a Pattern or bar boundary. It can also capture successful activations for an explicit Append or Replace confirmation. Its lane mute, velocity, gate, and transpose controls are temporary and do not rewrite note cells.

Each FT2 Pattern owns up to four private WAV loop references. Loop Mix browsing does not launch audio. Arrangement and Live boundaries switch the MIDI and WAV owners together. A bad slot is isolated, and SHR does not time-stretch files.

Ideas preserve free-timed MIDI. A synthv1 or Moj Sint Idea includes its private preset snapshot; other backends keep their instrument reference. SHR Sampler stores the package's stable ID and configured path without copying its sample data. Loading an Idea restores its sound before playback.

See Live performance for boundary timing, capture, failure behavior, and realtime limits.

Automation, click, and MIDI export#

FT2 AUTO records compact Pattern-owned control curves independently from notes and cell commands. Arm only the lane you mean to write. Continuous controls ramp to the next point; switches, choices, modes, divisions, and bypass step at their point. Play Here and loops chase the effective value, and relative turns continue from the effective automated value when automation takes or releases ownership.

Keep CLICK on when recording from stop: SHR-DAW accents beat one, displays one bar of 4 3 2 1 → REC, and begins capture at row zero. Punching into a playing Arrangement starts immediately. The click is internal audio and never reaches an instrument or external MIDI output.

FILES EXPORT analyses, then confirms, a non-overwriting format-1 MIDI file for the whole Arrangement. Tempo, meter, parts, setup, notes/gates, and portable CC automation use the same musical-tick interpretation as playback. Loop audio and SHR-only effect automation are counted as omissions.

Effects and final sound#

Effects contains bounded source, aux, drums, and master processing. The Project owns rack order, parameters, routing, the fixed DRUMS Reverb-then-Delay rack, and the fixed MASTER STRIP.

With the optional graph disabled, ordinary source, aux, and master rack edits change Project data but do not process direct audio. The DRUMS rack still processes in-process drums on their direct path. With the graph active, stop transport and recording before changing graph structure. MASTER STRIP value changes can be auditioned during playback but are refused during final recording.

The exact placement and safety rules live in How SHR-DAW works, Audio graph and DSP contract, and Fixed stereo MASTER STRIP.

Recording and meters#

Recorder writes armed exact JACK sources as synchronized mono 24-bit WAV stems with one timeline and manifest. LEVELS opens the fixed 18-channel overview. A missing assigned source blocks take start until it is reassigned or disarmed. Interrupted recognized takes remain available for bounded recovery.

Performance owns the optional final bus and one 24-bit stereo recording of the same post-strip samples sent to playback. Input software monitoring starts off and uses one MON ON or MON OFF action. Enable it only after checking for direct hardware monitoring, or the input may be heard twice.

All horizontal meters use circular ● LEDs. Green is the safe range; yellow and red appear only at their active thresholds. A brighter circle holds the peak.

Read Synchronized multitrack recording and Final stereo performance bus before relying on a recording or monitoring setup.

Command line#

Common inspection and setup commands are:

shr menu
shr list
shr status
shr doctor
shr start "synthv1:Velvet Tines"
shr stop
shr log 80
shr ideas list
shr pads auto [PORT_MATCH]
shr pads learn [PORT_MATCH]
shr config paths
shr config init [--force]

shr config init preserves existing files unless --force is given. shr casio diagnostic is a legacy-named, non-transmitting route report. Command-line Idea playback restores the Idea's instrument and stops on Ctrl+C.

The complete command inventory is in shr --help. Maintenance stress commands belong to Maintainer helper scripts. effects-checkpoint is different: it starts a prepared JACK graph and synth, sends a low-gain note, and measures a bounded run. Run it only with explicit authorization. Its setup contract is in Configuration and routing.

Back to detailed guides

The installed SHR-DAW package is one music workstation with a complete sound system: five melodic instrument families, the SHR Drums instrument and kits, one controller workflow, one tracker, one effects graph, and one final audio bus. Moj Sint, SHR Sampler, and SHR Drums arrive and work together as parts of SHR-DAW. Their names identify kinds of sound available inside the workstation.

This guide is the musician-facing home for choosing, loading, playing, saving, routing, and recovering SHR-DAW sounds. Machine paths and component version checks remain in Configuration and routing; process and audio ownership remain in How SHR-DAW works.

The SHR-DAW sound system#

Instrument family	Sounds inside SHR-DAW	Musical role	Editing and saving
synthv1	.synthv1 sounds	Melodic synth	Twelve mapped controls; private Overwrite or Save New
Yoshimi	.xiz sounds and banks	Melodic synth	Read-only catalog and playback
FluidSynth	.sf2 / .sf3 SoundFonts	Multitimbral melodic or General MIDI drums	Bank/program selection; SoundFonts remain read-only
Moj Sint	.mojsint Model D, Six-Op PM, Strange Oscillator, Swarm Machine, Bass Matrix, and Dual Filter sounds	Melodic synth	Model-specific controls; Dual Filter uses 15 controls plus a reversible core click; private Overwrite or Save New
SHR Sampler	.shrinst instruments	Melodic sample instrument	Strict preloaded instruments; read-only in SHR
SHR Drums	.shrkit kits	Four-lane drum instrument	Project kit, tuning, drum rack, and tracker notes

All six families participate in the same Project, routes, effects, transport, recording, controller, and final-bus workflows. At the implementation boundary, only one SHR-managed melodic host process runs at a time. Loading a new synthv1, Yoshimi, FluidSynth, Moj Sint, or SHR Sampler sound safely replaces or reuses that owner. FluidSynth may hold several compatible channel parts inside its one process. SHR Drums renders in process and can play beside the selected melodic instrument. This arrangement keeps drum audio independent inside the same installation and workflow.

Browse, load, and switch safely#

Open Software Synths from Home. Turn to browse sounds in the selected catalog. Shift-turn the main encoder, use [/], or click the two halves of the Presets heading to move through all five melodic instrument families. Browsing is silent. LOAD is the deliberate start or replacement boundary.

Loading follows one ownership transaction:

1. validate the selected sound and its engine before disturbing the current one;
2. send All Notes Off and stop only the melodic process SHR owns when a replacement is required;
3. start or reuse the selected backend;
4. resolve its exact MIDI input and stereo JACK outputs; and
5. publish the new sound only after the route is ready.

A failed replacement leaves no second managed engine layered. When possible, SHR makes one bounded attempt to restore the previous owned session and shows the fault. PANIC, shutdown, or another explicit replacement releases notes and stops only owned work; it never terminates a matching process opened by the musician.

Presets and Playback share the loaded sound. Leaving either screen does not stop it. A new, empty, unsaved FT2 Project can adopt that exact Player sound on its first software page without restarting the host. A saved or already edited Project keeps its stored routes.

Moj Sint sounds#

Moj Sint is SHR-DAW's editable in-house synthesis family. The current installer pins a 16-start catalog with these five models:

• Model D: Full Bass, Full Lead, Full Filter Articulation, Matched Idealized, Matched Linear Mixer, Matched Linear Ladder, and Matched No Drift or Feedback;
• Six-Op PM: Bell Metal, Fractured Metal, Electric Piano Mallet, Glass Wood, Brass Bass, and Mechanical Stab;
• Strange Oscillator: one unified sound whose TYPE control selects triangle, saw, pulse, modulated resonator, deformed loop, stochastic breakpoints, scanned string, or register machine;
• Swarm Machine: the typed modular graph's warm, wide nine-oscillator pad;
• Bass Matrix: one transformable start with a phase-locked sub/body and a separate punch, growl, metal, drive, filter, and unstable character path.

The current SHR-DAW source also supports Moj Sint preset schema 8, the Dual Filter model, and its five cleared starts: Industrial Lead, Serial Bass, Counter Growl, Envelope Punch, and Topology Motion. Those starts require a newer Moj Sint checkout than the exact commit in install/compatibility.json; they are not part of the current public installer payload.

Presets groups the available catalog in the fixed model order Model D, Six-Op PM, Strange Oscillator, Swarm Machine, Bass Matrix, then Dual Filter when the configured Moj Sint provides it. Visible identities use one model letter and a two-digit number local to that model: D01, P01, O01, S01, B01, and F01. Opening or switching to Moj Sint starts at D01 Full Bass; letter-jump follows those visible model letters. In FT2 ROUTE, choosing Moj Sint adds an explicit ENGINE → MODEL → PATCH hierarchy. Changing the model selects that model's first available patch, and patch browsing never crosses the selected model boundary. Apply keeps the complete live-auditioned route; Cancel restores its opening snapshot.

Playback and FT2 PARAM use the same 3×5 control surface. The five models in the pinned installer catalog use the first 12 positions for synthesis and the last three for Project aux sends. Their synthesis labels are:

Positions	Model D	Six-Op PM	Strange Oscillator	Swarm Machine	Bass Matrix
1–4	Evolve, Shape, Color, Edge	Index, Ratio, Feedback, Op Decay	Type, Form, Warp, Couple	Mass, Detune, Spread, Shape	Body, Growl, Metal, Punch
5	Volume	Volume	Volume	Volume	Volume
6–8	Motion, Depth, Space	Key Scale, Velocity, Motion	Chaos, Color, Space	Motion, Color, Space	Drive, Filter, Unstable
9–12	Attack, Decay, Sustain, Release	Attack, Decay, Sustain, Release	Attack, Decay, Sustain, Release	Attack, Decay, Sustain, Release	Attack, Decay, Sustain, Release

Dual Filter uses all 15 positions for synthesis when a compatible schema 8 Moj Sint is configured, so it has no aux controls on this surface.

Moj timbre and ADSR retain their established CCs. Physical position 5 uses MIDI CC7 as the shared instrument-volume contract. Position 5 is a mapped direction-only rotary. Its smoothed gain runs from silence to the preset's normal maximum and does not enter timbre DSP. synthv1 uses its smoothed DCA volume at the same position; Yoshimi, FluidSynth, and SHR Sampler receive standard channel volume. Those read-only optional backends do not gain an SHR preset-save format: FT2 automation and Project MIDI state own their durable volume. After Load, Reset, Project/Idea restore, automation ownership changes, or another value-setting transition, physical turns continue from the effective value by signed relative steps, preventing jumps after a load or reset.

RESET restores the loaded model values without restarting the synth. Dual Filter also restores its saved INDUSTRIAL or COUNTER core. SAVE offers Overwrite, Save New, and Cancel. Factory/system sounds are read-only, so Overwrite redirects to the next private User NNN sound. All six Moj models keep separate private namespaces. A successful save becomes the current sound and Reset baseline without releasing held notes; a failure keeps the live sound and any previous file intact. A Moj Sint Idea carries its private preset snapshot, while an FT2 route stores the model-qualified stable sound identity.

SHR Sampler instruments#

SHR Sampler is the sample-instrument family inside SHR-DAW. It plays strict .shrinst packages, and the installation includes one cleared, project-authored neutral factory instrument. Packages are read-only catalog entries. SHR treats each package as a complete instrument.

LOAD first checks the installed host version and runs the package's bounded offline validation. Only a compatible, valid package may replace the current melodic owner. The live host must then publish its exact configured MIDI input and stereo JACK outputs. A missing executable or package, incompatible version, malformed manifest, validation timeout, missing ports, startup failure, or unexpected exit becomes a visible fault. The previous owned session is not discarded until validation succeeds, and failed activation cannot leave a second melodic process running.

Playback provides notes, held-note/velocity feedback, N00B filtering, take capture, effects access, and transport without inventing unsupported Sampler macros. Sound saving is visibly unavailable. FT2 stores the package's stable identity in its software route. Ideas store that identity and configured public path; they do not copy sample content into the private Idea directory.

SHR Drums kits#

SHR Drums is SHR-DAW's kit-based drum instrument. Its bounded engine runs inside SHR-DAW, with its own voices alongside the current melodic instrument. A new Project's four-lane Drums page uses the installed Big Rock kit when available; an explicit external or FluidSynth General MIDI drum route remains possible.

The public installation contains four cleared kits:

• Acid, an original fully modelled CC0 kit;
• Electronic House, original modelled voices plus two deterministic CC0 Moj Sint one-shot exports;
• Big Rock, a curated CC BY 4.0 acoustic kit; and
• Experimental Noise, a curated CC BY 4.0 experimental kit.

Open FT2 ROUTE on a Drums page and choose TARGET → SHR Drums → KIT. Kit changes are live-auditioned inside the same Apply/Cancel transaction as other routes. A successful change resets tuning that belonged to the previous kit while keeping the Project key and drum effects. A failed load restores the previous kit and keeps the route editor open with the error visible.

The Project stores the selected kit, OFF, FOLLOW KEY, or MANUAL per-piece tuning, and the fixed Reverb-then-Delay drum rack. Follow Key uses the Project tonic. The Drum page's four columns remain independent tracker lanes, and loading a reusable drum pattern copies note cells without replacing the saved kit or route. Immediate chokes and note cleanup apply when a drum target or kit changes.

With the owned audio graph active, SHR Drums has its own final-bus source level, mute, meter, and DRUMS effect target before the master rack and fixed master strip. Without that graph, its owned stereo output follows the direct JACK playback path. The metronome remains a separate final-bus sound and never borrows a drum voice.

Projects, Ideas, and automation#

Context	Moj Sint	SHR Sampler	SHR Drums
Player	Load, edit, reset, save	Load and play read-only package	FT2 Drums page
Idea	MIDI plus private preset snapshot	MIDI plus stable package reference	Tracker workflow, not an Idea sound
FT2 route	Stable model and patch	Stable package identity	Stable kit or explicit MIDI/FluidSynth drum target
Automation	Seven timbre controls, shared volume, and ADSR	Standard channel volume plus note performance	Notes use drum lanes; Project drum effects use stable effect automation
Project audio	Managed stereo source	Managed stereo source	Independent in-process stereo source

Project loading refuses unknown newer schemas rather than rewriting them. Missing sounds and kits remain named and visibly unavailable; SHR never swaps in a similarly named backend or route. Starting, stopping, route loss, live switching, and reload retain the same note-cleanup and ownership boundaries. External USB MIDI sync changes only the steady transport owner: incoming Start/Stop still enter these same managed-instrument, drum, held-note, Loop, and cleanup paths, and no instrument route receives forwarded clock. See Priority 7 external transport sync acceptance.

Where files and provenance live#

Private user sounds, Projects, Ideas, and runtime state stay below the normal XDG data roots or ignored $SHSYNTH_USER_DIR/. Public factory material is restricted to the repository allowlists. SHR-DAW installs and operates the system as one workstation, while its component source and sound formats remain public:

• Moj Sint source and preset format;
• SHR Sampler source and instrument format;
• SHR Drums source, kit format, and provenance.

Exact installed versions and commands are in Installation, machine settings are in Configuration and routing, and redistribution evidence is in Third-party software and sounds.

For step-by-step screens, continue with the screen and menu manual. For Pattern pages, route fields, recording, and Arrangement behavior, use the tracker guide.

Back to detailed guides

This is the visual guide to SHR-DAW's current 40×13 workspaces, contextual screens, editors, and master overlays. The current controller map is authoritative in Controller interface. Screenshots are drawn by the real Rust UI from deterministic, populated presentation states; they do not start JACK, open a MIDI port, or claim to show a live audio measurement.

The manual is split into three chapters so it remains usable on a phone:

1. Everyday screens — Home, Presets, Playback, Ideas, MIDI Learn, Help, synchronized multitrack recording and its 18-channel Levels overview, the performance meter, and Routing.
2. FT2, Projects, and Patterns — the tracker in Play, Record, Edit, and Cell Edit; Tools; the N00B scale-filter switch across Play/Record/Edit; separate Edit note length; Projects; Pattern tools; drum patterns; Arrangement; Live Patterns; the Tracks screen; and routing fields.
3. Loops and effects — Pattern-owned four-slot Loop Mix, the shared loop browser, alignment, the effects rack and its contexts, the fixed MASTER STRIP, and the parameter editor.

How to read a screen#

Each screenshot is a 40-column by 13-row terminal image. It uses the same 12×24 Uni2-TerminusBold24x12 PSF2 glyphs as tty1, producing a native 480×312 content bitmap, then enlarges it to 960×624 by copying every pixel into an exact 2×2 square. There is no font substitution, stretching, smoothing, interpolation, or antialiasing.

The normal bottom controller strip has four page positions and four action positions:

• On an eight-button controller, the first four buttons choose the page and the second four run the shown actions.
• On a five-button controller, one button cycles pages and four run actions.
• On a four-button controller, press the main encoder to enter page selection, turn it to choose a page, press it again, then use the four buttons.
• Empty pages and actions are hidden and skipped.
• Every genuine rotary/Up/Down browsing list wraps at both ends. Functional entries such as Blank/Skip, AUTO, Off, Clear, and + INSERT EFFECT remain selectable exactly once; only decorative blank lines are skipped.
• Page 1 holds the screen's primary workflow; on FT2 it is PLAY, while SELECT holds the page/pattern/song/route overlays. On workspaces, child screens, and editors, SYS item 4 is EXIT, which goes back one level. MIDI controls never quit SHR-DAW.
• PANIC stops owned playback and sends All Notes Off. It does not kill an unrelated synth or JACK client.

Home has no shared status row. Its own last line appears only for active owned playback/recording, a current fault, or a controller-setup reason; routine result messages remain hidden. The native fullscreen EQ owns all thirteen rows. The native 18-channel Levels overview is the third layout exception: it omits the controller strip so all meters fit, but keeps the unchanged shared status renderer on row 13. Its visible command pages occupy only the right half.

A master overlay temporarily changes that strip. The caller remains visible around a centered double border, whose bottom edge shows only the highlighted action that opened the overlay near its original physical item position. The final row remains the shared status row. That same menu item closes it; there is no fourth-button Back item. The rotary and Up/Down browse, click/Enter selects or confirms, and Back/Esc cancels the current field before cancelling and closing the overlay. Unconfirmed drafts never save on close. FT2 ROUTE is the deliberate live-audition exception: valid active-field choices change the Project and live route at once, Apply keeps them, and Cancel restores the opening route snapshot. On the native 40×13 display the outer rectangle is 38×11 at (1,1) and the usable inner area is 36×9 at (2,2).

The yellow page name at the bottom is the page currently selected. The yellow bracketed numbers below the actions are the physical item positions. The shared status row is always the final row on working screens.

That row begins with exactly one transport cell: steady green > for play, steady white ■ for stop, steady white ‖ for pause, or red ● for record. Record alone pulses between red and bright red without hiding the circle. Any text after one space is current useful state or a fault, not filler. Horizontal meters use only circular ● LEDs: dark gray when unlit, one consistent green for safe active cells, yellow/red only at active thresholds, and a brighter circle in the same threshold colour for a held peak.

Screen flow#

flowchart TD
    H0[Home] --> P[Software Synths / Presets]
    H0 --> T[FT2 Pattern]
    H0 --> A[Recorder]
    A --> LV[18-channel Levels]
    H0 --> M[Performance]
    H0 --> ML[MIDI Learn]
    H0 --> RTE[Routing editor]
    H0 --> FX[Effects / FX rack]
    H0 --> I[Ideas]
    H0 --> H[Help]
    P -->|Load| PB[Playback]
    M --> MO[MTR FX overlay]
    MO --> FX
    FX --> FE[FX editor]
    T --> ON[PAGE / PATTERN / SONG / ROUTE overlays]
    T --> N[N00B filter on/off]
    T --> R[Record context]
    T --> E[Edit]
    E --> CE[Cell Edit]
    ON --> TR[Tracks and routing]
    ON --> F[Project Files / Pattern tools]
    ON --> AR[Arrangement]
    ON --> TT[FT2 Tools]
    TT --> LP[Live Patterns]
    TT --> L[Loop Mix]
    TT --> HS[Pattern History]
    HS --> FEEL[Pattern Feel]
    HS --> GROOVE[Deterministic Groove]
    F --> PT[Pattern tools]
    PT --> D[Drum patterns]
    PT --> PS[Pattern setup]
    L --> LA[Loop align]
    L -. LIBRARY overlay .-> LL[Inbox + private loop browser]
    H -. returns to its caller .-> H0

The Help screen returns to whichever screen opened it. EXIT follows the arrows in reverse by one level. Top-level workspaces return Home; nested tools return to their parent first.

Pattern History is the fourth FT2 Tools PAGE action. Its History page is UNDO/REDO/SNAP/RECALL and its SYS page remains Panic/Help/blank/Exit. Empty Undo, Redo, and Recall controls are dim and cannot dispatch. Snapshot captures one Pattern without dirtying; Recall is undoable. Restore is immediate only while FT2 transport is stopped. During Play the requested stack position is kept and the status row asks for Stop; REC Undo finishes the current take and held-note cleanup first. Ctrl+Z, Ctrl+Y, and Ctrl+Shift+Z use the same restore actions as controller and mouse.

Pattern History's RHYTHM page opens FEEL and GROOVE. FEEL owns a draft EIGHTH/SIXTEENTH division and 50–75% amount. GROOVE owns a deterministic preset, cell/lane/page/Pattern scope, and strength. Apply is one Pattern history step; Cancel and no-op Apply are non-writing. Back returns to History page 2. CELL EDIT exposes independent TIME on its ROUTE page, and REC exposes the runtime-only REC FEEL toggle on CAPTURE. The CELL EDIT rotary list now continues through CHANCE, CONDITION, COND A, and COND B without adding an unreachable fifth controller page. Normal FT2 SOUND item 4 is FILL; CLICK moves to FT2 Tools SYS item 3. Keyboard f shares the same next-cycle-boundary Fill latch.

Naming and safety conventions#

• Project means the whole saved tracker song: Patterns, Arrangement, routes, programs, loop settings, and effects.
• Pattern means one reusable block of rows inside a Project.
• Page means four tracker lanes that share a MIDI destination. Each lane can still have its own channel, bank, and program.
• Idea means a free-time MIDI take associated with a sound; it is not an audio recording.
• Audio recording means one synchronized take containing a 24-bit mono WAV for each armed JACK source plus a versioned session manifest. A legacy stereo input remains a linked two-track configuration.
• Remove Loop detaches the selected WAV slot from the Project. It never deletes the private WAV. The current loop browser imports inbox files or attaches existing private files; it has no deletion workflow.
• With the graph active, FX edits require stopped transport and no active recording. With it disabled, FX edits change saved Project data only.

For the source-of-truth page/action matrix and controller reachability rules, see the controller interface. For computer keyboard commands and deeper musical workflows, continue with Using SHR-DAW and the tracker guide.

Back to detailed guides

Controller basics Presets and playback Effects graph 18-channel input levels Performance meters MIDI ideas FT2-style tracker Pages and hardware MIDI Live performance Loops and audio Trouble spots

Controller basics#

The main encoder moves one visible row or value at a time except on the FT2 grid, where Play/REC turns select columns and Edit turns move rows. Press it to select the highlighted row, confirm a field, or follow a help link.

Home centers every label in one equal-width bar. MIDI Learn, Routing, and Effects are separate destinations. Routing reports current controller, performance-input, MIDI-output, clock, and audio connections and edits them transactionally. Browsing is read-only; press to edit a detached field, press again to validate/save, or Back to cancel. Use shr-setup for initial machine setup.

If a configured controller is offline, has no reviewed profile, or has not learned encoder turn and click, Home highlights MIDI Learn and explains why. Keyboard Up/Down/Enter still work. Optional command buttons may be skipped once the learned encoder can turn and click, but only through explicit S or keyboard-arrow input; master-rotary traffic is ignored during Learn. The explanation uses Home's single bottom line so the native menu keeps its empty first row. Home does not learn or send MIDI by itself; Learn keeps selected-controller messages isolated until an explicit save or cancel. Its optional encoder-Shift step learns two ordinary gestures: Shift plus a left turn, release Shift, Shift plus a right turn on the same CC, then release Shift again. This captures either the ordinary rotary CC or a different CC emitted only while Shift is held. Separate performance inputs continue to bypass controller interpretation. The Shifted CC may encode left/right opposite to the ordinary rotary; Learn discovers that from the two physical gestures instead of assuming they match. Learn itself uses exactly two rows total. The first is the complete required gesture, such as SHIFT + TURN ROTARY 1 LEFT; the second is its immediate state or retry. There is no repeated MIDI LEARN title or status footer.

The controller menu has four pages. Page 1 is OPS. On child screens, page 4 item 4 is EXIT and returns one level. Empty buttons are hidden and silent.

Home and MIDI Learn are the screens without the shared working-screen status row. Learn owns only its two centered action rows. The native fullscreen EQ owns all thirteen rows. The native 18-channel Levels screen keeps the shared final row but omits the two controller rows; every other working screen places those rows immediately above status. The first status cell is steady green > for play, steady white ■ for stop, steady white ‖ for pause, or red ● for record; record alone pulses between red and bright red without hiding the circle.

Four-button controllers use encoder press to enter page-select mode. Turn to choose a menu page, then press again to return the encoder to screen control. In Help, use OPS OPEN to follow the highlighted link. In target/channel editors, use OPS CONFIRM; SYS EXIT cancels the field.

Some navigation actions open a master overlay instead of replacing the current workspace. The workspace remains visible around a 38×11 border; its usable inside is 36×9 on a 40×13 display. While the overlay is open, its bottom border shows only the highlighted launcher near the same physical position; the final row remains the shared status row. Turn the master rotary or use Up/Down, then click or press Enter. Press that same menu item again, or use Back/Esc, to close. The controller strip has no separate Back item while an overlay is open. Back first cancels an active field, then cancels any unconfirmed draft and closes the overlay.

FT2 Tools PAGE item 4 opens HISTORY. Page 1 is UNDO, REDO, SNAP, RECALL; unavailable actions are dim. Ctrl+Z is Undo, while Ctrl+Y and Ctrl+Shift+Z are Redo. SNAP is one non-dirty runtime Pattern capture and RECALL is undoable. History covers committed edits inside one existing Pattern, not Project or Arrangement structure, global mix/effects, runtime launch state, private files, or an editor draft before Apply. Restore currently requires stopped FT2 transport; Play-time attempts keep history unchanged and ask you to stop. Undo during REC finishes the take and note cleanup first.

HISTORY page 2 opens FEEL and GROOVE. FEEL sets Pattern EIGHTH/SIXTEENTH swing from straight 50% through 75%. GROOVE applies one deterministic preset to the selected cell, lane, page, or Pattern. Both remain drafts until Apply; Cancel and unchanged Apply do not enter history.

CELL EDIT TIME is independent of the one-command field. It moves a cell up to half a row early or late in 1/96-row steps; Reset returns ON GRID. The tracker grid marks early with <, late with >, and on-grid with a blank. Pattern swing and cell timing move musical events only; cursor rows, Loop timing, and MIDI clock stay steady. REC CAPTURE offers runtime-only REC FEEL; quantized REC remains the default.

CELL EDIT's rotary list continues after TIME with CHANCE, CONDITION, COND A, and COND B. Chance is deterministic 1–100%. Conditions are FIRST, LAST/N, A:B, PRE, and FILL; ALWAYS is the default. LAST/N is the final pass in an N-pass cycle, PRE follows the preceding trigger in the same lane/pass, and FILL uses the runtime latch. Normal FT2 SOUND FILL or keyboard f changes that latch at the next cycle boundary. Stop/new Play clears it. CLICK remains under FT2 Tools SYS.

Presets and playback#

Presets chooses the instrument engine and sound. Loading a sound starts or reuses only the engine owned by SHR-DAW; unrelated synth processes are left alone. Presets and Playback share that owned sound, and leaving those screens keeps it running. Global panic, shutdown, replacement, or an explicit different FT2 software route ends it safely. A genuinely new, empty, unsaved default FT2 Project adopts the current engine/instrument on page 1 without restarting it; without a Player instrument, FT2 loads the first available synthv1 preset. Saved or explicitly changed Projects keep their routes.

Turn the main rotary to browse sounds. Hold the configured encoder Shift while turning to change engine catalog in either direction; [/] and the two heading halves remain available. Catalog changes are silent. Only LOAD starts or replaces the managed preset.

Synthv1 controls add or subtract from SHR's current value immediately. The direction-only rotaries have no physical position to catch and cannot jump to a stale knob value.

Moj Sint uses the same direction-only behavior with seven model-specific timbre controls, Volume at physical position 5, and ADSR. RESET restores the loaded .mojsint values in place without restarting the host. Those controls never use synthv1 XML names or parameter indices. The current catalog has 21 numbered starts: seven Model D, six Six-Op PM, one each for Strange Oscillator, Swarm Machine, and Bass Matrix, and five Dual Filter starts. The public SHR-DAW installer currently pins the 16-start pre-Dual-Filter catalog. Player and FT2 PARAM always use a 3×5 surface. Synthv1 and the five older Moj models put their twelve synth controls first and Project AUX 1/2/3 sends last; NO FX means that aux needs an effect before the send can move. With the owned graph active, these send levels ramp live without rebuilding the graph; recording refuses the change. With it disabled they update Project data. Dual Filter uses all fifteen positions for synthesis. Moj routes remain inside their selected model in FT2 ROUTE.

SHR Sampler packages are read-only instruments. LOAD validates the host version and complete .shrinst package before replacing the current sound. A failure keeps or restores the previous owned session; SAVE stays unavailable. Ideas and FT2 routes retain the package identity without copying its samples.

SHR Drums is selected from an FT2 Drums-page route, not Presets. It runs in process beside the one managed melodic engine. KIT changes use the live Apply/Cancel route transaction and preserve the prior kit on failure.

The dots beside synthv1 values compare the current sound to the loaded preset: green is lower, yellow is near original, red is higher.

Playback names the held chord and notes, with each note's decimal MIDI Note On velocity (1–127) directly beneath it. Use the rows to practise gentle/strong strikes, even chord attacks, or bass-versus-chord balance. Velocity comes from MIDI and is not an audio volume measurement; the controller and instrument response matter. On terminals taller than the native 40×13 layout, the spare space adds a continuous two-row keyboard from C2 through G7 at 40 columns. A red white-key area means its natural note is held; a red upper └ means the following sharp is held. Major triads show maj explicitly, such as C maj. display.note_names=german uses B/H spelling; english uses A#/B.

Playback PLAY starts a saved MIDI take or, with no take, the configured external-sync controller arpeggiator. RECORD starts the same controller clock before free-time capture. STOP ends the take/arp and sends All Notes Off without unloading the sound. TAP changes the current Pattern/controller tempo but never starts transport by itself.

Playback N00B toggles the filter on the existing Player screen. While on, its compact SCALE rotary appears below the normal controls; turn the master encoder to cycle every root plus MAJOR or natural MINOR choice. Notes in the chosen scale keep their pitch and sound normally; notes outside it stay silent. Pressing N00B again restores all chromatic notes. Changing or leaving the filter releases held notes first.

Playback and FT2 PARAM SAVE offer OVERWRITE, SAVE NEW, and CANCEL for synthv1 and Moj Sint. Factory or system sounds are read-only, so Overwrite clearly redirects to a new private User NNN sound. A saved sound becomes the current RESET baseline without restarting the engine or changing its values. Use the overlay with the controller, encoder/Enter, or mouse; keyboard O, N, and C select its three actions while S remains Panic. Unsupported backends show SAVE UNAVAILABLE. A storage or format failure leaves the overlay open and preserves the current sound, controls, held notes, and existing file. Save MIDI takes from Ideas. SOUNDS returns directly to Presets, where LOAD starts the highlighted instrument.

Effects graph#

Playback SYS FX or FT2 Tools OPS FX opens the current Project's FX rack. In FT2, uppercase F opens it directly. Back returns to the calling Player or FT2 screen while its instrument remains active. TARGET cycles SOURCE, AUX 1, AUX 2, AUX 3, DRUMS, and MASTER. Shift-rotary selects that target in either direction while the ordinary rotary browses rack rows. Source effects change the instrument in series. Each aux makes a parallel wet copy: SEND sets how much enters it, POINT chooses before or after source effects, and RETURN sets how much comes back. Master effects change the final dry-plus-aux mix.

ADD inserts a provisional processor and opens TYPE. EDIT changes the selected processor's type; PARAM opens its named values; DEL removes it. ORDER moves the same stable instance and BYPASS fades a source or master effect toward dry. A fully bypassed aux returns silence, so it never doubles the dry source; a delay tail can be allowed to fade with new input muted. Aux effects are forced wet.

The editor selects named parameters and adjusts values in physical units. At 40×13 an EQ fills all thirteen rows: four one-cell markers move on a 50 Hz–20 kHz logarithmic axis, the side panel exposes bypass, every band, low cut, and output trim, and gains edit in 0.5 dB steps. Turn/click browses and edits; Back restores an active edit. Knobs 1–4 are logarithmic band frequencies and knobs 5–8 are their gains. One compact meter row appears for other effects when the owned graph has data. The compressor uses a dark-red 0.5–24 dB LED row whose bright-red lights show live gain reduction; bypass leaves every LED dim. Other effects show compact input/output values. Rack size and total effect count are bounded. With the graph active, stop transport and all recording before an FX change can publish a replacement plan. With the graph disabled, the same editor can design and save the Project silently, but direct playback will not process or meter it.

On the MASTER rack, ORDER STRIP opens the fixed mastering processor; MTR NAV STRIP reaches the same Project state. Its front page selects INPUT, broad TONE, linked full-band GLUE, declared harmonic COLOR, conservative M/S IMAGE, or LOUD/CEIL. DETAIL exposes only that section's values. Optional sections have smoothed BYPASS. A/B keeps the same delay and protected true-peak limiter. RESET I clears LUFS-I. Playback allows smoothed value changes, but a final recording rejects them; with no owned graph they change only the Project. In DETAIL, the ordinary rotary browses parameters and Shift-rotary changes section through the existing front-page order.

Performance meters#

Home PERFORMANCE, or keyboard m, opens the meter/mix surface. With the owned graph inactive it retains the passive CPU and legacy output view. With the graph active it shows Synth, Loop, Input, and Drums readiness and level; Synth, Loop, and Drums use MUTE while Input uses one MON ON/MON OFF action; Input stereo/dual-mono mode and the two independent dual-mono pans; master level; final sample peak and dBTP; GLUE/limiter gain reduction, correlation, LUFS-M/S/I; and final-record elapsed time, size, drop/error state, and path.

Stereo bars use circular ● LEDs for live smoothed RMS and a brighter, decaying held peak on a −60 to 0 dBFS scale. Unlit circles are dark gray; safe active circles use one green, while yellow and red appear only at their active thresholds. Each channel's MAX number separately holds its highest peak without decay. CLIP is held in red. RESET clears MAX, the bright peaks, and CLIP. Any downward movement of the mapped synthv1 Volume control clears both MAX values; increases, equal values, and other controls leave them alone. Stopped, unavailable, and new meter sessions cannot carry an old MAX forward.

FINAL OUT is available only for the active owned graph. It measures after all present optional sources and the deliberately monitored Input, master inserts, live master level, fixed strip, and linked 8× true-peak limiter. The same final buffer feeds the stereo recorder and playback. Direct playback reports this final-bus meter unavailable and stays direct.

The FT2 WAV Loop screen's LOOP OUT still measures only the rendered loop. When the final bus is active, that loop is one of the four sources in FINAL OUT.

On MTR, SOURCE-/SOURCE+ choose a source and LEVEL-/LEVEL+ change it in 1 dB steps. The same source-control position shows MUTE for Synth/Loop/Drums, MON ON for an unmonitored Input, or MON OFF for a monitored Input. Keyboard m, its controller item, and the visible pointer target invoke that same action. MON ON activates the input-only final bus when needed; it never starts an optional source. REC starts/stops the final stereo WAV at callback boundaries. RESET clears presentation holds and, when the bus is unavailable, retries the same exact remembered source mapping. Source and master changes are smoothed; there are no solo, aux, or per-input effect controls.

With Input selected, MTR NAV DUAL/STEREO changes the input interpretation. IN CTRL cycles LEVEL, PAN 1, and PAN 2; on either pan, the ordinary LEVEL-/LEVEL+ positions become PAN1-/PAN1+ or PAN2-/PAN2+. Dual mono starts at 1L100 2R100, matching the original stereo image, then pans each configured capture port independently with an equal-power law. Mode and focus use the visible MTR controller actions; they add no dedicated computer-keyboard shortcuts. These are live session controls, not Project data, and a fresh launch starts in stereo.

18-channel input levels#

Audio Recorder LEVELS opens Levels. At native 40×13 all 18 inputs stay visible as three groups of six; selection never scrolls or banks them. Each nine-LED column is smoothed RMS at −48, −36, −30, −24, −18, −12, −6, −3, and −1 dBFS. Green covers −48 through −18, yellow −12 through −3, and red −1. A brighter LED in the same colour is the held sample peak.

Turn the encoder or use Left/Right or j/k to select a channel. Click/Enter or Space toggles its arm. PageUp/PageDown shows TAKE, CHANNEL, and SYS commands in the right half; r records, s stops, x resets holds, u returns to setup, and uppercase S panics. The shared final row remains the only status row. M, F, and held C distinguish missing, faulted, and clipped channels from ordinary silence. This is a recording overview, not the MTR final-bus mixer, Audio Recorder setup, route detail, audible monitor, or mixer strip.

MIDI ideas#

Ideas record musical MIDI while a sound is loaded. Repeated RECORD stops the capture; PLAY plays it back through the loaded engine; SAVE stores it for later.

Recording timestamps come from the MIDI callback, and PLAY playback runs independently of screen redraws. Stopping a take cancels it promptly and sends all-notes-off cleanup.

Loading an idea can replace the current sound. If a sound is already active, choose LOAD twice to confirm. Saved synthv1 control values are restored after the sound loads, and relative turns continue from those restored values.

Ideas are MIDI, not audio. Use the audio recorder when you need a WAV of the actual JACK input.

FT2-style tracker#

SHR-DAW uses FT2-style Pattern screens for MIDI sequencing; it is not a sample-based FastTracker II implementation. PLAY starts at the current Pattern/Arrangement location, REWIND returns to the beginning, and STOP stops only the tracker transport. Turn the physical main encoder to move rows. Hold the configured encoder Shift while turning to select columns across page boundaries. The shaded selected column does not move the row, playhead, Arrangement Step, or transport. During REC, Shift-turns made while recorded notes are held are ignored until all of those notes receive Note Off.

FT2 SELECT contains PAGE, PATTERN, SONG, and ROUTE. PAGE lists only the current Pattern's pages, preserves the selected column, and can open the full Tracks manager. PATTERN selects an existing Pattern or opens Pattern/Project tools. SONG selects an Arrangement step and can open detailed Arrangement or Loop/ page tools. ROUTE shows the active page destination and all four columns' channel, bank, program, profile name, and availability. Turning an active field validates and applies the choice to the Project and live route. APPLY ROUTING keeps the result. CANCEL or Back from the main list restores the route from when ROUTE opened; Back during field editing restores that field first.

Normal FT2 page 3 is SOUND, with PARAM and MIX. PARAM opens a tracker-owned view of the current software instrument without entering Player or replacing the tracker engine. It uses the same 3×5 labels, values, relative-to-preset colours, held-note display, and rotary carry behavior as Playback. Synthv1 and the five older Moj models use 12 synthesis positions and three aux sends; Dual Filter uses all 15 for synthesis. Instrument choice stays in ROUTE; there is no second sound browser.

PARAM SOUND provides RESET, SAVE, N00B, and one empty position. RESET restores the existing baseline in place without restarting the engine or releasing notes. SAVE uses the normal preset-save overlay; successful save becomes the new RESET baseline and changes only the matching active FT2 route. PARAM SYS provides PANIC, an empty position, HELP, and EXIT. Unsupported backends visibly have no editable or saveable parameters. Back/Esc or EXIT returns to the exact Pattern/order/page/lane/column/row, FT2 mode, transport, route, N00B state, live values, and launching SOUND page.

MIX opens the live audio-level mixer in Play, REC, or Edit; Shift-clicking the main encoder is the direct shortcut in every mode. It controls canonical final- bus Synth, Drums, Loop, or configured Input owner gain, never MIDI velocity or CC volume. Linked pages share gain/VU after either rotary moves. With fewer than twelve configured active rotaries, turn the main encoder to choose the active page bank. External MIDI without a configured stereo SHR return says NO RETURN; Input monitoring remains an explicit safety choice. Back, click, or SYS EXIT restores the exact tracker location and mode. Play/REC follow the sounding Pattern; Edit follows the Pattern being edited.

With controller clock enabled, SHR sends the current/default tempo at 24 PPQN to one exact controller MIDI port while the app is open; tracker transport adds Start/Stop. An empty Pattern may run for a live external-sync arpeggiator; tracker pages never send notes or programs back through the clock-only route.

EDIT turns incoming notes into pattern data. Encoder press inserts a blank row. Edit ADD opens a rotary overlay choosing any advance from 0 through 32 rows; 0 keeps the cursor on the current row. The FT2 heading shows the active value. N-OFF writes a note-off.

TRACKS SYS ENTRY persists one entry layout per page. Manual starts at the selected column and spreads chords across later columns. One column redirects notes to its C1–C4 monophonic anchor without moving the cursor. Drum auto places each simultaneous group atomically across four safe lanes without overwriting cells. Active unrelated cymbal tails reserve their lanes; matching retrigger/choke groups may reuse them. Unknown drum notes are short percussion, and a full four-lane group is refused unchanged as DRUM LANES FULL.

CELL edit is transactional. DONE SAVE commits the draft cell; EXIT cancels and restores the original value. PANIC remains available without introducing a second partial-commit path.

FT2 N00B toggles the Player-selected scale directly over Play, Record, and Step Edit on the selected melodic page; it does not open another screen or change the current mode. Out-of-scale keys stay silent and are never moved to another pitch. Play can use it without writing; Record and Edit write only the allowed notes. It turns off automatically on Drums, where the current mode remains active.

Edit LENGTH opens a rotary overlay choosing 1/1, 1/2, 1/4, 1/8, 1/16, 1/32, 1/64, or 1/128 for melodic notes. The independent 0–32-row ADD overlay controls where the next entry goes.

Pages and hardware MIDI#

Each tracker page has four lanes and one destination. New Patterns start with Software Synth (first synthv1 preset), MIDI (channel 1/program 1), and Drums (channel 10). Explicit columns show MIDI channel 1–16 and program 1–128. Pages can target a named synthv1 preset, configured external output, or named MIDI port. Live keyboard and musical MIDI audition whichever page is selected. Sharing a destination/channel requires the same master instrument.

Real-time REC uses the selected page's exact target. A named software-instrument page records through that one owned engine; a hardware page uses its exact MIDI output. REC refuses an offline, missing, or ambiguous target instead of silently substituting another instrument.

Exact saved targets keep their data and show OFFLINE or AMBIG when they cannot resolve; they never substitute another output or the Pattern's software synth. Portable AUTO pages resolve the current machine default instead. Reconnect an exact target and play again without rewriting the Project.

The quick FT2 ROUTE overlay keeps APPLY and CANCEL visible in its bottom border. Every encoder change updates the live Project route immediately, so the selected instrument or SHR Drums kit can be heard without leaving ROUTE. APPLY keeps the live result; CANCEL restores the complete route from when the overlay opened. Back during a field edit restores that field first, while Back from the main list restores the whole route. Keyboard A and C match the visible actions.

FILES NEW PRJ requires a second press, clears the current unsaved Project, and starts the next project-001 style name. SAVE AS writes and switches to the next non-overwriting <name>-copy-001 file. Pattern Repeat/Remove operations remain on the Arrange screen. FILES NAME accepts a display name and safely publishes a rename; its custom text requires the computer keyboard. LOAD and computer-keyboard quit protect dirty Project data with Save/Discard/Cancel. Cancel or a failed/pending Save retains the exact tracker position. FILES PATTERN groups pattern create/clone/clear, clipboard, and melody-only semitone/octave transpose actions. PATTERN DRUMS loads bundled grooves into the percussion page without changing its MIDI route. FILTER picks genre, meter, and 32/64/128-row length (24/48/96 in 3/4). Empty Patterns resize; existing melody is protected. Saved drum patterns are separate .shdrum files; only user saves can be deleted. The ordinary rotary browses the filtered list; Shift-rotary changes genre through the same wrapping action as GENRE-/GENRE+. FILES CLEAN deletes only a zero-reference Pattern and never edits Arrangement steps.

Live performance#

FT2 TOOLS LIVE opens Live Patterns. Browse without launching. LAUNCH queues the selected Pattern for the chosen Pattern or bar boundary; NOW is immediate, RETRIG repeats the current Pattern, and CANCEL removes the queue. CAPTURE keeps only successful boundary activations, then APPEND or REPLACE explicitly confirms an Arrangement change.

SHAPE controls transient mute, velocity, gate, and transpose for the selected page's four MIDI lanes. The values survive navigation but reset on Project load/new. Keyboard: l/L launch/now, c cancel, r retrigger, q quantization, and m/v/g/t lane shaping. Shift-rotary selects the lane through the same previous/next path as Left/Right.

Loops and audio#

Loop Mix has four slots owned by the FT2 cursor's Pattern. Browsing changes the editor, not the sounding Pattern. SLOT-/SLOT+ changes selection without launch. Shift-rotary uses that same slot action while the ordinary rotary keeps browsing WAV choices. LAUNCH and STOP queue the selected slot for the next Pattern-local bar; a new command replaces the queue and CANCEL removes it. MIX controls smoothed level and mute. FILTER turns left for low-pass, right for high-pass, with neutral at centre. Keyboard: p/P launch/stop, c cancel, m mute, ,/. filter, and 0 neutral.

Every active WAV must match its Pattern's interpreted tempo and JACK's sample rate. Playback stays native speed/pitch; there is no time-stretching. Pattern changes switch MIDI and loops together and restart local phase. A failed slot is isolated while healthy loops and MIDI continue.

LIBRARY opens an overlay for the selected slot. Browsing is silent. Controller PLAY explicitly previews the WAV; repeated PLAY, selection change, STOP, Back, browser close, or leaving the browser stops preview. Press the rotary/Enter to import or attach. INBOX imports; PRIVATE, CURRENT, and SAVED attach the existing file. Failure keeps selection and FT2 context. The browser does not delete WAVs.

LOOP OUT is the summed four-slot source after each slot's cut, phase, filter, level, transport gate, and edge fades. It does not include the loaded synth, effects, recorder input, hardware gain, or other JACK clients.

The audio recorder arms independently named JACK inputs and writes one 24-bit mono WAV per input in a synchronized take directory. Select a track, assign an exact discovered source, name it, then arm it; a missing remembered source stays missing and blocks recording instead of being replaced. ARM ALL includes only resolved tracks, and NONE disarms all. Every armed stem starts and stops on the same JACK callback boundary.

Each take has a session.json manifest recording the sample rate, shared frame count, source identities, grouping, errors, and finalization state. Recognized interrupted take directories recover conservatively on the next start. Existing two-port capture.input configuration still appears as a linked stereo pair.

Trouble spots#

If nothing sounds, check JACK first, then the page or preset target. Setup does not start or restart JACK for you.

If controls do not move a synthv1 parameter, verify that every mapped rotary is configured for Relative 1 or Relative 2 and run MIDI Learn again. Each performance rotary must prove a slow left turn and then a slow right turn on the same CC. A POSITIONAL or DIRECTION message means that role was not saved; change the hardware mode if necessary, then press R to retry.

PANIC sends all-notes-off, stops owned playback/recording, and shuts down the managed engine. It does not kill synth processes SHR-DAW did not start.

Pad lock lets command pads play as musical notes. Turn pad lock off when menu buttons appear to do nothing.

Back to detailed guides

The FT2 screen is a vertical MIDI pattern sequencer. Its quick, top-to-bottom editing style is inspired by FastTracker II, but SHR-DAW is not an FT2 clone. It does not use FT2 code or read XM files.

This guide owns FT2 behavior and Project editing. Use the screen and menu manual for button-by-button screenshots and Configuration and routing for stored fields and machine defaults.

On the native 40×13 display, the FT2 body and its own compact page/lane footer end above the two controller rows. Row 13 is the shared working-screen status row: steady green > for play, steady white ■ for stop, steady white ‖ for pause, or a ● that pulses only between red and bright red for record. The tracker header does not repeat PLY or REC state beside the Project title.

Modes#

The normal FT2 screen has PLAY, real-time REC, and detailed EDIT modes. N00B is a separate on/off filter that can remain enabled in all three. It keeps the selected melodic page as the instrument and filters input through the Project-wide song key: a chromatic tonic plus major or natural-minor scale. The key remains saved and available to SHR Drums when N00B is off. An in-scale key keeps its original pitch; an out-of-scale key is consumed and stays silent. N00B never quantizes a rejected key to a different note. Each entry to the main FT2 screen opens controller-menu page 1, PLAY, where the PLAY and RECORD buttons are immediately available. PLAY, REC, and EDIT are mutually exclusive. Selecting one ends the other active mode first; pressing the active PLAY, REC, or EDIT control stops or leaves it.

In Play, N00B changes only what is heard. In REC and EDIT, allowed notes can be written normally while rejected notes remain silent and unwritten. Turning the filter on or off never changes Play/REC/EDIT. N00B is refused on a percussion page; moving onto Drums turns only the filter off and preserves the current mode.

The N00B button stays in the same FT2 SYS position in Play, REC, and EDIT. Each press toggles the Player-selected scale directly without opening another screen or changing existing cells. Command pads and their releases remain consumed.

The same Project key also drives the read-only HARMONY browser. Open the SONG overlay's tools row, select FT2 Tools PAGE, then choose HARMONY. It shows the two circle-of-fifths neighbours, relative and parallel keys, and all seven diatonic triads for the current major or natural-minor mode. The browser uses the configured English or German note names and the same sharp-based enharmonic spelling as SHR's existing note and chord display. It never changes the key, creates notes, starts playback, or dirties the Project. HARMONY, EXIT, Back/Esc, encoder press, or right-click closes it and restores the exact tools page and FT2 position.

FT2 Tools PAGE also opens HISTORY. Its first controller page is exactly UNDO, REDO, SNAP, and RECALL; unavailable actions are dim and inert. History retains at most 32 prior Pattern states within a shared cell/automation memory budget. It covers committed edits to the selected existing Pattern: cells and notes, a completed REC take, tempo/meter/length and SIZE tools, clear/transpose/drum load, lane/page/Pattern paste-over, confirmed page and route changes, automation, and Pattern-owned Loop Mix settings. Project replacement and saving, Pattern/Arrangement structure, global FX and mixing, private files, live launch/shaping, transport, held notes, and drafts still waiting for Apply or Cancel are not Pattern history.

Ctrl+Z performs Undo; Ctrl+Y and Ctrl+Shift+Z perform Redo. Undo/Redo restore the Pattern and its FT2 selection context. A successful new edit after Undo clears Redo; refused, failed, cancelled, and no-op commands do not move history. SNAP captures one runtime Pattern/context without dirtying the Project or changing transport. RECALL restores it as an undoable edit. Loading, importing, or creating another Project clears both stacks and the Snapshot; Save keeps useful history, and the existing Song-equality baseline continues to decide SAVED versus DIRTY.

The first version restores only while FT2 transport is stopped. During Play it shows STOP TRANSPORT · UNDO/REDO/RECALL kept and leaves the requested action available. Undo during REC first finishes the take, releases its held-note owners, stops safely, and then restores. Full Play-time queueing is deferred because the scheduler has no boundary transaction that can atomically replace an authoritative full Pattern, activate its routes and decoded Loop resources, restore editor context, and report success before the history stacks move.

HISTORY page 2 opens the Pattern rhythm tools. FEEL is a draft editor for straight or 50–75% EIGHTH/SIXTEENTH swing; Apply is one undoable Pattern edit and Cancel is non-writing. GROOVE previews one deterministic preset over the selected cell, lane, page, or whole Pattern, with 0–100% strength. Apply stores the resulting cell timing/velocity values as one undoable edit. The neutral preset names describe only their transformation and do not claim a cultural style.

CYCLE edits the selected lane's independent playback length, rate, and direction. Length is FULL or an explicit Pattern-row count; rates are 1/4X, 1/2X, 1X, 2X, and 4X; directions are forward, reverse, pendulum, and bounded deterministic variation. Drafting does not move the FT2 cursor. Apply requires stopped transport and creates one Pattern History entry; Cancel and unchanged Apply create none. These settings change only which cells that lane reads and when—it never changes the Pattern's Arrangement duration. Exact scheduling, ownership, migration, and acceptance semantics are in Priority 4 lane playback acceptance.

GEN opens the one offline deterministic Generator for the selected Pattern, page, lane, and cursor row. Alongside Euclidean triggers, bounded accumulator progressions, seeded pitch mutation, and percussion-only controlled FILL, it offers ROLL without another launcher or mode. ROLL uses 1–8 total pulses over the selected span: EVEN uses the existing within-row Retrigger command, while ACCENT and CRESCENDO use ordinary rows with explicit velocities. It defaults to an independent new clone; EMPTY ONLY and REPLACE NOTE are explicit current-Pattern choices. The Generator also offers three melodic tools. ARPEGGIO reads the existing notes across the cursor row as its explicit chord source and exposes order, upward octave count, 1/2/4/8-row rate, 25/50/75/100% gate, and complete repetition count. CHORD derives one triad from the Project tonic/major-or-natural-minor scale plus degree, inversion, close/open voicing, three consecutive lanes, row rate, and repetition count. HARMONIZER copies the selected lane over a bounded row span to another explicit lane as a diatonic third/fifth above/below, with REFUSE or SKIP for out-of-scale notes and exact Note Off/field preservation.

Every tool builds an inspectable draft first. The screen shows its explicit source/target and settings, affected rows and cells, replacements, collisions, protected cells, out-of-scale skips, and counted range/scope refusals. Its four pages remain Shape, Detail, Value/Repeat/Inspect, and Stop/Apply/Clone/Cancel. Apply requires stopped transport and is one Pattern History step; Clone uses the existing structural owner to append an independent Pattern and explicit Arrangement step without overwriting the source. Cancel, refusal, and unchanged Apply write nothing. Only ordinary Cells persist, so playback, Project save/load, reusable drum patterns, export, and preflight never invoke a hidden generator. Exact shared and harmonic semantics are in Priority 5 deterministic generative tools and Priority 6 arpeggio, chord, and harmonizer generators.

Routing SYNC can instead give steady transport time to one exact USB MIDI input. After seven Timing Clocks establish tempo, incoming Start begins either Arrangement step 1/row 1 or the selected Pattern/row 1 according to SYNC POS; Stop, loss, or refusal cleans through the normal FT2 transport and requires reacquisition plus a fresh Start. External time replaces only Pattern/Tempo- command steady tempo: swing, groove, timing, REC FEEL results, independent lanes, probability/conditions, retrigger, automation, Live Patterns, and Loop Mix retain their existing owners. Stopped external REC is refused rather than inventing an unsynchronised count-in. Continue, Song Position Pointer, clock thru, and external partial-position starts are not available. See Priority 7 external transport sync acceptance.

On the main tracker grid, the physical main rotary always moves rows. Holding the configured encoder Shift button while turning selects the previous or next column, continuing through page boundaries from Software Synth to MIDI, Drums, and later pages. The selected column has a subtle dark full-column shade; the yellow cell cursor and row/warning emphasis remain stronger. Keyboard arrows retain row navigation in every mode. Shift-rotary column selection does not move the row, playhead, Arrangement Step, or transport, and is ignored while a recorded note is still held.

Projects, patterns, and arrangement#

An SHR-DAW Project contains FT2 Patterns and an FT2 Arrangement. An FT2 Pattern is a self-contained tracker pattern. The FT2 Arrangement is the ordered chain of Arrangement Steps; each step references a pattern ID. Repeating a step reuses the same pattern until you explicitly clone or paste a new pattern.

Each FT2 Pattern owns its own rows, meter, hundredths-BPM master tempo, pages, page targets, per-column MIDI channels/banks/programs, velocity defaults, mutes, percussion settings, note-entry mode/anchor, drum classification overrides, lane settings, and cell data. A new Project starts with one pattern whose FT2 workspace exposes four musician-facing pages:

1. Software Synth, a four-track page using the first available synthv1 preset;
2. MIDI, a four-track page using the configured external output, MIDI channel 1, and program 1;
3. Drums, a four-track page using the installed SHR Drums starter kit when available, otherwise the discovered FluidSynth General MIDI compatibility kit, with the existing GM percussion-note mapping;
4. Loop Mix, that Pattern's four-slot decoded-WAV source.

Loop Mix is a page in the musician-facing FT2 workflow, not four empty MIDI lanes. SELECT → PAGE opens it directly, so a new Project does not require adding or naming a page before importing a WAV. The blank Pattern, unloaded loop state, loop inbox, and startup MIDI-output snapshot are initialized when SHR-DAW starts. Entering a genuinely new, empty, unsaved FT2 Project loads its page 1 software instrument immediately. If Player already owns a loaded instrument, page 1 adopts that exact instrument and the same managed engine session becomes FT2-owned without a restart. Otherwise page 1 loads the first available synthv1 preset.

Loop Mix settings are saved with their Pattern. Launch, stop, mute, queued commands, playback position, faults, and Live Pattern shaping remain runtime performance state; none of them creates MIDI lanes or Arrangement Steps.

Channels and programs are zero-based in MIDI bytes and in the in-memory model. Every musician-facing screen shows channels 1–16 and programs 1–128.

Each page keeps one MIDI target plus four independent column channel, bank, and master-program setups. It also keeps velocity, mute, percussion, optional device-profile metadata, and lane settings. A software target stores its engine and that engine's stable instrument identity in the Pattern. Moj Sint stable identities are model-qualified. When page 1 is part of a genuinely new, empty, unsaved default Project, entering FT2 may replace its factory route with the currently loaded Player engine/instrument. A loaded/saved Project or an unsaved Project with any explicit change is never retargeted, even when its Pattern has no notes. For external MIDI, columns may share a destination/channel only when their master bank and program match, because MIDI program selection is channel-wide. A software route owns its preset instead of using those external master-program fields.

Pages play together, and page count is not an instrument or polyphony limit. Any number of pages and columns may share the exact same software route/channel. Their four lanes remain independent: two shared pages provide eight simultaneous tracker lanes, and further pages extend that pool within the Project and synth voice limits. The same route may also be used on several channels.

SHR still owns one synth host at a time. synthv1, Yoshimi, Moj Sint, and SHR Sampler expose one current instrument, while one owned FluidSynth process is multitimbral: each distinct SoundFont preset/channel pair is selected once without changing other channels. For example, bass on channel 1, keys on 2, pad on 3, and a drum kit on 10 play together through the existing stereo synth output. Channel 10 is the normal percussion-page default, not a reservation; an explicit Project may route it differently. SHR Sampler packages are preloaded before its JACK/ALSA host starts; it does not auto-connect or share a process with another backend.

Drums pages can explicitly store an SHR Drums kit, a configured/exact external MIDI output, or a FluidSynth General MIDI compatibility route. An unavailable saved target remains visibly offline and silent; it never falls back to another route. SHR Drums is an in-process stereo source and does not consume the one managed melodic-synth slot, so it can play beside synthv1, Yoshimi, FluidSynth, Moj Sint, or SHR Sampler. Switching targets sends All Notes Off and immediate drum chokes. Loaded Projects keep their saved routes and channels, and loading a reusable drum pattern copies cells only.

The complete musician-facing comparison, including Moj model controls and saves, Sampler package validation, installed drum kits, ownership, and failure recovery, is in SHR-DAW instruments and drums.

Two different FluidSynth presets cannot share one channel in the current playback loop. SHR selects stable channel parts before scheduling, and note tails plus Pattern/Arrangement loop boundaries are not treated as safe dynamic preset-change points. Consequently even apparently non-overlapping uses on one channel are refused for now with a channel-conflict error. Identical route/channel sharing is safe and is never that conflict. FluidSynth plus another managed backend is also refused because that would require a second managed backend; external MIDI pages and the WAV loop remain independent.

Pressing Play on such a mixed Project opens an explicit recovery choice instead of leaving only a status-line refusal. NO keeps every route and cell unchanged. YES opens a list of matching FluidSynth sounds for each incompatible page. Moving through the list is silent; PREVIEW performs one short deliberate audition, and selecting a sound applies that page before Play is retried. Back during the sequence restores the complete pre-remap Project. This conversion is never performed merely because Play was pressed.

Computer-keyboard notes and ordinary incoming musical MIDI audition the selected page's target, channel, program, and drum mapping throughout the FT2 workspace. Shift-rotary column navigation preserves already sounding notes on their original routes while later notes start from the newly selected column. Explicit page/track route, preset, channel, program, or destination changes still end notes on the old route. The FX rack/editor is an FT2 child: live input and the owned synth stay active, and Back returns to its FT2 caller. Leaving top-level FT2 for an unrelated workspace ends notes and unloads its owned synth.

AUTO · machine default is a real portable target. Its saved channel, bank, program, and setup fields are blank; at playback the machine's configured melody/percussion channels and available default destination are used. AUTO does not mean channel 1, channel zero, muted, or disabled. Choose an explicit target only when a song intentionally belongs to particular hardware.

Use FT2 SELECT → PAGE to browse every page without leaving the Pattern or changing its selected column. Its final row opens the full TRACKS screen. There you can add or select a page, choose a column, set its target, channel, bank, and program, and open SYS → ENTRY to choose that page's note-entry layout. DONE validates shared-channel compatibility and keeps the changes. Internal routes use TARGET → ENGINE → INSTR; Moj Sint inserts its explicit MODEL → PATCH hierarchy after ENGINE; external routes use TARGET → MIDI OUT → CH → INSTR/PROG. SYS → EXIT restores the Project as it was before TRACKS opened. A disconnected saved target is marked OFFLINE (or AMBIG for duplicate stable identities); its exact route, notes, raw channels 1–16, and programs 0–127 are not changed. EXIT from a nested Tracks field restores that field's complete original route while retaining unrelated draft edits.

For a quick routing change, SELECT → ROUTE opens a centered overlay over FT2. It shows target type, software engine/instrument or MIDI output, optional device profile, plus all four columns' channel, bank, program/instrument name, and interface availability. With an SHR Drums target, the KIT field cycles the installed drum sets; there is no redundant engine field. Big Rock is the fresh-Project default when installed, while other kits remain explicit choices. Applying a different kit must start it before the route change completes and resets the old kit's tuning overrides; the Project key and drum effects remain unchanged. A failed load restores the previous kit and keeps the editor open with the failure visible.

For Moj Sint, ENGINE stays Moj Sint, MODEL cycles Model D, Six-Op PM, Strange Oscillator, Swarm Machine, and Bass Matrix, and PATCH stays inside the selected model. Changing the model selects its first available patch; changing patches never crosses the model boundary. These live field changes remain inside the same Route Apply/Cancel transaction.

Turn and click/Enter to activate a field. Turning the active field validates and applies each choice to the Project and live route at once, so an available instrument or kit can be auditioned without leaving the overlay. A failed choice restores the previous field value and route. Click/Enter keeps the current field value; Back/Esc restores the value from before that field was opened.

APPLY ROUTING keeps the live result. CANCEL or Back from the main list restores the complete route snapshot from when ROUTE opened. The contextual ROUTE page puts APPLY at physical position 5 and CANCEL at position 8; those controller buttons, mouse targets, and keyboard A/C share the same actions even while the field list scrolls. At 40×13 the bordered outer window is 38×9 at (1,1), its usable inner area is 36×7 at (2,2), rows 11 and 12 are the controller rows, and row 13 remains the shared status row.

Step editing#

Step entry accepts notes and chords from any configured musical input. TRACKS → SYS → ENTRY selects one persisted layout for each page:

• Manual is the backward-compatible default. A note starts in the selected column and a chord continues through later columns.
• One column stores every note in the chosen C1–C4 anchor. It is deliberately monophonic: a new note interrupts the earlier note in that lane, and a chord collapses in deterministic pitch order to its final note. The selected cursor does not move to the anchor.
• Drum auto allocates each simultaneous percussion group across the current page's four ordinary lanes. Kick and snare share a compact primary lane when they alternate, while simultaneous hits spill into distinct safe lanes. Toms, fills, hats, cymbals, and other percussion reuse established lanes when safe and never overwrite an existing target-row cell.

Changing layout affects future entry and recording only; it never rearranges existing Pattern data or changes column routing. The compact layout label and One-column anchor appear in the FT2 footer and Tracks screen. Legacy ordinary pages load as Manual; legacy pages with the persisted percussion flag retain their prior automatic drum layout.

The same Tracks ENTRY list stores NOTE OFF ON/OFF per page. It controls whether future Edit and Record input writes automatic release cells. Melodic pages default to ON; one-shot percussion pages default to OFF. Percussion playback never generates a release from the Project gate, a retrigger, a later same-lane hit, or the Arrangement boundary. A drum voice rings until an explicit OFF/CUT, a kit choke, or Stop, Panic, mute, route-change, or shutdown cleanup catches it. The setting never removes an existing explicit OFF cell and does not disable those deliberate releases.

ADD opens an overlay for every persistent advance from 0 through 32 rows for note/chord entry, blank, erase, and note-off; 0 keeps the current row. The FT2 title shows EDIT +n. A computer keyboard can enter notes with Z S X D C V G B H N J M. Those lowercase letter keys remain musical in REC as well as Play/Edit; in REC, use uppercase S or Space for Stop and Esc or uppercase B for Back so the S and B note keys are never shadowed.

LENGTH is a separate Edit overlay. It chooses 1/1, 1/2, 1/4, 1/8, 1/16, 1/32, 1/64, or 1/128 for melodic entries and defaults to 1/16. The selected duration writes the existing gate/explicit note-off representation; it does not change the independent ADD cursor advance or create a second timing system.

Edit has four controller pages: EDIT, SET, SIZE, and SYS. Normal FT2 SELECT remains one Exit away and still owns PAGE, PATTERN, SONG, and ROUTE. SIZE changes the current Pattern across every page and lane:

• HALF accepts an even length of at least two rows. A populated Pattern asks KEEP TOP, KEEP BOTTOM, or CANCEL and reports the cells each half would discard. An empty Pattern keeps the top half directly.
• ROW- removes the cursor row and shifts later rows up. A populated row requires one confirmation with its exact discarded-cell count; a one-row Pattern is unchanged.
• ROW+ inserts one empty row after the cursor and shifts later rows down, up to the 256-row limit.
• DOUBLE works through 128 rows. A populated Pattern asks COPY NOTES, EMPTY HALF, or CANCEL; an empty Pattern appends empty rows directly.

Successful SIZE changes stop FT2 Play/REC, keep the selected page, lane, and column, preserve Pattern setup and Arrangement references, and then mark the Project dirty. Refusal, failure, and Cancel leave the Pattern unchanged.

Drum auto also checks sounding lane state. An unrelated long-tail cymbal makes its lane unavailable, so later kick, snare, tom, clap, hat, or ornament hits spill elsewhere. Another cymbal does the same when capacity permits. A same-note retrigger or matching explicit choke group may reuse that lane; the new same-lane note then performs the tracker’s ordinary interruption. General MIDI cymbals and hi-hat group 1 are the defaults. Unknown notes predictably fall back to short other percussion, never cymbal. A page can persist non-GM role/choke overrides. If a whole group cannot fit, DRUM LANES FULL leaves the Pattern unchanged; Drum auto does not create a page or drop a hit silently.

This protection is placement only. Playback never reallocates a note or gives cymbals special ownership: any note already stored in the same lane interrupts the previous lane note. Manual entry into a cymbal lane and every One-column entry therefore keep normal monophonic interruption.

The editor can add a note, note-off, or blank step. It can also change the page program and pattern master tempo, mute a lane, and move through rows, lanes, pages, and arrangement steps.

Pressing PLAY on the main FT2 screen starts the first pass at the selected row. When playback reaches the end, subsequent passes restart at row 1 of that Pattern rather than at the original play cursor.

Normal FT2 SOUND replaces its CLICK shortcut with FILL; CLICK remains available on FT2 Tools SYS. Keyboard f uses the same runtime latch. Fill changes are quantized to the next playback-cycle boundary, are cleared by Stop or a new Play start, and never dirty the Project. In normal FT2 that boundary is the selected Arrangement playback span; in Live Patterns it is the current Pattern boundary.

Tempo commands inside cells still work inside the current pattern. When playback enters the next arrangement step, tempo starts again from that referenced pattern's master tempo. The arrangement boundary itself does not send note-off for active lanes. Melodic lanes are released by their own gate/cut/note-off, by a later same-lane note, or by stop/panic/mute cleanup. Percussion lanes release only from an explicit OFF/CUT, a kit choke, or deliberate cleanup.

Cell editing#

CELL EDIT changes one cell as a draft. CONFIRM saves the draft. EXIT or cancel restores the original cell.

A cell contains:

• a blank, MIDI note 0–127, or note-off;
• an inherited gate or a gate from 1–100% of one row;
• inherited velocity or MIDI velocity 0–127;
• inherited program or a MIDI program override stored as 0–127 and shown as instrument/program 1–128;
• independent timing shown as ON GRID, EARLY … ms, or LATE … ms, stored within ±48 units of 1/96 row and applied after Pattern swing;
• independent deterministic chance from 1–100%, with 100% as the default;
• one loop-aware condition: ALWAYS, FIRST, LAST/N, A:B, PRE, or FILL;
• one optional command: cut or delay tick 0–15, retrigger count 1–8, or decimal tempo 20.00–300.00 BPM.

CELL EDIT's rotary field sequence exposes CHANCE, CONDITION, COND A, and COND B without adding a fifth controller page. LAST/N fires on the last pass of each N-pass cycle; A:B fires on pass A of each B-pass cycle; PRE follows the preceding note trigger in the same lane and playback pass; FILL fires only while the performance latch is armed. Conditions are checked before chance. Chance is deterministic for the Project, Arrangement step, row, lane, and pass. Chance and non-ALWAYS conditions require a note-on.

The grid shows < for early, > for late, and a blank marker for on-grid timing without widening the four-lane native grid. C, D, R, and T continue to identify cut, delay, retrigger, and tempo. One cell cannot contain more than one command. Velocity, program, gate, and retrigger need a note-on in a newly confirmed edit. Invalid combinations stay in the draft and show an error.

Choosing PROGRAM opens a full-height sound browser. A matching MIDI device profile adds the instrument's slot labels and sound names. Without a profile, all MIDI programs 1–128 remain available. Performance notes audition the draft sound on that page's exact target and selected-column channel. Confirm keeps the cell override without changing the column master; cancel restores the previous value and selection.

In the ROUTE overlay, confirming an external column's PROGRAM sends that column's bank/program selection immediately, so a connected hardware instrument changes sound for stopped FT2 free play as the field choice is applied. APPLY ROUTING keeps the route in the Pattern and sends the selected column's program again. The Tracks screen's DONE action follows the same selected-column rule. These actions do not wait for Play or for the next note.

Real-time recording#

From stopped transport, REC starts the selected Pattern from row 1 and loops it. Pressing REC during Play punches into the current Arrangement position without replacing that schedule; punch-out returns to Play. Between notes, Shift plus the main rotary may select another column or page without leaving REC, and later notes use that selected page. While one or more recorded notes are held, Shift-rotary turns are ignored rather than queued; movement resumes only after every matching Note Off. Played notes use the active page's Manual, One-column, or Drum-auto allocator and are quantized to Pattern rows by default. The REC CAPTURE page can turn REC FEEL on for the current runtime session; then note-ons keep the nearest row plus their bounded callback-time offset. This option is not Project data, and switching it off returns immediately to zero-nudge recording. Events assigned to one row occupy distinct Drum-auto lanes. REC ignores the Edit note-length setting: each note-on records its exact Pattern/page/lane owner. With automatic Note Off enabled, its matching release writes the quantized note-off in that lane even after cursor movement, a Pattern loop, or an Arrangement boundary. With it disabled, release still clears the live ownership without writing an OFF cell. Repeated identical input notes keep independent owners and cannot release one another early. Newly captured notes and releases are published to the next stopped-record loop without restarting its current cycle. Each assigned lane auditions through that column's channel and the selected page's exact Pattern-owned software or hardware instrument. It does not leak into an unrelated standalone Player instrument. The source port, not a special MIDI channel, separates a performance keyboard from a control-only surface. A combined device retains channel-qualified controller mappings.

Real-time recording accepts the selected page when its exact target is online, including the factory Software Synth page. An offline or missing target refuses REC instead of substituting another destination. Stop, mute, panic, target failure, route interruption, Project replacement, and exit clear every recorded input owner and release auditioned notes. A Drum-auto capacity fault keeps recording and transport responsive, reports DRUM LANES FULL, and leaves existing cells unchanged.

Live audio-level mixer#

The FT2 mixer is available without leaving Play, REC, or Edit. In normal Play, open SOUND → MIX; REC keeps the same MIX action in its MODE page. In any of the three modes, Shift plus main-encoder click opens the same panel, which is the controller path from Edit without displacing its four contextual command pages. The panel snapshots the current Arrangement step/Pattern, cursor row, tracker page, lane/column, mode, and controller-menu page. Main-encoder click, Back, or SYS EXIT returns to that exact editing location.

The panel shows at most twelve current-Pattern strips in one 4×3 grid. A strip is not a MIDI velocity or CC-volume control: it points directly to one existing final-bus audio owner. synthv1, Yoshimi, FluidSynth, Moj Sint, and SHR Sampler pages use SYN; SHR Drums pages use DRM; attached Pattern Loop Mix appears as LOP when the twelve-strip cap has room; and an external-MIDI page uses INP only when an exact two-port SHR input return is configured. Otherwise it says NO RETURN and has no gain or VU. MTR owns whether that pair is stereo or dual mono and the two dual-mono pans; FT2's linked INP strips retain the one shared owner gain. The configured Input remains marked M while software monitoring is off; opening the mixer does not silently defeat the direct/software doubled-monitoring guard.

The heading identifies the source Pattern and current rotary bank. Configured active rotary positions are ranked in order, so physical rotaries 2–13 are usable. Twelve map directly to strips 1–12. Fewer rotaries map to the current bank; turn the main encoder or use BANK-/BANK+ to change banks. Each strip shows its Pattern page/name, owner, signed dB gain, five-LED VU, and L2 or higher when multiple strips share that owner. The VU uses the same circular LED language as the rest of SHR-DAW.

Linked strips read and write one canonical owner gain and one post-gain owner meter. Moving either is audible immediately through the existing 10 ms final- bus ramp. Direction-only controls carry the current linked value, so a physical position cannot jump the shared gain.

In Play and REC, the mixer follows the Pattern that the sequencer is actually sounding, including Arrangement and Live Pattern changes, even while another Pattern remains the saved editor location. In Edit, it follows the Pattern being edited. Opening activates the owned final bus and keeps live Edit audition on the same route: owner gain, Project processing/master strip, master volume, limiter/final meter, recorder tap, and output.

Live Patterns#

Open TOOLS → LIVE to browse four launchable Patterns at a time without changing playback. Selection, current playback, and the replaceable queue have distinct screen states. Launches can use the next Pattern boundary or the next complete bar; immediate launch is a separate deliberate action. Queue cancel, current-Pattern retrigger, literal Stop, and Panic remain directly reachable.

Successful activations can be captured into a temporary list, then explicitly appended to or used to replace the Arrangement. Cancelling leaves the original Arrangement unchanged. The four lanes on the selected Pattern page also have transient live mute, velocity, gate, and transpose shaping which resets only when another Project loads or is created.

The full keyboard/controller workflow, exact held-note transfer, failure behavior, and capture confirmation contract are in Live performance.

WAV Loop Mix#

Open TOOLS → LOOP for four independent private mono/stereo WAV slots. Each stores its filename, source BPM, half/normal/double interpretation, non-destructive start and length, whole-bar offset, level, and bipolar filter. The selected slot is not launched by browsing it.

WAV has no dependable standard BPM metadata, so import and AUTO estimate pulse spacing when useful and otherwise use duration plus the current tempo to choose a whole-bar length. BPM-/BPM+ and BPM x correct source interpretation; UNIT changes cut adjustment between beats and bars. ALIGN re-runs bounded offline analysis or moves placement by a whole bar.

Each slot queues launch/stop for the next Pattern-local bar. A later command replaces the earlier one, and Cancel removes it. All active slots must match their Pattern's interpreted tempo and JACK's sample rate; there is no time-stretching or callback resampling. Different whole-bar lengths stay phase-aligned under that Pattern's tempo and meter. A missing, corrupt, incompatible, late, or failed slot is isolated while healthy slots and MIDI continue.

The screen always edits the Pattern under the FT2 cursor, but browsing another Pattern does not change the sounding Pattern. At an Arrangement or Live Pattern boundary, the outgoing slots stop and the incoming Pattern's prepared slots start with MIDI. Every Arrangement step is a fresh instance: a repeated reference restarts phase at Pattern-local beat zero, while playback begun at a middle row seeks from that local row without adding earlier Pattern durations.

LIBRARY opens the private browser for the selected slot. Browsing is silent; preview is explicit and stops on selection change, Stop, Back, browser close, or leave. INBOX imports; PRIVATE, CURRENT, and SAVED attach an existing private file. REMOVE requires confirmation, clears only the selected Pattern slot, and keeps the private WAV.

See Live performance for level/filter controls, bar scheduling, routing, realtime limits, and the deliberately unsupported DJ features.

Copy and Paste#

Pattern copy stores the complete current FT2 Pattern, including rows, pages, routes, channels, programs, mutes, meter, tempo, and all four Loop Mix references/settings. Paste-new and Clone make independent Pattern copies; paste-over replaces the destination Pattern's loops only after its existing confirmation. Repeated Arrangement references do not clone: editing the shared Pattern changes every step that references it.

The FT2 tools clipboard can copy and paste one lane/column or one full page block. Lane and page paste keep note, velocity, program, gate, and command cells. When source and destination row counts differ, only overlapping rows are pasted and the status line reports truncation. Page paste targets the selected destination page; missing destinations are not created implicitly.

This is a cell-block clipboard, not a complete Page operation. It does not copy the Page name, destination, column setup, entry behavior, mute state, or Page-targeted automation. Rename, complete duplicate, reorder, remove, clear, and cross-Pattern Page operations are recorded under Future Page operations.

Drum pattern library and transpose#

Open FILES → PATTERN → DRUMS for reusable rhythms stored separately from Projects. The bundled library has 72 authored grooves across Rock, Pop, House, Techno, Hip-Hop, Funk, Reggae, Breaks, Latin, and Jazz. The FILTER page selects genre, 3/4 or 4/4 meter, and phrase length. 4/4 offers 32/64/128 rows (2/4/8 bars at the default four steps per beat); 3/4 offers the matching 24/48/96 rows. Longer choices add alternating-bar changes and genre-aware phrase-end fills rather than merely duplicating a filename. Genre names are compact creative labels for editable starting points, not claims of an authoritative historical transcription.

LOAD replaces only the current Pattern's first percussion page. Its destination, channels, bank/program setup, lane state, tempo, and arrangement remain unchanged. An empty melodic Pattern is resized to the selected meter and length for the quick load-drums-then-enter-bass workflow. If melodic cells already contain data, any load that would resize or change meter is refused.

SAVE writes the current percussion page as a non-overwriting .shdrum file below ${XDG_DATA_HOME:-~/.local/share}/shsynth/drum-patterns/. DELETE requires confirmation and applies only to user-saved files; bundled grooves are read-only.

The Pattern TRANS page moves all note-ons on non-percussion pages by a semitone or octave up/down. Percussion pages and note-offs are never changed. If any melodic note would leave MIDI range 0–127, the whole transpose is refused without changing the Pattern.

FT2 Arrangement#

Use SELECT → SONG for quick Arrangement-step navigation. Choose EDIT ARRANGEMENT there to edit the FT2 Arrangement separately from pattern editing and Project files. The ARRANGE screen can select a step, append or insert the current pattern, duplicate or remove a step, move a step earlier or later, jump to the referenced pattern for editing, and play from the selected step.

ARRANGE's FORM page opens the bounded A A B A assistant. A is the Pattern referenced by the selected Arrangement step. B starts unselected; turn the main encoder or use B-/B+ to choose one existing Pattern ID explicitly. The draft changes no Project data and shows all four references, each Pattern's row count, the total four steps and total rows, plus any missing or invalid Pattern.

With transport stopped, APPEND adds those four references after the current Arrangement. REPLACE swaps only the Arrangement and first passes through the normal unsaved-Project SAVE (AUTO) / SAVE (NAME) / DON'T SAVE / BACK guard when the Project is dirty. CANCEL or Exit returns to the same Arrangement selection and controller context. Refusal, missing Patterns, invalid limits, and failed validation leave Arrangement, Pattern data, Pattern History, dirty state, transport, and the FT2 cursor/context unchanged. This first slice never clones or edits Pattern contents and stores no recipe.

Automation, metronome, and count-in#

Each Pattern owns independent sparse automation lanes; automation never uses the cell command character. Open AUTO from FT2's SOUND page. Up/Down picks an existing lane without moving the tracker cursor. Merely opening AUTO does not add data or dirty the Project; NEW explicitly creates the first or next unused target lane. The controller pages arm capture, add/delete and browse points, adjust a point, choose a stable target, inspect the target-owned curve type, and confirm CLEAR. A populated lane keeps its target until CLEAR is confirmed, so browsing cannot silently discard points. Continuous instrument, external CC, and effect parameters show RAMP: the value reaches the next automation point exactly. Integer, choice, toggle, bypass, mode, and division targets show STEP and change at their point. One point holds.

Arm is explicit and applies only to the selected lane. Touching its control records at the real transport position and monitors the value while tracker notes may be recorded at the same time. Unarmed controls do not replace an automated value. Start, stop, Project replacement, reset, arm changes, and leaving AUTO keeps relative turns anchored to the effective automated value. When stopped, the selected lane follows the tracker cursor. If Arrangement playback enters a different Pattern while capture is armed, AUTO becomes safe instead of applying the same lane index to unrelated Pattern data; reopen and arm that Pattern deliberately. Removing an effect, or confirming a different effect type, removes every now-unresolvable lane for that exact effect and reports the lane/point count. Cancelling a type change retains those lanes. Playback chases the current point and active ramp when started with Play Here; Pattern/Arrangement loops continue without restoring a preset value. Recorded knob streams are thinned into a bounded curve.

CLICK toggles SHR-DAW's final-bus metronome. It accents beat one and never sends click notes to a page. REC from stop shows one Pattern-meter bar as 4 3 2 1 → REC (or the matching meter), then transport and capture begin at row zero. REC while already playing punches in without restarting transport. Count-in clicks are neither Pattern events nor borrowed instrument/drum voices.

Pattern and Project files#

Pattern setup starts with the convenient 4/4 sizes 8, 16, 32, 64, and 128 or the matching 3/4 sizes 6, 12, 24, 48, and 96. Its LNGTH overlay also makes every row count from 1 through 32 plus 48, 64, 96, 128, 192, and 256 available for either meter.

The Files screen saves, loads, previews, and deletes the whole Project. Its PATTERN child keeps create, clone, copy, paste, resize, clear, transpose, and drum-library operations together. NEW starts with empty Loop Mix slots. Clone copies all MIDI and Loop Mix settings into an independent Pattern. Resize retains Loop Mix settings. Confirmed CLEAR keeps established page/routing setup but clears cells and explicitly detaches attached loops. Arrangement repeat/duplicate adds another step that references the same Pattern. CLEAN offers only Pattern records with zero Arrangement references, confirms deletion, preserves at least one Pattern, and never deletes private WAV files or rewrites an Arrangement step.

NEW PRJ requires a second press before replacing the in-memory Project and chooses the next free project-001 style name. SAVE AS immediately writes the next free <current-name>-copy-001 style copy and switches to it. These automatic names keep both actions usable from a four-button controller. NAME starts with the current display name. Main-rotary click accepts it, while computer-keyboard editing is optional; collisions are refused and a saved rename keeps the loaded Project state.

FT2 workspace Exit and computer-keyboard quit open the dirty-Project guard only after at least one note event exists anywhere in the Project. With zero note events, Exit discards unsaved setup experiments back to the clean baseline and returns without a save question; quit likewise never asks to save. Empty routing/template work is retained only through an explicit SAVE. New Project, LOAD, and MIDI replacement still protect any dirty Project before replacement. The rotary guard opens on SAVE (AUTO), followed by SAVE (NAME), DON'T SAVE, and BACK. SAVE (AUTO) reuses a saved identity or chooses the next free automatic name. SAVE (NAME) starts with a collision-free automatic suggestion that rotary click accepts without typing. DON'T SAVE explicitly restores the clean Project baseline before FT2 Exit. BACK, Esc, and any failed or pending save keep the Project and exact mode/order/Pattern/page/lane/row context.

MIDI uses the private configured MIDI inbox and follows an analyse-then- confirm workflow. Analysis changes nothing and reports parts/pages, Patterns/rows, tempo and meter, exact and quantized timing, maximum displacement, stripped events, and important mappings. Confirmation creates a new unsaved FT2 Project; a dirty current Project uses the same four-choice rotary guard. Parsing, conversion, allocation, preparation, or cancellation keeps the current Project, cursor, routing, Loop Mix, effects, and clean baseline unchanged.

The importer accepts bounded regular SMF format 0/1 files with PPQN timing, running status, conductor tracks, track names, tempo maps, fixed 3/4 or 4/4, and fixed 6/8 mapped visibly to the compound 3/4 grid. It groups each MIDI track/channel part, preserves channel, velocity, initial CC0/CC32/program, and bakes sustain into note lengths. Four monophonic lanes are allocated deterministically per page, with overflow pages and bar-boundary Pattern splits as needed. SMPTE, format 2, changing/unsupported meters, malformed files, and bounded-limit violations are refused.

Lyrics, copyright, markers, cues, key metadata after reporting, SysEx, aftertouch, machine-control/timecode/realtime messages, sequencer metadata, unsupported CC automation, pitch bend, and later unrepresentable bank/program changes are stripped and counted. Imported system or SysEx data is never transmitted. Timing stays in musical ticks; non-representable positions are quantized and reported rather than flattened to elapsed microseconds.

EXPORT on FILES' PREVIEW page writes the whole Arrangement as genuine tick-domain SMF format 1. The first press analyses and reports track count plus omitted Loop Mix slots and SHR effect lanes; a second press saves below ${XDG_DATA_HOME:-~/.local/share}/shsynth/exports/. Existing files are never overwritten. The conductor carries exact tempo and meter changes. Named page/channel tracks carry bank, program, CC, velocity, notes, and exact gates in deterministic setup/CC/note order. Instrument and external-CC automation are exported. Live playback keeps the full 1/96-row cell timing fraction; SMF export rounds that fraction to the nearest tick in the established export timeline. Audio loops and internal effect automation are omitted and counted rather than disguised as portable MIDI.

The FX rack, editor, and fixed MASTER STRIP always show the owning Project plus NEW, SAVED, or DIRTY; source, AUX, master racks, and strip are all Project data. The strip remains global when Arrangement or Live Patterns changes Pattern.

Projects are readable .shsong text files stored below ${XDG_DATA_HOME:-~/.local/share}/shsynth/songs/. Current Project format 18 stores each Pattern's tempo, meter, pages, four column setups, lanes, setup messages, per-page entry mode/anchor, automatic Note Off choice, and drum-role overrides, cells, persistent Project tonic/mode, selected drum kit and tuning, the fixed internal-drum Reverb-then-Delay rack, source insert rack, three aux routes, and master rack. Portable pages use explicit default markers rather than numeric routing. Pattern-owned software pages store explicit engine and stable instrument identities; optional external-device profiles are stored separately from raw output/channel/bank/ program data. Each Pattern also stores exactly four optional Loop Mix slot records and bounded sparse automation lanes. Format 13 and older Projects gain empty automation in memory. Format 7's four Project-global slots migrate in memory into every distinct Pattern. Format 6's single loop= record similarly migrates to slot 1 of every Pattern with its filename, BPM interpretation, cut, and placement unchanged; level becomes unity and the filter neutral. Only references and settings are copied, never WAV files. Format 15 adds Pattern swing and the independent signed timing value on each cell. Formats 0–14 load straight and on-grid in memory. Format 16 adds deterministic cell probability and condition; formats 0–15 load at 100% and ALWAYS. Loading, previewing, or inspecting does not rewrite an old file. Format 17 adds independent lane cycle length, rate, and direction; formats 0–16 load FULL/1X/FORWARD. Format 18 expands the bounded aux inventory to three while older Projects retain their existing routes. Explicit save writes format 18. Formats 0–9 migrate their whole-BPM Pattern and tempo-command values to integer hundredths in memory. Format 10 persists those fields as integer hundredths, so 10050 means 100.50 BPM. Formats 0–8 gain a neutral fixed strip only in memory. Format 10 pages infer automatic Note Off as ON for melodic pages and OFF for percussion pages; format 11 persists the explicit per-page choice. Formats 0–11 migrate with C major, the starter-kit identity, tuning OFF, and their original page routes unchanged. Format 12 preserves those values and routing while adding restrained family-specific drum-effect defaults in memory. Format 5 and older ordinary pages load as Manual with anchor C1 and no overrides. Pages carrying the old explicit percussion flag retain their prior automatic drum entry. Versions 0 and 1 gain empty effects routing; version 2 retains its source rack and gains empty aux/master routing. Format 3 routes stay explicit. Version 0 page-wide setups copy the old channel/bank/program into all four columns. Unknown newer versions, fields, or invalid effect shapes are not loaded or overwritten. Older ActiveInstrument and old synthv1:<preset name> routes are upgraded in memory to explicit synthv1 engine/instrument routes and are not rewritten until the musician explicitly saves the Project.

If an empty Pattern's routing differs from the current new-Pattern template, SAVE asks whether to make it the new routing default. The compact prompt states that new Patterns will use the route, that confirming saves the default, and that cancelling keeps the old default. Confirming queues the private template and writes it only after the Project save succeeds; cancelling saves the Project but keeps the old template. A pending, refused, or failed Project save leaves the template unchanged. A Pattern with notes never changes that template implicitly, and no prompt appears when routing is unchanged. The template is stored outside the repository at ${XDG_DATA_HOME:-~/.local/share}/shsynth/ft2-routing-defaults.shsong and is used by every subsequently created Project or Pattern.

Cleared demo songs#

Setup seeds ten public-domain demo Projects into the same song directory, so they appear on FILES without an import step. Matching format-1 MIDI files and the clearance manifest live below ${XDG_DATA_HOME:-~/.local/share}/shsynth/demos/. Seed copies never replace a same-named user Project. Each arrangement has separate drums, bass, pad, lead, and counterline pages on AUTO, making it easy to choose new sounds or bind a page to hardware. See Public-domain demo songs.

Effects saved with the Project#

The Project also owns the managed instrument's ordered source insert rack, three aux send/rack/return routes, and master rack. Those settings are independent of the Pattern/Arrangement structure: repeating a Pattern does not duplicate an effect, and changing Arrangement steps does not change rack order. The three aux sends take their pre/post source-insert taps from the one managed software instrument, not from individual MIDI lanes.

With the opt-in graph active, the managed source and wet returns, SHR Drums, private WAV loop, and exact configured two-port external-input return meet once before the master rack and final meter. SHR Drums has its own final-bus level and mute but no multi-mic live mixer. The loop, drums, and external input do not acquire the melodic source inserts or aux sends; the raw multitrack recorder remains a separate capture path. See How SHR-DAW works for the musical workflow and Audio graph and DSP contract for exact effect schemas and limits.

Detailed controls and routing#

See the Controller interface for the full FT2 menu map. See Configuration and routing for page routing, exact targets, note ownership, and Project behavior.

FastTracker II was created by Fredrik “Mr.H” Huss and Magnus “Vogue” Högdahl of the demo group Triton. Learn more at Demozoo.

Back to detailed guides

SHR-DAW has two complementary performance systems in the FT2 workspace:

• Live Patterns launches existing MIDI tracker Patterns.
• Loop Mix launches and mixes up to four private WAV loops or stems.

They share Pattern ownership, transport timing, safety controls, and the configured controller. A Pattern owns both its MIDI tracker pages and one logical four-slot decoded-audio Loop Mix page. The loop page is not four fake MIDI lanes, and neither system turns SHR-DAW into a full DJ application.

Live Patterns#

Open FT2 → TOOLS → LIVE. The screen shows four Patterns from the current group. Turning the encoder or using Up/Down browses through all Patterns in groups of four. Browsing changes only the white selection; it does not launch anything and does not move the FT2 Arrangement Step, row, page, lane, column, or edit cursor.

The display distinguishes:

• the selected Pattern with the selection highlight;
• the sounding Pattern with green PLAY; and
• the queued Pattern with yellow Q.

LAUNCH or Enter queues the selected Pattern. The first Live Pattern starts directly because there is no earlier Live Pattern boundary to wait for. NOW is the deliberate immediate action. RETRIG queues the currently playing Pattern again, including when it is also the selected Pattern. CANCEL removes a pending launch without changing playback. A later launch before the boundary replaces the earlier queue.

The TIMING controller page selects either:

• PAT Q — activate at the end of the current Pattern; or
• BAR Q — activate at the next complete Project-meter bar.

The keyboard equivalents are l for quantized launch, L for immediate launch, r for retrigger, c for cancel, and q to toggle Pattern/bar quantization. s or Space is literal Stop. Panic remains on the SYS page and through the controller's global safety action.

Live Patterns does not change the saved Arrangement. Outside this screen the ordinary Arrangement plays exactly as saved.

Note and instrument ownership#

A successful quantized change transfers a lane only when its destination, channel, held note, and next Pattern event still agree. Otherwise SHR-DAW sends the exact old note-off before the new event. It does not release all lanes just because the Pattern number changed.

If the queued Pattern needs a different software instrument, the old owners are released at the activation boundary, the one managed engine is replaced, and the new Pattern begins only after the replacement succeeds. SHR-DAW never layers managed synth engines. A failed replacement restores the previous managed session where possible and resumes the previous Pattern from a clean boundary; incoming loops are stopped, the failed launch is not captured, and no incoming loop remains under the restored MIDI Pattern.

Immediate launch deliberately releases the old scheduled owners first. Stop, lane mute, target loss, Project replacement, Panic, shutdown, and application exit release the exact destination/channel/note owners and retain the normal all-channel panic. Missing or ambiguous external targets remain visible and are never replaced with another route.

Capturing a Live Pattern performance#

CAPTURE arms an empty temporary list. Only successful Pattern activations at their actual boundaries are added. Browsing, a replaced or cancelled queue, a failed launch, and ordinary Pattern looping are not captured.

Press CAPTURE again to stop and enter the reversible confirmation state. Then choose:

• APPEND to add the captured Pattern references after the existing Arrangement; or
• REPLACE to replace the Arrangement with the captured references.

Back/CAPTURE cancels confirmation and leaves the original Arrangement unchanged. An empty capture cannot replace it. Repeated launches remain repeated Pattern IDs; Pattern rows and pages are not cloned.

Live lane shaping#

The lower half of Live Patterns controls the selected Pattern page's four MIDI lanes. Left/Right selects a lane. The controller SHAPE page or keyboard offers:

• m — transient live mute;
• v — velocity/intensity scaling;
• g — gate-length scaling; and
• t — transpose in semitones.

After choosing velocity, gate, or transpose, turn the main encoder or use Up/Down; press Enter to return to Pattern browsing. Velocity and gate are bounded to 10–200%. Transpose is bounded to -48..+48 semitones. Resulting MIDI velocity and gate values remain in their legal ranges, and transposed notes are clamped to 0–127 without wrapping.

These controls shape a runtime copy of the Pattern. They never rewrite stored cells or persisted lane settings. Velocity, gate, and transpose changes take effect on the next activation boundary, so changing them while a note is held cannot release another owner. Mute releases only that live lane immediately. Repeated notes continue to use the sequencer's exact ownership ledger.

The state survives navigation while the same Project is open. Loading or creating a Project resets every live shape to 100% velocity, 100% gate, zero transpose, and unmuted. The main encoder is a relative navigation control from controller.conf or the selected controller profile, so these controls do not introduce hard-coded CCs or an invisible positional-knob mode. All mapped rotaries use the direction-only controller contract.

Lane shaping is MIDI performance data, not per-lane audio processing. Several lanes can share one stereo synth output, and external devices do not share a universal filter CC.

Loop Mix#

The fourth FT2 page is Loop Mix. It always shows the four WAV slots owned by the Pattern under the FT2 cursor and keeps editing selection separate from the sounding Pattern. Browsing a Pattern changes this page without launching it. Left/Right or SLOT-/SLOT+ selects a slot. Slot and command-page context survive navigation within the same Pattern and reset when the owning Pattern or Project changes. Each row shows only useful state:

• PLAY or STOP;
• Q▶ or Q■ for a queued bar-boundary command;
• MUTE;
• FLT; or
• — for an empty/missing slot.

Each slot stores a private mono or stereo WAV filename, source BPM, half/normal/double interpretation, non-destructive start and length in beats, whole-bar placement offset, level, and bipolar filter. Different loop lengths are allowed when they are whole bars at the same interpreted tempo.

LAUNCH and STOP queue independent actions for the next Pattern-local bar. Repeated commands replace the earlier action for that slot. CANCEL clears it. Keyboard equivalents are p, P, and c. m toggles mute. Level is bounded to 0–150%; the slot filter is bounded to -100..+100%.

At filter centre a small deadband is neutral. Turning left progressively low-passes the slot; turning right progressively high-passes it. 0 returns to neutral. Level and filter changes are smoothed. Filter state and output are finite and bounded under rapid movement.

IMPORT/LIBRARY uses the existing private browser for the selected Pattern and slot. Inbox WAVs are copied without replacement below private XDG/user storage; existing private/current/saved entries attach without copying. REMOVE requires confirmation and removes only that Pattern's reference while keeping the private WAV. Preview remains explicit and stops on selection change, Stop, Back, browser close, or leaving the browser.

NEW starts with empty slots. Clone, Pattern copy/paste-new, and paste-over copy all four references and settings; paste-over still requires confirmation. Resize retains them. Confirmed CLEAR explicitly detaches them while retaining the established MIDI page/routing setup. CLEAN removes only an unused Pattern record. Private WAV files remain shared library assets and are never duplicated or deleted by Pattern operations. Editing a shared Pattern affects every Arrangement step that references it; cloning makes an independent copy.

Tempo, rate, and failures#

Loop Mix does not time-stretch or preserve pitch while changing tempo. Every active slot's interpreted BPM must equal its owning Pattern's current tempo. An incompatible slot is refused rather than allowed to drift. Each WAV must also match the current JACK sample rate; SHR-DAW does not resample it in the callback. Corrupt, oversized, missing, incompatible, or failed WAVs fault only their own slots, and healthy slots continue.

All four renderers follow the owning Pattern's tempo, meter, local origin, and bar clock. At every ordinary or Live Pattern boundary, outgoing slots stop, prepared incoming slots activate with MIDI, and phase restarts at local beat zero. A repeated reference to the same Pattern is a fresh instance and also restarts. Starting from a middle row seeks from that Pattern-local beat; starting at a later Arrangement step never adds earlier Pattern durations. Empty incoming slots stop their outgoing counterparts. A late or failed preparation leaves only its slot silent and faulted. A tracker tempo command that becomes incompatible stops/faults affected loops while MIDI continues. Queues prepared for an old Pattern are discarded rather than applied to a new owner. Stop, Panic, Project replacement, JACK shutdown, application shutdown, and exit stop all four and retain All Notes Off.

Audio routing and realtime limits#

The four WAV renderers sum inside one owned shs-loop JACK client and expose the existing logical Loop stereo source. The final bus therefore remains exactly four fixed nodes: Synth, Loop, Input, and Drums. It does not gain four general-purpose Loop strips. Optional sources can be absent; Input MON ON requires only the exact Input and playback pairs.

In direct mode the Loop output owns its configured playback connections. A final-bus transaction moves that one summed source into the graph and removes the direct path, with rollback on failure. The limiter, FINAL OUT, and final stereo recorder receive the complete four-slot sum once. SHR-DAW does not create or disturb unrelated JACK connections.

WAV discovery, file access, decoding, validation, import, analysis, and bounded active/incoming preparation happen outside the JACK callback. Stored Patterns do not create clients or renderers and are not decoded eagerly. Prepared state is published through one bounded pending four-renderer set and an atomic pointer swap; its retired set is reclaimed by the owner thread. The callback has fixed meter/DSP memory and performs no allocation, locking, file access, formatting, decoding, or unbounded work. There is still exactly one stereo Loop source.

Deliberate limits#

There are currently no Playlists, companion mode, cue/headphone buses, crossfader, scratching or jog-wheel emulation, beat-grid editor, automatic beat matching, time-stretching, pitch-preserving tempo change, waveform editor, standalone Pattern library, additional audio buses, or new general-purpose mixer strips. Project effects, final-bus routing, recording configuration, and unrelated Project state remain Project-owned.

Back to detailed guides

SHR-DAW ships ten original, editable arrangements of traditional or otherwise public-domain compositions. They are musical starting points, not copies or imitations of modern recordings. Every arrangement has five independent parts: Drums, Bass, Pad, Lead, and Counter.

Composition	BPM	Meter	Key	Suggested restyles
House of the Rising Sun	84	6/8	A minor	folk rock, dark synthwave, ambient
Whiskey in the Jar	108	4/4	D major	Celtic rock, acoustic, festival EDM
Cotton-Eyed Joe	126	4/4	G major	country dance, chiptune, electro-folk
Scarborough Fair	92	3/4	D Dorian	medieval ambient, trip-hop, orchestral
Greensleeves	96	3/4	A minor	Renaissance, dream pop, cinematic
Amazing Grace	76	3/4	G major	gospel, ambient, orchestral build
Drunken Sailor	116	4/4	D minor	punk shanty, industrial, festival folk
Wellerman	104	4/4	E minor	sea folk, synth-pop, drum-and-bass halftime
Auld Lang Syne	88	4/4	D major	piano ballad, post-rock, New Year synthwave
Danny Boy	72	4/4	D major	cinematic, ambient, slow rock

Setup copies each native .shsong into the XDG song directory without replacing an existing file, so it appears directly on FT2 FILES. Its pages use portable AUTO routing. Matching format-1 .mid files and a copy of the manifest are kept below ${XDG_DATA_HOME:-~/.local/share}/shsynth/demos/.

The canonical metadata is demos/cleared-demos.json. For every title it records the short arrangement description, exact filenames and SHA-256 hashes, public-domain reasoning, institutional source links, and the MIT licence for SHR-DAW's newly authored arrangement. House of the Rising Sun remains 6/8 in MIDI; because the current tracker stores a 3- or 4-beat grid without a denominator, its native Project uses the documented 3/4 compound grid while preserving the two-beat feel.

Maintainers regenerate or validate the corpus with:

./scripts/generate_demo_songs.py --write
./scripts/generate_demo_songs.py
make check-demos

The normal command is validation-only. Packaging first requires an exact deterministic match, then installs only paths emitted from the cleared manifest. An altered, missing, malformed, or extra file therefore stops the package.

Back to detailed guides

This document owns the controller action inventory and paging contract. Use the screen and menu manual for screenshots and the musician guides for task order. The inventory follows the current keyboard, mouse, encoder, command-pad, screen, and contextual dispatch paths.

Startup splash#

Startup first shows a 40×13 old-school stereo LED animation using all thirteen top-origin terminal rows. Row 0 contains the indicator strip; rows 1–3 are empty; row 4 contains a lowercase shr - daw wordmark, where one bright light-blue glyph moves quickly across otherwise bright-white text; rows 5–7 are empty; rows 8–9 contain the R meter; row 10 is empty; and rows 11–12 contain the L meter. Each meter uses two identical horizontal ● rows. Unlit meter LEDs are dark gray; lit LEDs use one green below −12 dBFS, yellow from −12 through −3 dBFS, and red above −3 dBFS. The animation is decorative and does not start audio, playback, or MIDI transmission.

The indicator strip contains six identical five-cell indicators: one dynamic build-mode cell followed by CFG, SND, TTY, CTL, and INP. The build cell displays blue DEV in a debug build or green REL in a release build. Each three-letter label is centred in its coloured cell. At 40 columns their 30 coloured cells and five two-cell black separators fill the row exactly, with no outside margin. They sweep from red over 2.5 seconds, then hold complete before the three-second minimum ends. At full load the build cell has its mode colour and every completed startup phase is green, so an inactive build mode does not leave a false red warning. These are loader phases, not claims that JACK or all synth engines are running.

A terminal computer keyboard remains an optional fallback for controller navigation and text editing; the main rotary and numbered pads complete the core workflows without it. Only when none of those inputs is available does the splash remain open, show CONNECT KEYBOARD OR MIDI INPUT and the expected input in the normally empty recovery rows, and rescan the configured MIDI inputs. Esc or q can still exit from the splash.

Action inventory#

Screen or mode	Existing user-facing operations and input paths
Home	Centered startup navigation root with equal-width bars for Software Synths, FT2, Recorder, Performance, MIDI Learn, Routing, Effects, Ideas, and Help. Encoder/Up/Down selects a workspace and encoder click/Enter opens it. Its existing bottom line overrides ordinary guidance with the exact owning workspace whenever recording or transport remains active. Home has no MIDI quit command; Esc or q quits from the computer keyboard. A note-bearing dirty Project uses the rotary SAVE (AUTO) / SAVE (NAME) / DON'T SAVE / BACK protection; a zero-note Project never asks to save on exit.
Presets	Select previous/next, keyboard page up/down, first/last, Shift-rotary previous/next engine across synthv1, Yoshimi, FluidSynth, Moj Sint, and SHR Sampler, and load the selected sound. Moj Sint sounds show their synthesis model separately from the Moj Sint engine; SHR Sampler packages remain read-only. Its physical pages contain only sound browsing, load, panic, contextual help, and Exit to Home; engine browsing remains available from Shift-rotary, [/], and the two header halves.
MTR	With the final bus active: choose Synth/Loop/Input/Drums, adjust its bounded smoothed level, use MUTE for optional sources or the one MON ON/MON OFF Input action, switch Input between stereo and dual mono, and pan configured Input 1 and Input 2 independently in dual mono. IN CTRL cycles LEVEL/PAN 1/PAN 2, and the ordinary minus/plus pair follows that focus. Both new Input choices live on the visible NAV controller page and add no dedicated computer-keyboard shortcuts. Dual mono starts at 1L100 2R100, so its initial output matches stereo. Inspect final sample/true peaks and linked reduction, and start/stop the callback-boundary final stereo recording. Input monitoring defaults off and MON ON can activate the bus without launching an optional source. At native 40×13 the body reserves its final rows for recording integrity and a doubled-monitoring refusal; healthy sources omit READY/ON. With the bus inactive, the passive CPU/VU view puts an unavailable reason in the VU heading instead of clipping it below the body. NAV opens either the selected source/AUX/master rack overlay or the fixed Project MASTER STRIP and owns the two Input controls.
Playback	Inspect held notes/chords and aligned decimal MIDI strike velocities, with keyboard state added only when the terminal is taller than native 40×13; toggle the N00B filter in place and, while enabled, turn the main rotary through all root plus major/natural-minor choices shown by a compact SCALE control; reset the active synth parameters in place; open and return from the FX rack without stopping the sound; use STOP/PLAY/RECORD/TAP for a free-time take or the dedicated external-sync controller arpeggiator; save the current synthv1 or Moj Sint sound through the explicit Overwrite/Save New/Cancel overlay; use SOUNDS to return directly to the Presets catalog and its visible LOAD; panic; contextual help; return to Presets. PLAY sends a fresh controller Start even with no take, RECORD starts the same clock before capture, STOP sends Stop without unloading the sound, and TAP changes tempo without starting transport. Factory/system sounds are read-only and redirect Overwrite to a private numbered sound. Saving changes neither the running engine nor held notes and makes the values the new RESET baseline. N00B never replaces the Player body. The native parameter surface is always three by five: Synthv1 and the five older Moj models show twelve synth controls plus AUX 1/2/3 sends, while Moj Sint Dual Filter shows its fifteen synthesis controls. Aux sends use a live 10 ms gain ramp and refuse changes during recording. Direction-only mappings carry current values.
Ideas	Previous/next/first/last idea; inspect, load, play, delete, record, and save; panic; contextual help; Exit to Home.
FT2 normal	The main rotary always moves rows; holding the configured encoder Shift while turning selects the previous/next column across page boundaries, while Shift-click opens the FT2 live mixer. Keyboard Up/Down also moves rows. PLAY holds cell edit and transport, SELECT opens PAGE/PATTERN/SONG/ROUTE rotary overlays, SOUND contains PARAM, MIX, AUTO, and next-boundary FILL, and SYS holds panic/N00B/help/Exit. PARAM and AUTO return to the exact cursor, mode, transport, route, and launching page. CLICK toggles the internally owned final-bus metronome from FT2 Tools SYS item 3. With external SYNC selected, local PLAY enters visible clock waiting or performs literal Stop; only an acquired incoming Start launches Arrangement step 1/row 1 or selected Pattern/row 1. In ROUTE, turning an active field validates and applies the choice to the Project and live route. Moj Sint exposes ENGINE → MODEL → PATCH; patch browsing stays within its selected model. APPLY keeps the result; CANCEL restores the route snapshot from when the overlay opened. Back restores the active field first. The physical item buttons, mouse, and keyboard A/C share those actions. Its KIT field selects an installed SHR Drums kit when the target is SHR Drums; a successful kit change resets old kit-specific tuning while preserving the Project key and drum effects. Exit never asks to save when the entire Project has zero note events; explicit SAVE remains available for an empty routing template.
FT2 PARAM	Reuses Playback's active backend/model three-by-five renderer, values, relative-to-preset colours, held-note presentation, and configured rotary 2–16 mapping while keeping tracker engine ownership. Older 12-control instruments expose AUX 1/2/3 in the final row; Dual Filter retains all fifteen synth controls. SOUND provides RESET, SAVE, N00B, and one empty position; SYS provides Panic, one empty position, Help, and Exit. RESET is in place. SAVE reuses Overwrite/Save New/Cancel and retargets only the active matching FT2 route after success. Unsupported backends visibly provide neither editable parameters nor save support. The ordinary and Shift rotary do not edit synth parameters. Back/Esc/Exit restores the exact FT2 state and launching menu page.
FT2 mixer	A mode-preserving live audio child for up to twelve current-Pattern strips. Configured active rotary positions map directly with twelve controls or to a rotary-selected bank with fewer. Each strip shows page/name, canonical Synth/Drums/Loop/Input owner, signed dB gain, five-LED post-gain VU, link count, and honest NO RETURN, monitor-off, or offline state. Linked pages share gain/VU. Play/REC follow the sounding Pattern; Edit follows the edited Pattern. Opening activates the final bus without silently enabling Input monitoring. Main-encoder click, Back, or SYS Exit restores the exact tracker context.
FT2 automation	Pattern-owned sparse-lane child. Opening is read-only; NEW explicitly creates an unused target lane. Up/Down changes lanes; REC arms only the selected target and adds/deletes points; POINT browses and adjusts points; LANE changes an empty lane's target, explains fixed RAMP/STEP meaning, and confirms clear. Populated lanes refuse target browsing until CLEAR is confirmed. Touch capture uses transport time, can run beside note REC, monitors the armed value, and becomes safe rather than writing through a Pattern boundary. Effect removal or confirmed type replacement reports and clears only that effect's now-unresolvable lanes; Cancel retains them. Back restores exact tracker context.
FT2 HARMONY	Read-only FT2 Tools overlay derived from the current Project tonic and major/natural-minor mode. It shows both circle-of-fifths neighbours, relative and parallel keys, and seven diatonic triads using the configured English/German note-name policy and SHR's canonical sharp spelling. Opening, repeated opening, encoder turns, and closing cannot change or dirty the Project, generate notes, or alter transport. The launcher/Exit, keyboard H/Back/Esc/Enter, controller, and mouse paths restore the exact caller page, page-select mode, Pattern/order/page/lane/column/cursor, FT2 mode, and transport.
FT2 HISTORY	Bounded runtime history for committed mutations to one existing Pattern. Page 1 is exactly Undo, Redo, Snapshot, Recall; page 2 opens FEEL, GROOVE, CYCLE, and GEN. FEEL drafts Pattern swing division/amount. GROOVE drafts one deterministic preset/scope/strength and writes exact cell timing/velocity only on Apply. CYCLE drafts the selected lane's independent length, rate, and direction; stopped Apply is one history entry and never moves the FT2 cursor or changes Arrangement duration. GEN opens the one offline inspectable Euclidean/accumulator/seeded-mutation/controlled-FILL/arpeggio/chord/harmonizer workflow described below. Unavailable restore controls are visibly disabled. Snapshot capture is non-dirty and Recall is undoable. Mouse and controller dispatch the same actions; keyboard adds Ctrl+Z, Ctrl+Y, and Ctrl+Shift+Z. Restore preserves Pattern/order/row/page/lane/column/mode/controller context and currently requires stopped FT2 transport; a Play-time attempt leaves the stack unchanged, while REC Undo finishes the take and held-note cleanup first.
FT2 GENERATOR	Offline draft for the selected Pattern/page/lane/cursor context, with explicit harmonic source/target, complete tool settings, affected/replacement/collision/protected counts, affected rows, out-of-scale skips, range/scope refusals, collision policy, and retained seed where used. ROLL is percussion-only: amount selects 1–8 total pulses, length selects the bounded span, DETAIL changes velocity depth and EVEN/ACCENT/CRESCENDO shape, and its visible NEW CLONE default makes Apply use the existing independent Clone transaction. ARPEGGIO reads the cursor-row chord and exposes order/octaves/rate/gate/repetitions; CHORD uses Project key/degree/inversion/close-or-open voicing/three lanes/rate/repetitions; HARMONIZER copies a bounded source-lane span to an explicit target as a diatonic third/fifth above/below under REFUSE/SKIP policy. SHAPE selects tool/length/amount; DETAIL exposes tool-specific secondary/control values and policy; VALUE changes gate, chord rate, harmony target, or existing seed as named in the body, then offers Repeat and Inspect; APPLY owns Stop, current-Pattern Apply, Apply to Clone, and Cancel. Opening and every draft action preserve Song, History, dirty state, Arrangement, automation, and FT2 cursor. Current Apply is one stopped History transaction. Clone uses the existing independent Pattern plus explicit appended Arrangement-step owner. The result is ordinary Cells; no playback-time generation exists. HARMONY remains a separate read-only browser.
FT2 record	Record row-quantized note-ons by default and, when enabled for the page, release-based note-offs through the selected page's target and persisted Manual, One-column, or Drum-auto layout. CAPTURE offers runtime-only REC FEEL, which keeps the nearest row plus a bounded callback-time offset. MODE keeps MIX directly reachable. Stopped internal REC runs one visible meter-aware count-in bar and starts capture at row zero; REC during Play punches into the Arrangement without restart. External sync refuses stopped REC until acquired Start, then retains the same running punch-in owner. Exact page/lane owners survive cursor moves and boundaries. Shift-rotary column turns are ignored while recorded notes are held; Edit note length does not affect REC.
FT2 edit	A contextual four-page command set only: EDIT has cell edit, blank/skip, erase, and note off; SET has independent 1/1–1/128 LENGTH and 0–32 ADD selectors plus column movement; SIZE has HALF, ROW-, ROW+, and DOUBLE across the complete Pattern; SYS has panic, N00B, help, and a one-level Exit back to normal FT2. Shift-click opens the live mixer without displacing these pages. Populated destructive/copy choices use a modal confirmation with exact cell counts. Normal FT2 SELECT remains available after Exit. It contains no Play/Record/Edit mode duplicates. Manual writes from the selected column, One column uses its C1–C4 anchor, and Drum auto allocates simultaneous hits without moving the cursor.
FT2 N00B	Independent on/off scale filter layered over Play, Record, and Edit on a melodic page, using the scale selected on Player. Accepted notes keep their pitch; rejected notes stay silent. Play remains non-writing, while Record/Edit write only accepted notes. Toggling N00B is immediate, opens no screen, preserves the current mode, and moving to Drums turns only the filter off.
Live Patterns	Browse four existing Patterns at a time without launch; use Shift-rotary or Left/Right for the tracker lane; distinguish selection/current/queue; replace or cancel Pattern/bar-boundary queues; deliberate immediate launch and current retrigger; capture only successful activations with Append/Replace confirmation; transient four-lane mute, velocity, gate, and transpose; literal Stop, Panic, keyboard equivalents, and preserved FT2 cursor. In external Pattern sync, incoming Start launches the selected shaped Pattern at row 1 and later launch/retrigger boundaries retain the external owner.
Loop Mix	Pattern-owned fourth musician-facing FT2 page; browse inbox WAVs with the ordinary rotary and select one of four private WAV slots with Shift-rotary, Left/Right, or the existing slot buttons, all without launch; queue independent launch/stop at the next Pattern-local bar; replace/cancel commands; show play/stop/queue/mute/missing/fault states; smoothed level and bipolar filter; import/attach/remove only the FT2 cursor Pattern's selected slot; isolate faults; shared library overlay and align child.
FT2 cell edit	Transactional route/channel/instrument, banks, note, gate, velocity, per-note program, independent 1/96-row timing, single command type/parameter, clear-field, save/cancel, and panic actions. Four-button encoder page selection remains available.
Tracker files	Select saved Project; load; preview/stop; save with overwrite confirmation; create a confirmed blank Project; save a numbered non-overwriting copy; delete with repeat confirmation; rename; open the Pattern child; back/cancel and panic.
Pattern tools	New, clone, clear, copy, paste-new, paste-over, or clean unused Patterns; transpose melodic pages by semitone or octave; open reusable drum patterns.
Drum patterns	Filter 72 bundled plus user rhythms by genre, meter, and 2/4/8-bar size; browse the filtered list with the ordinary rotary and change genre with Shift-rotary or the existing Genre−/Genre+ actions; load into the percussion page; save that page separately; confirmed deletion of user saves only. Empty Patterns may adopt the selected shape, while existing melody blocks resizing.
FT2 arrange	Select an Arrangement step; append/insert the current Pattern; duplicate/remove a step; move it earlier/later; jump to its Pattern; or play from it. FORM opens the non-writing A A B A assistant with the selected Pattern as A and no implicit B. B-/B+ explicitly choose an existing Pattern ID. The assistant keeps four pages: FORM, APPLY with Stop/Append/Replace/Cancel, one empty page, and canonical SYS. Append and Replace validate before changing only the order; dirty Replace uses the existing unsaved-Project guard. Cancel and every refusal preserve Pattern data, History, dirty state, transport, and FT2 cursor/context.
Pattern setup	Choose 3/4 or 4/4 and pattern length; CONFIRM performs NEW/CLEAR with that shape, KEEP performs the same operation with the current Pattern's shape, and Exit cancels.
Tracks page manager	Select pages with the encoder and change the selected column with Shift-rotary or the existing Column−/Column+ actions; add a four-lane page; edit target, channel, bank, program, and the per-page Manual/One-column/Drum-auto entry layout; confirm all changes; or exit and restore the original Project.
Target/channel field mode	Previous/next choice, confirm field, cancel field. Encoder turn/press and menu items share these operations.
Audio recorder	Select and name a track (NAME accepts the current value by rotary click and allows optional keyboard editing); assign an exact discovered JACK source; arm/disarm one, every resolved track, or all; refresh source discovery without rewriting preferences; start/stop one synchronized take; inspect elapsed time, active count, selected-track activity, drop/xrun/high-water status, final basename or failure; Exit to Home and panic. The native body uses a selection-following five-track window and reserves its final two rows for integrity/recovery and the result. Healthy tracks omit ready; only MISSING is called out.
18-channel Levels	Show all 18 recording inputs simultaneously as three groups of six fixed nine-LED dBFS meters. Encoder, Left/Right, j/k, or pointer selects without scrolling; encoder click/Enter/Space arms the selected channel. Visible TAKE, CHANNEL, and SYS pages provide setup, record, literal Stop, reset, previous/next, arm, refresh, Panic, Help, and Exit. At native 40×13 it omits controller rows but keeps shared row 13; compact geometry falls back rather than cropping.
FX rack/editor	Show the owning Project and its NEW/SAVED/DIRTY state; choose source, AUX 1, AUX 2, AUX 3, drum, or master with Shift-rotary or the existing forward TARGET action; select the typed + INSERT EFFECT row with the ordinary rotary; add/select/remove/bypass/reorder bounded effects; and edit every parameter using explicit compact labels and type-aware values. Shift-rotary is inert in the type and parameter editors. The native 40×13 EQ is a dedicated fullscreen logarithmic graph with four one-cell band markers and all bypass, band, low-cut, and output fields; other processors retain the 2×4 physical-control grid. The rack and parameter fields keep the current selection visible. Aux time effects are forced wet. An active graph publishes FX changes only with stopped transport and recording; a disabled graph accepts Project-only edits without touching audio.
MASTER STRIP	Compact fixed-order INPUT, TONE, GLUE, COLOR, IMAGE, and LOUD/CEIL front page with one selected-section value and bounded mastering meters; DETAIL opens only that section's advanced values. In DETAIL, the ordinary rotary browses that section's parameters and Shift-rotary changes section through the existing previous/next order. Optional sections have smoothed bypass; A/B retains fixed latency and true-peak protection; RESET I clears integrated loudness. Playback allows numerical audition without a topology rebuild, final recording rejects edits, and a disabled graph changes only Project state. Back preserves caller, page, FX/tracker selection, and cursor.
Routing	Transactional rotary editor for controller input/role, every repeated performance input plus an explicit add row, external MIDI enable/output/profile, controller clock enable/output, exclusive SYNC internal/external owner, exact SYNC IN, SYNC POS Arrangement/Pattern Start, and audio output. Browsing never writes or transmits. Field confirmation validates the whole candidate, rejects duplicate or ambiguous inputs, backs up and atomically saves it, safely activates live MIDI input changes while transport is stopped, refreshes discovery, and rolls back on failure. All controller layouts reach the same scrolling rows through the canonical menu dispatcher. Interface availability and unverified downstream DIN profile are separate states.
Help	Compact Markdown user help, temporary LAN web help when port 80 is available, section links selected by the master encoder, keyboard page scrolling, top, and return to the previous screen.
Global/safety	Stop MIDI playback, tracker transport, recorder, managed engine, and owned notes; All Notes Off; cancel or leave the current controller level. Application exit remains computer-keyboard-only. Help is also reachable from ? or F1. Process termination remains limited to the engine owned by SHR-DAW.

The complete final screen × page × item mapping is maintained below. The table uses expanded action names where that is clearer; the compact visible label is shown in parentheses when it differs materially. src/navigation.rs is the executable canonical copy: labels and dispatch actions are one definition. A unit test builds the union of every normal and contextual menu and checks every action in this screen-specific inventory for controller reachability. Top-level Home entries are reached by the master rotary rather than duplicated on child command pages.

Shared status row and master overlays#

Every working screen except Home and the native 40×13 fullscreen EQ reserves the final row. Native 18-channel Levels is a separate exception only to the controller rows: it still reserves that shared row while using rows 1–12 for meters, labels, and visible right-side commands. Its first status cell is the transport state: steady green > for play, steady white ■ for stop, steady white ‖ for pause, or red ● for record. Record alone pulses between normal and bright red; the circle never disappears. One space leaves exactly 38 cells for current useful status. A configured CPU temperature remains right-aligned as CPU 52°C whenever useful state or a fault fits beside it. Longer actionable text temporarily owns all 38 cells so its consequence and recovery are not lost; the temperature returns when that message clears. Text is fitted after reserving ownership, consequence, and recovery. Routine success lasts at most 1.5 seconds; a retained-work, rollback, or All Notes Off consequence lasts at most three seconds. Confirmations and faults remain until resolved, while active recording always names its owner and merges any recording fault. With no configured temperature and no message, an idle transport cell alone is the normal healthy state. Screen bodies do not add generic gray status lines, and the two controller rows sit immediately above the shared status row. Working-screen frame cleanup stops above that row; only the shared renderer clears and replaces it. The fullscreen EQ deliberately owns all thirteen rows: its final row is the 50 Hz–20 kHz logarithmic axis, temporarily replaced only by a useful range or fault message. It has no visible controller rows. A compact terminal falls back to the ordinary FX editor and shared status layout. Levels likewise falls back to its compact ordinary layout below 40×13.

Horizontal meters use the same circular LED language everywhere. Every cell is ●: dark gray when unlit, one consistent green at a safe active level, then yellow and red only when their documented thresholds are active. A held peak uses a brighter version of its threshold colour rather than a line or square.

An overlay is transient state above its caller, not another Screen and not a second Project/engine owner. Its central state records identity, caller, title, canonical launcher, selection/scroll, active field snapshot, typed draft, and the caller's controller-page state. At 40×13 an ordinary overlay's outer rectangle is exactly x=1, y=1, width=38, height=11; its bordered inner content is x=2, y=2, width=36, height=9. ROUTE reserves the two controller rows and therefore uses outer 38×9 and inner 36×7 rectangles at the same origin. Every form leaves the final shared status row untouched.

While an ordinary navigation overlay is open, the launcher remains on its bottom border near the original physical item position and with an active highlight. Loop Browser keeps STOP at position 5 and PLAY preview at position 6, and the Song overlay keeps TAP at position 8. ROUTE is the deliberate exception: its window ends above the canonical controller page/action rows, where the ROUTE page maps APPLY to position 5 and CANCEL to position 8 through the same table used for rendering and physical dispatch. All unrelated caller commands are hidden and silent. No overlay occupies or clears the shared status row. There is no controller-strip Back button. The rotary and Up/Down browse; rotary click and Enter select or confirm. Back/Esc cancels an active field first, then cancels the overlay draft and closes, before a later Back can leave the caller. Four-button page-selection state and every layout's previous page are restored deterministically.

FT2 demonstrates eight caller-specific adapters: PAGE lists only the Pattern's musician-facing pages, preserves the selected column, and links to Tracks; PATTERN navigates the Project's existing Pattern owners and links to Pattern/Project tools; SONG navigates Arrangement steps and links to its detailed editors; ROUTE applies valid active-field choices to the Project and live route, while Cancel restores the opening route snapshot; Edit LENGTH chooses 1/1 through 1/128 and ADD chooses 0 through 32 rows; Tracks ENTRY chooses Manual, One column C1–C4, Drum auto, and the per-page automatic Note Off setting; Pattern Setup LNGTH chooses every value from 1 through 32 plus 48, 64, 96, 128, 192, and 256. Edit SIZE is not a navigation overlay: its canonical action row performs HALF, ROW-, ROW+, and DOUBLE on the complete Pattern. Populated HALF, ROW-, and DOUBLE operations switch to one modal choice page; controller items, rotary selection, keyboard, and mouse all share its confirmation dispatcher. The prompt and both controller rows remain above the shared status row. Loop Mix preserves slot and command-page context while the FT2 cursor remains on one Pattern, then resets that context safely on Pattern or Project change. Its LIBRARY launcher uses the overlay for one combined inbox/private browser. Selection is silent until PLAY explicitly previews it; changing selection, STOP, Back, closing the browser, or leaving the browser stops that preview. Activating an inbox selection imports and loads it, while activating a private/current/saved selection attaches and loads it. A failed preview or import keeps the selection and caller context for retry. MTR's FX launcher reuses the same rendering, input, toggle, and return layer.

Input model#

Shift state comes either from a configured MIDI modifier or from a dedicated alternate encoder CC produced only by the controller's hardware Shift layer. The latter is the MiniLab mkII path: Arturia documents that Shift changes the CC of encoders 1 and 9, so SHR does not wait for an independent Shift packet that the controller does not expose. Releasing Shift restores the ordinary rotary CC in hardware. The following table is the current secondary-navigation contract:

Screen/context	Ordinary rotary	Shift+rotary	Existing action reused
Presets	Preset in current catalog	Previous/next engine catalog, wrapping in engine order	PreviousEngine/NextEngine; same behavior as [/] and the header halves
FT2 Play/REC/Edit grid	Row	Previous/next column across page boundaries	Existing page-spanning tracker-column move; ignored in REC while a recorded note is held
Tracks browse	Page	Previous/next column, bounded within the page	Column−/Column+
Live Patterns	Pattern browse, or the active shape value	Previous/next tracker lane	Left/Right and PreviousTrack/NextTrack
Loop Mix	Inbox WAV browse	Previous/next loop slot, wrapping	Slot−/Slot+ and Left/Right
Drum patterns	Filtered rhythm list	Previous/next genre, using existing wrap	Genre−/Genre+
FX rack, including an empty rack	Effect row	Previous/next source/AUX/drum/master target	TARGET's existing forward order plus its exact reverse
MASTER STRIP detail	Parameter in the current section	Previous/next section, wrapping	The front-page section order; its existing section change resets parameter selection to the first value

Shift+rotary is intentionally inert on Home, Playback, FT2 PARAM, Ideas, Help, Project files, Pattern tools, Arrangement, Pattern setup, FT2 Tools, Loop Align, Audio Recorder, Levels, the FX type and parameter editors, the MASTER STRIP front page, MTR, and Routing because each has no separate reversible adjacent navigation axis beyond the ordinary rotary. It is also inert in FT2 cell edit, Tracks field edit, overlays, confirmations, naming, and other transient editors: their one browse/edit axis and caller boundary stay exclusive. Four-button page-select mode remains an explicit exception in which the rotary continues to select controller pages while Shift is held.

• Eight buttons: four direct page selectors plus four item buttons.
• Five buttons: one page-cycle button plus four item buttons.
• Four buttons: four item buttons; encoder press enters/leaves page-selection mode and encoder turn changes pages while that mode is visible.
• Outside four-button page-selection mode, encoder turns retain list, row, and field adjustment. On the normal FT2 grid, an ordinary turn always moves rows; holding the configured encoder Shift while turning moves columns across page boundaries. Encoder press retains the existing select/confirm action on eight- and five-button layouts. Menu slots do not duplicate those master rotary selection actions.
• An open overlay always gives the encoder to overlay browsing/editing, so a four-button controller cannot become stranded in page-selection mode.
• Entering any screen or contextual mode selects its page 1, preventing a page choice from a previous visit from becoming the new screen's hidden meaning.
• Page 1 holds the primary screen workflow; for FT2 normal mode it is PLAY. On every workspace, child screen, and contextual editor, EXIT is page 4/item 4 and returns exactly one level. Home is the root and has no MIDI Exit; quitting remains keyboard-only.
• Physical positions 5–8 are semantic anchors: STOP/PANIC, PLAY/LOAD/PREVIEW, REC/capture, and TAP respectively when those actions are present. Empty anchors remain contextual rather than becoming unconditional global commands. The page-4/item-4 Exit flow remains at the right edge when TAP is absent.
• When a configured controller is offline, lacks a matching reviewed profile, or has an incomplete learned encoder, Home initially selects MIDI Learn and gives the reason. A learned master encoder with turn and click is usable even without optional pads. Home itself neither learns nor transmits. During Learn, master turn/click packets cannot browse or skip capture roles; only explicit keyboard skip/back can move past an unlearned optional control. Learn renders exactly two action-first rows total and no shared status row.
• Help is a child screen. It tries to show the same help at http://<LAN-IP>/help while open. The master encoder moves one help row at a time. Encoder press follows a highlighted internal section link on eight- and five-button layouts; four-button layouts use OPS OPEN because encoder press is reserved for page selection. The compact help text uses a stable 38-column width so link targets and rendered rows remain identical.
• Target/channel fields use encoder press to confirm on eight- and five-button layouts. Four-button layouts use the visible OPS CONFIRM item; SYS EXIT cancels the field on every layout and restores that field's complete target/engine/instrument/output/channel snapshot without reverting unrelated Tracks edits.
• Empty items and pages are not drawn, are silent when pressed, and are skipped by page cycling. The interface exposes working actions only.
• Physical command pages never contain PageUp/PageDown. Keyboard PageUp/PageDown change order while preserving page/lane/column and retaining the row unless a shorter destination Pattern requires clamping. Pattern and Song overlays follow the same rule; the rotary continues ordinary one-step list and row movement.
• Every genuine rotary/Up/Down browse list wraps first-to-last and last-to-first, including Home, file/library lists, Arrangement, tracker browse cursors, recorder/meter/FX lists, overlays, Routing rows, and enumerated field choices. Empty lists are inert, one-item lists remain stable, stale selections clamp before wrapping, and scroll offsets follow the selected row. Bounded numeric editing does not inherit list wrapping.
• Functional sentinels are typed logical entries, not inferred from their visual text. Blank/Skip, Off, Clear, Default/AUTO, and FX + INSERT EFFECT therefore remain distinct and reachable exactly once; decorative blank lines remain non-selectable.
• The rendered controller strip is centered and capped at 40 columns. Labels and brackets use their natural width instead of expanding with the terminal.
• Command notes and CCs may be qualified by MIDI channel. The MiniLab factory Arturia/DAW pads are notes 36–43 on channel 10: 36–39 select pages 1–4 and 40–43 activate items 1–4. Matching pressure and releases are consumed, while the same notes on channel 1 remain keyboard input. User 1's captured channel-1 pads cannot safely be commands because they collide with the keys.

Complete controller map#

Blank physical positions and wholly empty pages are omitted.

Screen/context	Page	Item 1	Item 2	Item 3	Item 4
Presets	Ops	First	Load	Last	—
Presets	Sys	Panic	Help	—	Exit
MTR	Ops	Source−	Source+	Level−	Level+
MTR	Mix	Mute or Input MON ON/OFF	—	Final rec/stop	Reset holds
MTR	Nav	FX overlay	MASTER STRIP	Input stereo/dual mono	Input LEVEL/PAN 1/PAN 2
MTR	Sys	Panic	—	Help	Exit
Playback	Play	Stop take/arp	Play take/arp	Record MIDI	Tap tempo
Playback	Sound	Reset controls	Save sound	N00B on/off	Sounds
Playback SAVE	Save	Overwrite	Save new	—	Cancel
Playback	Sys	Panic	FX	Help	Exit
FX rack	Ops	Add	Delete	Edit type	Parameters
FX rack	Order	Up	Down	Bypass	MASTER STRIP
FX rack	Route	Target	Send−	Send+	Point
FX rack	Sys	Panic	Return	Help	Exit
FX rack empty	Ops	Add	—	—	—
FX rack empty	Route	Target	Send−	Send+	Point
FX rack empty	Sys	Panic	Return	Help	Exit
FX type	Type	Type−	Type+	OK	Cancel
FX editor	State	Bypass	—	—	—
FX editor	Sys	Panic	—	Help	Exit
MASTER STRIP	Section	Previous	Next	Detail	Bypass
MASTER STRIP	Compare	A/B	Reset LUFS-I	—	—
MASTER STRIP	Sys	Panic	—	Help	Exit
Strip detail	Param	Previous	Next	Value−	Value+
Strip detail	State	Bypass	A/B	Reset LUFS-I	—
Strip detail	Sys	Panic	—	Help	Exit
Ideas	Play	Inspect	Play	Record	Delete
Ideas	File	Save	Load	First	Last
Ideas	Sys	Panic	—	Help	Exit
Help	Ops	Open link	Top	—	—
Help	Sys	Panic	—	—	Exit
FT2	Play	Cell edit	Play	Record	Edit
FT2	Select	Page overlay	Pattern overlay	Song overlay	Route overlay
FT2	Sound	Parameter view	Mixer	Automation	Metronome
FT2 AUTO	Rec	Arm/safe	Add point	Delete point	New lane
FT2 AUTO	Point	Previous	Next	Value−	Value+
FT2 AUTO	Lane	Target−	Target+	Curve meaning	Clear/confirm
FT2 AUTO	Sys	Panic	—	Help	Exit
FT2	Sys	Panic	N00B	Help	Exit
FT2 PARAM	Sound	Reset controls	Save sound	N00B on/off	—
FT2 PARAM SAVE	Save	Overwrite	Save new	—	Cancel
FT2 PARAM	Sys	Panic	—	Help	Exit
FT2 tools	Ops	Arrange	Live Patterns	FX	Loop Mix
FT2 tools	Clip	Copy lane (COPY L)	Paste lane (PASTE L)	Copy page (COPY PG)	Paste page (PSTE PG)
FT2 tools	Page	Mute page (MUTE PG)	Mute lane (MUTE)	Harmony browser	History
FT2 HARMONY	Overlay	—	—	Harmony/close	Exit
FT2 HISTORY	History	Undo	Redo	Snapshot	Recall
FT2 HISTORY	Rhythm	Feel	Groove	Cycle	Generator (GEN)
FT2 HISTORY	Sys	Panic	Help	—	Exit
FT2 FEEL	Feel	Division	Amount−	Amount+	Apply
FT2 FEEL	Sys	Panic	Help	—	Exit/cancel
FT2 GROOVE	Shape	Preset	Scope	Strength−	Strength+
FT2 GROOVE	Apply	Apply	—	—	—
FT2 GROOVE	Sys	Panic	Help	—	Exit/cancel
FT2 CYCLE	Cycle	Length−	Length+	Rate	Direction
FT2 CYCLE	Apply	Stop	Apply	Reset	Cancel
FT2 CYCLE	Sys	Panic	Help	—	Exit/cancel
FT2 GENERATOR	Shape	Tool	Length−	Length+	Amount
FT2 GENERATOR	Detail	Offset/phase/depth−	Offset/phase/depth+	Context control or Roll shape	Collision/clone policy
FT2 GENERATOR	Value	Value−	Value+	Repeat	Inspect
FT2 GENERATOR	Apply	Stop	Apply	Apply to Clone	Cancel
FT2 tools	Sys	Panic	Help	—	Exit
Live Patterns	Launch	Launch	Cancel queue	Retrigger current	Immediate
Live Patterns	Timing	Stop	Pattern boundary	Bar boundary	Capture
Live Patterns	Shape	Mute	Velocity	Gate	Transpose
Live Patterns	Sys	Panic	Append capture	Replace Arrangement	Exit
Loop Mix	Play	Stop slot	Launch slot	Previous slot	Next slot
Loop Mix	Mix	Level−	Level+	Mute	Remove
Loop Mix	Filter	Filter−	Filter+	Cancel queue	Align
Loop Mix	Sys	Panic	Import	Library	Exit
FT2 loop align	Ops	Auto	Bar−	Bar+	Done
FT2 loop align	Sys	Panic	Help	—	Exit
FT2 record	Mode	—	Play	Record/stop	Edit
FT2 record	Capture	FEEL	—	—	—
FT2 record	Sys	Panic	N00B	Help	Exit
FT2 edit	Edit	Cell edit	Blank/skip	Erase	N-off
FT2 edit	Set	Note-length overlay	ADD 0–32 overlay	Column−	Column+
FT2 edit	Size	Half	Row-	Row+	Double
FT2 SIZE choice	Choose	Top/Copy/Confirm	Bottom/Empty	Cancel	—
FT2 edit	Sys	Panic	N00B	Help	Exit edit
FT2 cell edit	Route	Destination	Channel	Instrument	Timing
FT2 cell edit	Sound	Bank MSB	Bank LSB	Cell program	Clear field
FT2 cell edit	Cell	Note	Gate	Velocity	Effect
FT2 cell edit	Done	Panic	Save	Effect parameter	Exit/cancel
Files	Ops	Save	Load	Delete	MIDI import
Files	Project	New Project	Save As	Name/rename	Pattern tools
Files	Preview	—	Preview/stop	—	—
Files	Sys	Panic	—	Help	Exit
Routing-default prompt	Default	Confirm	Cancel	—	—
Routing-default prompt	Sys	Panic	—	—	Exit/cancel
Pattern tools	Ops	Blank new (BLANK)	Clone	Clear	Drum patterns
Pattern tools	Clip	Copy	Paste as new (PASTE+)	Paste over (OVER)	Clean unused (CLEAN)
Pattern tools	Trans	Octave− (OCT-)	Semitone− (NOTE-)	Semitone+ (NOTE+)	Octave+ (OCT+)
Pattern tools	Sys	Panic	—	Help	Exit
Drum patterns	Ops	Save	Load	Delete user	—
Drum patterns	Filter	Genre−	Genre+	Meter	Size
Drum patterns	Move	First	Last	—	—
Drum patterns	Sys	Panic	—	Help	Exit
Arrange	Ops	Jump	Play	Append	Insert
Arrange	Step	Up	Down	Repeat	Remove
Arrange	Form	A A B A assistant (AABA)	—	—	—
Arrange	Sys	Panic	Help	—	Exit
A A B A draft	Form	B Pattern−	B Pattern+	—	—
A A B A draft	Apply	Stop	Append	Replace	Cancel
A A B A draft	Sys	Panic	Help	—	Exit/cancel
Pattern setup	Ops	3/4	4/4	Length (LNGTH)	—
Pattern setup	Apply	Confirm	Keep	—	—
Pattern setup	Sys	Panic	—	Help	Exit/cancel
Tracks	Ops	Add four lanes	Target	Channel	Done
Tracks	Column	Column−	Column+	Program−	Program+
Tracks	Bank	MSB−	MSB+	LSB−	LSB+
Tracks	Sys	Panic	Entry layout	Help	Exit/cancel
Target/channel editor	Ops	Confirm	—	—	—
Target/channel editor	Sys	Panic	—	Help	Exit/cancel
Audio recorder	Record	Open 18-channel Levels	—	Record/toggle	Arm selected
Audio recorder	Track	Previous track	Next track	Assign source	Name track
Audio recorder	Setup	Arm all resolved	Disarm all	Refresh sources	—
Audio recorder	Sys	Panic	—	Help	Exit
18-channel Levels	Take	Stop	Recorder setup	Record/toggle	Reset holds
18-channel Levels	Channel	Previous	Next	Arm selected	Refresh sources
18-channel Levels	Sys	Stop	Panic	Help	Exit
Routing	Edit	Previous row/value	Next row/value	Edit/OK	Cancel
Routing	Sys	Panic	Help	—	Exit

Routing editor contract#

Routing opens in browse mode with a highlighted row. Rotary/Up/Down moves one row and wraps; click/Enter opens a detached field draft; rotary/Up/Down changes only that draft; click/Enter validates and confirms; Back/Esc restores the original field. Back/Esc from browse returns Home. Re-entry always starts with clean browse state.

Confirmation validates the complete runtime and controller candidate, creates non-overwriting backups, atomically replaces both files, releases source-owned notes/controller state, replaces SHR-owned MIDI inputs without layering, and refreshes live discovery. Failure restores the old files and runtime route. An audio-output change is saved for the next managed engine start and reported as AUDIO NEXT START instead of being described as hot/live. Controller-clock enable/output changes likewise report CLOCK NEXT START; live MIDI input role/ source changes activate immediately. Selecting or confirming a MIDI output uses discovery only; it never opens an output as a probe and never transmits.

The MIDI row shows the selected stable ALSA interface identity with an OFFLINE or AMBIG suffix only when discovery cannot resolve it. A known Device profile shows its configured model without claiming live detection; raw external MIDI remains UNVERIFIED. AudioBox plus D-50 is therefore the normal concise presentation, while SHR never claims that the D-50 itself was detected.

FX editor and 40×13 text contract#

Non-EQ processors use a spatial 2×4 grid matching the eight physical rotary positions. Every control has its title above its value; the selected pair is highlighted yellow while browsing and green while editing. Titles use clear words such as RATE, RATIO, ATTACK, and FEEDBACK, while values retain type-aware units.

At 40×13, EQ instead fills the display. Its 20-column plot maps 50 Hz through 20 kHz logarithmically and draws one ─ for each low, low-mid, high-mid, and high band. Gain markers snap visually to the nearest labelled row from −18 to +18 dB; displayed and editable gain values retain 0.5 dB precision. The master rotary browses bypass, each band frequency and gain, low-cut state and frequency, and output trim. Yellow means selected, green means editing, and a bypassed EQ is dim. Knobs 1–4 remain logarithmic band frequencies and knobs 5–8 their half-decibel gains. Low cut is never misrepresented as knob 1.

All working-screen single-line regions have explicit terminal-cell budgets. Static operational labels are written to fit; unpredictable device/file/user names pass through cell-aware fitting; fixed label/value rows reserve the selection marker and right-side state. Help remains the intentional wrapped, scrollable prose surface. The controller footer, DEV/REL badge, Help, and Exit areas retain their assigned cells at 40×13.

FT2 cell editor inventory and mapping#

A cell contains note, optional velocity, optional per-note program, optional gate, independent signed timing, deterministic probability, one loop-aware condition, and one command: none, cut, delay, retrigger, or tempo. Project format stores all of these fields directly inside each FT2 Pattern.

Page	Item 1	Item 2	Item 3	Item 4
Route	Destination	Channel	Instrument	Timing
Sound	Bank MSB	Bank LSB	Cell program	Clear selected field
Cell	Note	Gate	Velocity	Effect type
Done	Panic	Save	Effect parameter	Exit/cancel

CHANCE, CONDITION, COND A, and COND B follow Timing in the cell editor's rotary field sequence. They deliberately do not add a fifth direct-action page: turn while inactive to select one, press to edit, and turn to change it. Normal FT2 SOUND uses item 4 for the next-boundary FILL latch; the displaced CLICK action remains on FT2 Tools SYS item 3. Keyboard f shares FILL.

The timing spacer uses < for early, > for late, and blank for on-grid. The command marker still uses C, D, R, or T. The data model supports one command plus timing per cell. Gate is 1–100% of a row or inherited; delayed notes and retrigger pulses remain bounded. Program is routed before the shifted note on the same exact target/channel.

Physical MIDI notes and CCs remain configuration. Profiles name only PAD 1 through PAD 8; the active screen gives pads 1–4 their page positions and pads 5–8 their contextual STOP/PANIC, PLAY/LOAD/PREVIEW, capture, and TAP meanings. Older semantic mappings still decode to those physical positions without changing note numbers.

Parameters, relative turns, and extension points#

Menu navigation is discrete. Rotary 1 supplies relative navigation and its click selects. Rotaries 2–16 supply up to fifteen continuous parameter slots; each backend or editor supplies its own parameter table for those slots. The MiniLab mkII discards incoming rotary position and carries SHR's current parameter by signed steps across preset load, reset, mixer-bank changes, and linked controls. Rotary 9's click is learned and persisted; the verified synthv1 0.9.29 indices/ranges and green/yellow/red ±0.03 indicators are unchanged. Existing models retain their 12-position synth tables and use positions 13–15 for Project AUX 1, AUX 2, and AUX 3 sends on Player and FT2 PARAM. These Project controls are consumed before backend forwarding. Moj Sint Dual Filter instead uses all 15 parameter rotaries for two filter blocks, STRUCTURE, filter ADSR, and amp ADSR.

The master rotary always remains SHR navigation. Rotary 9's learned click is also stored as the optional synth.press_cc or synth.press_note binding. On Dual Filter it toggles only CORE: INDUSTRIAL and CORE: COUNTER; release is consumed, current rotary values are preserved, and the visible core state is saved with the preset.

All Shift-rotary secondary navigation uses either the profile/configured MIDI modifier or the learned hardware Shift-layer CC plus the same semantic actions as visible or keyboard navigation. The MiniLab mkII alternate CC is also relative. Shift Learn names and proves both directions as separate gestures: Shift plus repeated left packets, release, then Shift plus repeated right packets on the same CC, followed by release. Its direction encoding is learned independently and may oppose the ordinary axis. For each performance rotary, Learn requires repeated left-direction packets followed by repeated right-direction packets on the same channel and CC. Positional or wrong-direction input is rejected and cannot resume on that role until explicit retry or skip.

Action and the empty menu slots remain extension points. Future features are not shown on the hardware menu until they actually dispatch a working action.

Back to detailed guides

Every device in this guide is optional. Start with the equipment you already have and add one connection at a time.

Smallest setup#

A Raspberry Pi, terminal, and audio output are enough to use software instruments and the pattern editor. The terminal can be local or connected over SSH. Audio can use any Pi, HDMI, or USB output exposed through JACK.

Add a MIDI keyboard when you want live velocity and chord input. Add a physical control surface when you want to operate SHR-DAW without a computer keyboard or mouse.

Expanded setup#

Physical SHR-DAW connections: controller, Raspberry Pi, display, USB audio/MIDI interface, chained MIDI instruments, mixer, monitors, and headphones (shown earlier)

For a full-width browser view of the same approved specification, open the standalone connection diagram. It uses the tracked image directly and does not redraw devices, ports, or cables.

The main paths are:

• controller or computer keyboard → SHR-DAW;
• SHR-DAW → synthv1, Yoshimi, FluidSynth, or Moj Sint → JACK audio output;
• tracker pages → optional external MIDI instruments;
• optional audio inputs → direct monitoring and/or synchronized stem recording.

The diagram is an example, not a shopping list. The original test rig used an Arturia MiniLab 3, a PreSonus AudioBox USB 96, and a Casio Casiotone MT-240. Those devices proved the workflow, but SHR-DAW is not designed around them.

MIDI input#

SHR-DAW treats a control surface and performance keyboards as separate roles. The controller supplies menu buttons, the main encoder, pads, and mapped synth controls. Every configured performance input bypasses those mappings, so a keyboard note or CC cannot accidentally invoke a menu command. The controller can either pass its unmatched musical messages (the compatible default for one combined device) or be explicitly control-only.

If both roles resolve to the same exact ALSA port, SHR opens it once and classifies its messages as the established combined-device path. If they resolve to different ports, SHR opens separate connections. Repeated performance inputs are simultaneous sources; repeated legacy midi.input entries remain ordered controller fallbacks. Missing inputs fail independently, and computer-keyboard control remains available.

Source identity remains attached to active notes. Two keyboards may hold the same channel/note without either Note Off releasing the other's note. Route changes, source loss, panic, stop, and shutdown release the affected ownership; All Notes Off, All Sound Off, and sustain are also isolated per source/channel.

Do not also connect the controller directly to the same synth with a desktop MIDI patching tool. Two paths can cause doubled notes. Use shr-setup or the configuration files to choose the route in one place.

A USB audio/MIDI interface may be full-duplex: its MIDI input can be a performance source while its MIDI output remains an FT2 destination. Input and external_midi.output are independent directions.

Routing uses one stable ALSA identity policy everywhere. A live RtMidi name such as AudioBox USB 96:AudioBox USB 96 MIDI 1 32:0 is persisted as AudioBox USB 96:AudioBox USB 96 MIDI 1; only the volatile trailing numeric address is removed. The older whitespace form is accepted only when it resolves uniquely. Partial or ambiguous matches stay offline rather than selecting an arbitrary port.

Some distributions enable a standalone FluidSynth daemon or amidiminder, which connects hardware and application MIDI ports broadly. Accept the recommended exclusive-routing cleanup in shr-setup; SHR can still launch its own configured FluidSynth when selected.

Software instruments#

SHR-DAW supports synthv1, Yoshimi, FluidSynth, Moj Sint, and SHR Sampler as separately installed programs. Only one SHR-DAW-managed software-engine process runs at a time. synthv1 and Yoshimi provide one current preset; one FluidSynth process may play several SoundFont presets on different MIDI channels while retaining one stereo JACK source. Moj Sint contributes exactly out_l and out_r plus one ALSA Sequencer input; it creates no JACK connections itself. The standalone SHR Sampler likewise contributes the configured out_l and out_r plus one ALSA Sequencer input and creates no JACK connections itself. The standalone Software Synth workspace keeps its sound after leaving Presets or Playback. FT2 uses the engine/instrument pair saved by its current Pattern; if the Project is genuinely new, empty, unsaved, and otherwise still at its defaults, entering FT2 assigns the current standalone selection to page 1 and transfers ownership without restarting it. With no standalone instrument, FT2 loads the first available synthv1 preset. A different explicit FT2 backend replaces the standalone engine when needed. Global panic, replacement, and application shutdown stop only a process SHR-DAW owns.

Panic sends sustain off, All Notes Off, and All Sound Off on all 16 channels. For synthv1 0.9.29 those 48 messages are spaced by 100 microseconds because that version handles sequencer control traffic on its audio path; no safety message is omitted. Normal synthv1 shutdown then sends a targeted JACK SaveAndQuit request to the exact managed client before falling back to termination of the owned child process. The request is never broadcast and does not target an unowned synth.

Each engine has a configured MIDI input and JACK audio output. See Configuration and routing for the settings.

SHR considers a managed engine ready only after it resolves one unambiguous stereo JACK output pair—not merely a MIDI port. It accepts the exact configured client or one unique prefixed instance, including Yoshimi's generated prefixed client name. Missing, ambiguous, or non-stereo output and every failed JACK connection are reported instead of silently accepted.

By default, the active engine connects directly to the configured playback pair. With the opt-in owned effects graph enabled, that same one engine instead passes through source inserts, three aux returns, the master rack, and final meter. Activation is transactional and restores the direct path on failure. The active Pattern's complete internally summed four-slot Loop Mix joins the graph as one of its three exact stereo sources and is removed from direct playback for the duration, preventing a doubled path. Pattern changes replace the renderer content without adding ports or connections. The raw multitrack recorder remains separate.

External MIDI instruments#

Each tracker page can use its own MIDI output, with four independent column channels/banks/programs. Several pages can play several hardware instruments at the same time. All channels 1–16 and programs 0–127 remain raw-editable without a device profile. A page can instead store a software engine and one of that engine's instruments. An AUTO first page may deliberately adopt the current standalone selection when FT2 opens; an explicit page never does.

Portable AUTO pages save no output or channel and follow the machine default. Explicit pages remember their exact port. If it is disconnected, the page shows OFFLINE and does not silently send to another port. Its notes and preference are kept; reconnecting it makes the original mapping usable on the next play without rewriting the Project.

Named sound lists for supported external instruments come from optional MIDI device profiles. Profiles are convenience metadata, not permission or detection. Instruments without one still expose the normal MIDI programs 1–128 (stored/sent as values 0–127).

ALSA can resolve an AudioBox MIDI output port, but a one-way DIN output cannot report whether the downstream Roland D-50 is connected or powered. Routing therefore shows the interface availability and the configured device profile separately. A resolved AudioBox and configured D-50 need no healthy suffix; an unresolved interface adds OFFLINE or AMBIG, while raw external MIDI adds UNVERIFIED. It never says D-50 connected. SHR-DAW does not probe downstream DIN hardware. Advanced users may construct arbitrary experimental channel/program chains behind one configured output.

Audio output and recording#

The setup wizard selects the left and right JACK playback ports and can retain the older left/right recording pair. The recorder screen and repeated capture.track entries configure any larger set of exact capture sources.

When an audio interface has direct monitoring, connect an external instrument to its inputs and use the interface's monitor balance. This mixes the external sound with SHR-DAW software instruments without a second software-monitoring path or its additional CPU work.

Those JACK capture inputs remain available to the raw multitrack recorder. MTR Input MON ON resolves exactly one configured stereo capture pair and can activate the owned final bus without a synth, Loop, or drums. Optional sources attach only when their exact ports exist. The resulting complete limited stereo samples feed both playback and the dedicated 24-bit final-mix recorder. This is not a free-routing mixer and does not add per-interface-channel processing.

Input monitoring starts off. Do not also direct-monitor the same capture pair at the interface unless the doubled path is deliberate: otherwise the two latencies can cause excess level and comb filtering. SHR-DAW refuses a configuration that declares both modes unless explicit confirmation is set. See Final performance bus.

For exact routes and configuration keys, read Configuration and routing. For source assignment, manifests, recovery, and interfaces with any channel count, read Multitrack recording.

Back to detailed guides

Manual home · FT2 and Projects · Loops and effects

All values shown below are deterministic presentation data. The screens are real SHR-DAW renders, but no instrument, MIDI take, recorder, or meter was live while the images were made.

Home#

Home is the navigation root. Its nine labels are centered inside equal 36-cell bars spanning zero-based columns 2–37 on the 40-column display. The block is centered vertically, always leaving the first terminal row empty at the native 40×13 size, and scrolls safely on compact supported terminals. Home's own final line is shown only for active owned playback/recording, a current fault, or the reason MIDI Learn was recommended; routine selection and confirmation messages stay off the menu.

The master rotary browses the current screen content and its press opens or confirms the selection. On the configured MiniLab, pads do not navigate this plain list: the first four select controller-menu pages and the other four invoke that page's items wherever a controller strip is present.

Presets#

Software Synths opens Presets. Turn the main encoder, use the arrow keys, or use the mouse wheel to choose a sound. Hold the configured encoder Shift while turning to move between the synthv1, Yoshimi, FluidSynth, Moj Sint, and SHR Sampler catalogs. Loading replaces the one managed software instrument; it never layers engines. Within the same SHR-DAW sound system, the Drums instrument belongs to its FT2 page and kit route rather than the melodic Presets catalog.

Home keeps MIDI Learn, Routing, and Effects separate. Routing is the rotary browse/edit/confirm/cancel editor; Effects is the existing Project rack. Routing selections wrap, and merely browsing never writes configuration or opens/transmits through a MIDI output. Its live state names the discoverable interface separately from the configured downstream profile: a resolved AudioBox needs no healthy suffix, while an unresolved interface gets OFFLINE or AMBIG; a known D-50 profile does not claim device detection because DIN supplies no presence feedback. If a configured controller is offline, unreviewed, or has an incomplete learned encoder, MIDI Learn is selected first and Home explains why. Keyboard arrows and Enter remain available. A learned turn-and-click encoder is sufficient; optional command buttons may remain unmapped.

Presets and Playback share one Software Synth sound, and leaving them keeps it running for effects and other screens. Global panic, shutdown, replacement, or an explicit different FT2 software route stops only that SHR-owned engine. A genuinely new, empty, unsaved default FT2 Project adopts the current selection on page 1 without restarting it; with no Player instrument, FT2 loads the first available synthv1 preset. Saved or explicitly changed Projects keep their own routes.

OPS — browse and load#

LOAD starts the highlighted sound. FIRST and LAST jump to the ends of the current engine's catalog. Keyboard PageUp/PageDown still move by ten sounds; physical command pads deliberately do not duplicate that coarse scrolling. On the controller, LOAD uses semantic position 6; position 5 remains available for STOP/PANIC where that direct safety action exists.

Change instrument host#

Shift-turn the main rotary to move among synthv1, Yoshimi, FluidSynth, Moj Sint, and SHR Sampler in either direction. Keyboard [/] and clicking the left/right half of the Presets heading remain equivalent. Catalog changes are silent: they only change the list and reset its selection according to the existing catalog contract. LOAD is the sole managed preset start or replacement action.

The Moj Sint catalog has 21 ordered starts: seven Model D sounds, six Six-Op PM sounds, Strange Oscillator, Swarm Warm Pad, Bass Matrix, and five Dual Filter sounds. The list is grouped by model and gives each model one letter plus a two-digit number local to that model: D01, P01, O01, S01, B01, and F01. Opening or switching to Moj Sint selects D01 Full Bass, and typing a model letter jumps to that visible group. Selecting one only browses; LOAD starts it.

SHR Sampler lists strict read-only .shrinst packages. LOAD validates the installed host version and complete package before replacing the current engine. Its missing, incompatible, malformed, timed-out, or failed states stay visible and cannot leave two melodic hosts layered. The public installation's cleared factory package is a neutral starting sound.

SYS — safety and help#

PANIC stops owned playback and notes. HELP opens the local help reader. EXIT returns to Home. MIDI never quits the application; quitting remains computer-keyboard-only from Home.

Playback#

Playback appears after a sound is loaded. At native 40×13 the body shows the held chord and notes, each note's decimal MIDI strike velocity directly beneath it, and the selected backend's 3×5 controls. Synthv1 and the five older Moj models use 12 synthesis controls plus three aux sends; Dual Filter uses all 15 for synthesis. Taller terminals use spare space for a continuous two-row keyboard state. The aligned velocity row helps with gentle/strong control, consistent chord attacks, and bass-plus-chord balance. It is MIDI input data, not an audio loudness meter; controller and instrument response determine the audible result. On the keyboard, red white-key areas are held natural notes and red upper └ marks are held sharps. Parameter colors are relative to the loaded preset: green below the original value, bright yellow near it, and red above it. The Moj Sint uses seven model-specific timbre controls plus Volume in the first two rows and ADSR in the third; synthv1 retains its own names and indices. Read-only managed instruments show Volume at the same physical position. The main encoder press resets only these mapped controls; it does not restart the synth.

PLAY — capture a MIDI take#

PLAY plays or stops the captured take. With no take, it still sends a fresh Start to the configured controller clock so a controller in external-sync arpeggiator mode works with live keys. RECORD starts the same transport before free-time MIDI capture. STOP sends controller Stop and All Notes Off without unloading the sound. TAP updates the current Pattern/controller tempo; it does not start transport, so PLAY remains the deliberate start gesture.

SOUND — reset, save sound, scale filter, and sounds#

RESET restores every mapped synthesis parameter in place; subsequent relative turns continue from those restored values. SAVE opens OVERWRITE, SAVE NEW, and CANCEL. Factory and system sounds are read-only, so their Overwrite row clearly saves a new private User NNN sound instead. Save New numbers sounds independently for synthv1, Moj Sint Model D, and Moj Sint Six-Op PM. A successful save becomes the current sound and the new RESET baseline immediately; it does not restart the engine, release held notes, or change the controls. Presets refreshes immediately, and a Moj sound remains inside its Model D or Six-Op PM hierarchy in FT2 ROUTE. Cancel closes only the overlay and preserves cursor/list state, live values, and held notes. A failed save preserves that state and any prior user file while keeping the overlay open for retry. Other backends show SAVE UNAVAILABLE. N00B toggles the optional scale filter without leaving Playback or hiding any normal content. SOUNDS returns directly to Presets, where LOAD starts the highlighted sound. While N00B is on, a single compact SCALE rotary appears below the 12 controls; turning the master encoder cycles every chromatic root in major and natural minor. Pressing N00B again removes only that control and restores chromatic play.

SYS — safety, effects, help, and return#

PANIC performs the global owned stop. FX opens the current Project rack without restarting the sound. HELP opens help and returns here afterward. EXIT returns to Presets, then Presets EXIT returns Home.

See SHR-DAW instruments and drums for the complete Moj Sint, SHR Sampler, and SHR Drums workflows and their ownership boundaries.

N00B-on Playback pages#

N00B changes only the scale filter and its compact rotary; the three Playback controller pages keep the same actions and ordering.

Ideas#

Ideas are timestamped or numbered free-time MIDI takes. A synthv1 Idea carries a private preset snapshot; external-engine Ideas retain their sound identity instead. Turn the encoder to select an entry.

PLAY — inspect, play, record, or delete#

INSPECT shows the Idea's sound and recording metadata. PLAY plays or stops the take. RECORD starts or stops capture. DELETE requires a repeated confirmation and only removes the selected Idea.

FILE — load or save an Idea#

LOAD restores the selected Idea, asking for confirmation before replacing an active sound. The old engine remains usable if validation, start, or activation fails, and the same Idea stays selected for another LOAD attempt. SAVE publishes a new non-overwriting Idea. FIRST and LAST select the list boundaries.

SYS — safety, help, and return#

PANIC stops owned notes and transports. HELP opens contextual help. EXIT returns Home.

MIDI Learn#

MIDI Learn isolates controller messages from instruments while it captures the master rotary's counter-clockwise turn, clockwise turn, and click, followed by optional relative controls and command buttons. Release each opening control as prompted. The review step writes a private controller profile only after confirmation; Back cancels without saving. A learned master rotary is enough to browse and confirm even when optional buttons are skipped.

Help#

Help is always available locally with ? or F1, even if the optional temporary LAN page cannot bind. Turn the encoder one rendered row at a time. On eight- or five-button layouts, encoder press follows a selected section link. Opening Help preserves the exact caller, controller page, FT2 mode/location, cursor, editor draft, and active transport. EXIT restores that exact context. If the LAN port cannot be acquired, only the local reader opens and reports the failure; no URL is advertised.

OPS — read and follow links#

OPEN follows the highlighted internal link and is the required link action on a four-button layout. TOP returns to the beginning. Keyboard PageUp/PageDown retain page scrolling; physical pads do not.

SYS — safety and return#

PANIC remains available while reading. EXIT returns to the exact screen that opened Help.

Audio recorder#

The recorder captures any deliberately configured set of JACK source ports as one synchronized take with a 24-bit mono WAV per input and a shared manifest. The compact list shows named tracks as ready or missing. Its body shows armed count, elapsed time, sample rate, writer high-water mark, drop/xrun counts, final path, or the failure reason; the one shared final status row remains separate below the two controller rows. It never starts or restarts JACK.

RECORD — arm and record#

RECORD starts all armed tracks at one callback boundary. ARM toggles the selected track. LEVELS opens the separate 18-channel Levels overview. An armed missing source prevents a take from starting.

TRACK — choose the inputs#

PREV and NEXT select a track. SOURCE cycles deliberately through the currently discovered sources (and blank); NAME KB opens computer-keyboard text entry for the musician-facing label. Runtime absence never overwrites a remembered source.

SETUP — prepare tracks#

ALL arms every resolved track, NONE disarms everything, and REFRESH discovers current JACK audio sources without changing assignments.

SYS — finalize safely#

PANIC stops owned activity. HELP opens help. EXIT returns Home without silently changing recorder state.

18-channel input Levels#

This native overview keeps exactly 18 recording inputs visible as three groups of six. It is not a route/setup inspector, the Synth/Loop/Input final-bus MTR, Live Patterns, Loop Mix, or a full mixer strip.

Rows 2–10 are nine circular-LED thresholds at −48, −36, −30, −24, −18, −12, −6, −3, and −1 dBFS. Green covers −48 through −18, yellow −12 through −3, and red −1. Smoothed RMS fills the column; a brighter LED of the same colour holds sample peak and then decays. Normal silence stays dark gray. M means a configured input is missing, F is a meter/callback fault, and held C marks genuine clipping.

At exact 40×13 the meter columns occupy only columns 1–20 and the visible command page only columns 21–40. The two ordinary controller rows are omitted; row 13 remains the unchanged shared status renderer. Below native size a compact ordinary screen replaces the overview instead of cropping or banking channels.

TAKE — setup and take control#

Levels TAKE command page (shown earlier)

SETUP returns to Audio Recorder naming/routing. RECORD, literal STOP, and RESET start a take, stop it, or clear presentation holds. Keyboard u, r, s, and x are equivalent.

CHANNEL — select without hiding#

Encoder turn, Left/Right, j/k, PREV/NEXT, or a pointer click selects a channel without changing the 18 visible meters. Encoder click, Enter, Space, or ARM toggles only that channel; REFRESH resolves remembered exact sources.

SYS — literal safety#

STOP, PANIC, HELP, and EXIT remain visible; literal STOP is also on TAKE. Panic also closes the recorder-owned meter client and follows global All Notes Off. Monitoring and recording clients are mutually exclusive, and shutdown closes either one.

Populated level and state examples#

Nominal recording input (shown earlier)

Selection and command page survive ordinary navigation and reset with a new or loaded Project. The right side is operational command space, not a numeric RMS/peak, route, or metadata detail panel.

Performance meter#

With the final bus active, MTR selects Synth, Loop, exact Input, or SHR Drums, controls its bounded level and one context-specific source action, switches Input between stereo and independently panned dual mono, shows readiness and the post-limiter true-peak final meter, opens the fixed MASTER STRIP, and controls final stereo recording. With the graph inactive it keeps the CPU/legacy meter presentation without pretending that direct output is being measured. CPU is whole-core /proc/stat activity, not callback timing or xruns.

Every horizontal meter cell is a circular ● LED. Unlit cells are dark gray; safe active cells use one green; yellow and red appear only at their active thresholds; a held peak is a brighter circle in the applicable threshold colour. No square bar or line-marker glyph represents level or peak.

OPS — source and level#

SOURCE-/SOURCE+ choose Synth, Loop, Input, or Drums. LEVEL-/LEVEL+ change only that source's bounded final-bus level. When Input's NAV control is focused on PAN 1 or PAN 2, these two positions relabel to the selected pan's minus/plus pair instead.

MIX — mute, record, and holds#

The first position is MUTE for Synth, Loop, and Drums. For Input it is MON ON while monitoring is off and MON OFF while monitoring is on; no second Input mute is shown. Controller, pointer, and keyboard m all invoke this same visible action. MON ON starts the owned final bus if needed without starting an optional source. RECORD toggles the callback-boundary final stereo recorder. RESET clears presentation peak/clip holds; it does not reset effects, CPU state, or transport.

NAV — FX, master strip, and Input mode#

FX opens the same master-overlay layer used by FT2. Choose SOURCE, AUX 1, AUX 2, AUX 3, or MASTER, then click/Enter to open that rack.

With Input selected, DUAL changes the exact configured pair from its original stereo mapping to two independently panned mono signals; it then reads STEREO for the reverse action. Dual mono begins at 1L100 2R100, so the first switch preserves the stereo image. IN CTRL cycles LEVEL, PAN 1, and PAN 2; the OPS minus/plus pair follows that focus. Mode and focus use these visible controller actions and add no dedicated computer-keyboard shortcuts. These live values are not saved in the Project.

The MTR remains underneath; pressing the highlighted FX again closes the overlay without changing audio or Project state.

SYS — safety and return#

PANIC remains available. HELP opens the explanation of meter scope. EXIT returns to Home. The screenshot says Presentation · no live audio because its meter values are seeded for documentation rather than measured.

Routing#

Routing is a transactional editor for controller and performance inputs, controller role, external MIDI/profile, controller clock, and the stereo audio destination. Turn to browse rows and press to start an isolated draft. Turn to change that field, then press to validate, save, and activate it; Back cancels the draft without writing. Audio and clock changes that cannot be activated live are clearly marked for the next managed-engine start.

EDIT — browse or change one route#

PREV and NEXT browse the same wrapping row list as the master rotary. EDIT/OK starts or confirms the selected field. CANCEL abandons the active field, or returns Home when no draft is active.

SYS — safety and return#

PANIC stops owned playback and sends All Notes Off. HELP opens the local reference. EXIT cancels an active draft first, otherwise returning Home.

Back to detailed guides

Manual home · Everyday screens · FT2 and Projects

WAV loops and the owned effects graph require a running JACK server, but the screenshots below are deterministic presentation states and never start JACK. The loop player and graph operate only on resources owned by SHR-DAW.

FT2 Loop Mix#

Every FT2 Pattern owns four optional references to privately imported mono or stereo WAVs. The page shows the Pattern under the FT2 cursor; browsing does not change the sounding Pattern. Every active slot must match its Pattern tempo and JACK sample rate; playback stays native pitch/speed with no time-stretching. The four fixed renderers sum inside one owned Loop JACK client, so the existing LOOP OUT meter and final bus receive the complete Loop source once.

Selection is white and never launches. Rows separately show playing, stopped, queued launch/stop, muted, missing, and faulted slots. One bad WAV does not stop the other three. The ordinary rotary browses inbox WAVs; Shift-rotary changes the selected slot through the same wrapping action as SLOT-/SLOT+.

These ownership and state shots use the same real renderer without starting audio:

The root Loop Mix tour is the native 40×13 view; smaller terminals fall back without taking the shared status row:

PLAY — bar-quantized slot transport#

STOP and LAUNCH queue the selected slot for the next Pattern-local bar. SLOT-/SLOT+ change selection without playback. A later command replaces the earlier queue.

MIX — level, mute, and remove#

LEVEL-/LEVEL+ adjust the selected slot's smoothed 0–150% level. MUTE affects only that slot. REMOVE requires confirmation, clears only its Pattern reference, and keeps the private WAV.

FILTER — bipolar shaping and queue cancel#

FILTER- moves from neutral toward low-pass; FILTER+ moves toward high-pass. The centre deadband is neutral and changes are smoothed. CANCEL removes the selected slot's queued command. ALIGN opens bounded offline analysis and whole-bar placement.

SYS — safety, import, library, and return#

PANIC remains reachable. IMPORT attaches the selected inbox WAV to the selected slot. LIBRARY opens the shared loop browser for that slot. EXIT returns to the caller without moving its cursor.

Private loop browser#

LIBRARY opens the shared overlay over the unchanged loop page. It includes INBOX, CURRENT, PRIVATE, and SAVED entries. Turning the rotary changes selection silently. Controller PLAY at position 6 explicitly previews the selection; pressing it again stops. Changing selection, controller STOP, Back, the highlighted LIBRARY launcher, or leaving the browser stops the preview. Pressing the rotary/Enter commits the selected file: INBOX imports first, while the other types attach an existing private WAV. A failed preview or import leaves the browser selection and caller state in place for retry, and a failed import removes its private copy. The browser has no deletion action.

The caller remains visible while the overlay identifies each file's source and saved-Pattern relationship.

Loop Align#

Align performs bounded offline pulse/duration analysis, can snap interpreted length to complete Pattern bars, and can shift placement without destructively editing the audio file.

OPS — analyze and place#

AUTO analyzes the attached file and proposes a Pattern-bar-aligned beat length. BAR- and BAR+ move its placement by exactly one bar. DONE keeps the settings and returns to WAV Loop.

SYS — safety, help, and leave#

PANIC and HELP stay available. EXIT returns to Loop Mix without performing another automatic analysis.

FX Rack#

The rack targets SOURCE, AUX 1, AUX 2, AUX 3, DRUMS, or MASTER. Source, drum, and master racks are serial inserts. Aux buses have an independent send level, pre/post source-insert point, wet-only processor rack, and return level. Each rack is bounded to eight effects. The ordinary rotary browses its rows; Shift-rotary selects the previous or next target in the existing order. With the graph active, FX changes are refused while transport or recording makes publication unsafe. With it disabled, the same controls edit saved Project data without touching audio.

The first screenshot shows a populated source chain. Selecting another target keeps the same menu but changes the body and which routing actions apply. The final blank-looking + INSERT EFFECT row is a typed functional selection, not an effect index or decoration. It remains reachable once, participates in first/last wrapping, and click/Enter inserts an effect at that position.

OPS — edit rack contents#

ADD inserts a provisional processor and opens its Type context. DEL removes only the selected owned processor. EDIT opens the Type context for the selected processor. PARAM opens its named parameter editor.

ORDER — reorder, bypass, or open the fixed strip#

UP and DOWN move the selected effect within this rack. BYPASS fades it between active and safe bypass. Aux targets offer only supported wet time/modulation effects. On the MASTER target, STRIP opens the fixed Project-global mastering path after this reorderable rack.

ROUTE — choose rack and aux send#

TARGET cycles Source, Aux 1, Aux 2, Drums, and Master forward. Shift-rotary uses that same order in either direction. On an aux target, SEND- and SEND+ adjust its send level in dB and POINT toggles pre/post source inserts. Those three controls report that an aux must be selected when used elsewhere.

SYS — return level, help, and exit#

PANIC remains available. On an aux target, RETURN cycles its independent return level. HELP opens the local reference. EXIT returns one level.

Empty rack context#

OPS exposes only ADD; unavailable edit and delete actions stay hidden.

The empty MASTER rack's ORDER page still exposes STRIP; other targets ask for MASTER rather than opening a misleading per-source mastering path.

ROUTE still selects the target and, for an aux, its send settings.

SYS preserves panic, return-level, help, and one-level exit actions.

TYPE — choose or replace an effect type#

TYPE- and TYPE+ browse compatible processors. OK confirms the new type; CANCEL restores the original processor, or removes a newly inserted provisional one. This context is distinct from PARAM, which edits named values without changing the processor type.

Fixed MASTER STRIP#

The fixed strip follows the MASTER rack and live master fader. It is not an effect slot and cannot be reordered. Its front page shows the owning Project and saved/dirty state, INPUT, TONE, GLUE, COLOR, IMAGE, LOUD/CEIL, the selected value, sample/true peak, LUFS, linked reduction, and correlation warning. Browsing preserves the calling MTR/FX context and unrelated FT2 cursor.

PREV/NEXT select one section, DETAIL opens its advanced values, and BYPASS fades INPUT, TONE, GLUE, COLOR, or IMAGE. LOUD/true-peak protection cannot be bypassed.

A/B compares the optional strip processing with the same fixed delay and limiter. RESET I clears only integrated loudness. Edited settings stay intact. Numerical and bypass updates are smoothed during playback; final recording rejects them.

The front-page SYS commands keep PANIC, HELP, and EXIT available without changing the selected section or caller.

The detail page lists only the selected section's parameters. The ordinary rotary browses its parameters; Shift-rotary selects the previous or next section through the front-page order and starts at that section's first parameter. VALUE- and VALUE+ change the selected value.

STATE retains section bypass, A/B comparison, and integrated loudness reset while the detail values stay visible.

SYS keeps global Panic, contextual Help, and one-level Exit available from the detail view.

Below native geometry the screen compacts without drawing over the shared status row. The exact DSP ranges, latency, true-peak tolerance, and provenance are in Fixed stereo MASTER STRIP.

FX parameter editor#

Parameters come from strict persisted schemas. Non-EQ effects use a curated 2×4 layout of at most eight controls that mirrors the physical rotary positions. Each cell has the parameter title above its type-aware value; clear names such as RATE, RATIO, ATTACK, and FEEDBACK replace cryptic three-letter labels.

At 40×13, EQ uses a dedicated fullscreen editor:

Its 20-column plot covers 50 Hz–20 kHz logarithmically. Low, low-mid, high-mid, and high each use one movable ─; vertical placement rounds to the nearest labelled −18 to +18 dB row while the value readout and edit remain accurate to 0.5 dB. The master rotary browses bypass, all four frequency/gain pairs, low-cut state and frequency, and output trim. Turn to browse, click to edit, turn to change, click to confirm, and Back to restore the old value. Toggle fields act immediately. Yellow is selected, green is editing, and bypass dims the plot.

Knobs 1–4 remain logarithmic low, low-mid, high-mid, and high frequencies; knobs 5–8 are their matching half-decibel gains. Low cut is not placed on knob

1. Existing off-grid Project values display honestly until edited, so this surface does not invalidate saved Projects. Below 40×13, EQ uses the compact generic editor.

The title/state uses one row and metering is bounded to one row. The compressor shows 11 round red LEDs from 0.5 to 24 dB: dim circles keep the hardware-like scale visible, while bright circles show live gain reduction and all stay dim on bypass. Other processors use terse input/output values. Meter detail never displaces a parameter.

Numeric keyboard entry follows the same range and type validation. There are no duplicate PARAM± or VALUE± navigation buttons.

STATE — bypass this processor#

BYPASS toggles the edited processor without removing its ID, parameters, or position. Bypass uses click-conscious smoothing in the active graph.

SYS — safety and exit#

PANIC and HELP stay available. EXIT returns to the rack. Invalid or non-finite parameter values are refused rather than published to audio.

Back to detailed guides

Manual home · Everyday screens · Loops and effects

SHR-DAW's FT2 screen is a compact vertical MIDI Pattern sequencer inspired by tracker workflow. It is not an XM editor or a clone of FastTracker II. A Project owns several Patterns and an Arrangement order. Each Pattern has one or more four-lane pages. Portable AUTO pages defer destination and channels to the active machine; explicit pages retain a destination plus each column's channel, bank, and program.

The screenshots use a populated demonstration Project. External routes are shown as offline where no actual device was opened for documentation.

At native 40×13 the Pattern body and compact page/lane footer end above the two controller rows. The final row is the shared status row, so the tracker header does not add a second PLY/REC label.

FT2 Pattern — Play mode#

Turn the main encoder to move rows. Hold the configured encoder Shift while turning to select the previous or next column, including across page boundaries. Keyboard Up/Down and Left/Right remain the row and column alternatives. The shaded column is the live selection; the stronger yellow cell cursor and highlighted row remain the next edit/play location.

PLAY — transport and entry#

CELL opens the transactional editor. PLAY toggles tracker transport. RECORD stops another active mode and starts the current Pattern record loop. EDIT stops Play or REC before enabling note entry.

SELECT — master overlays#

PAGE, PATTERN, SONG, and ROUTE open the reusable centered overlay while the Pattern remains visible around it. Turn the master rotary or use Up/Down; click/Enter selects. PAGE, PATTERN, and SONG keep only their highlighted launcher on the overlay's bottom border near its original physical position. ROUTE ends above a normal controller strip whose ROUTE page exposes APPLY and CANCEL on the physical item buttons. The final row remains the shared status row. Press an ordinary overlay's launcher again, or use keyboard Back/Esc, to close. There is no extra controller Back item.

On 40×13 the ordinary overlay border is 38×11 at (1,1) with 36×9 usable content. ROUTE reserves the two controller rows, so its border is 38×9 with 36×7 usable content.

PAGE selects a page/column location and can open the detailed Tracks manager.

PATTERN selects an existing Pattern and links to Pattern tools or Project Files.

SONG selects an Arrangement step and links to Arrangement or page tools.

ROUTE opens the quick live route editor. Its complete field and rollback contract appears in ROUTE master overlay.

SOUND — current software instrument and mixer#

Normal FT2 page 3 is SOUND: PARAM, MIX, AUTO, and the next-boundary FILL latch. CLICK remains available on FT2 Tools SYS item 3. PARAM opens an FT2-owned parameter child without changing the selected Pattern, Arrangement step, page, lane, column, cursor row, mode, transport, route, or managed-engine ownership. Back/Esc or SYS EXIT returns to that exact location and the launching SOUND page. Instrument selection remains in ROUTE.

The child reuses Playback's current 3×5 view, including the active synthv1 or Moj Sint model labels, live values, relative-to-preset colours, rotary carry, and held notes. Older 12-control instruments use the final three slots for Project AUX 1/2/3 sends; Dual Filter retains fifteen synth controls. Its SOUND page contains RESET, SAVE, N00B, and one empty position. RESET restores the existing baseline in place without restarting the engine or releasing notes. SAVE uses the same Overwrite/Save New/Cancel overlay and private preset storage as Playback; a successful save becomes the new RESET baseline and retargets only the active matching FT2 route. Its SYS page contains PANIC, an empty position, HELP, and EXIT. Backends without mapped editable controls show parameters and SAVE as unavailable.

MIX opens the live audio-level mixer described below. Shift-clicking the main encoder is the direct controller shortcut in Play, REC, and Edit.

SYS — safety, filter, help, and exit#

PANIC stops all owned notes and transports. N00B immediately toggles the Player-selected scale filter without leaving Play. HELP opens contextual help. EXIT returns Home.

FT2 Pattern — real-time Record context#

Record uses the selected page's exact online Pattern-owned software or hardware instrument and its persisted Manual, One-column, or Drum-auto entry layout. Incoming notes are quantized into the current transport position. Each note-on owns its exact page/lane until its release, even across a loop or Arrangement boundary. Turns are ignored—not queued—while recorded notes remain held. REC from stopped transport owns its Pattern loop; REC during Play punches into the current Arrangement and punch-out returns to Play. Key release writes a quantized note-off independently of Edit note length.

MODE — transport and capture#

MIX opens the live audio-level mixer without ending capture. PLAY ends REC and starts normal transport. RECORD ends real-time capture while preserving the notes already entered. EDIT ends REC and enters stopped Edit mode. With N00B on, only allowed notes are heard and written.

SYS — emergency and normal exits#

PANIC performs the global owned stop. N00B toggles the same independent filter without ending capture. HELP explains the current mode. EXIT leaves the recording context safely.

FT2 Pattern — Edit context#

In Edit, Manual writes from the selected column, One column redirects every note to its displayed C1–C4 monophonic anchor, and Drum auto allocates a whole simultaneous group without overwriting existing row cells or unrelated active cymbal tails. Automatic placement never moves the visible lane cursor. Command-pad notes remain controls. The persistent ADD value chooses any advance from 0 through 32 rows after entry, blank, erase, or note-off; 0 stays on the current row. DRUM LANES FULL rejects an unplaceable hit/group without changing the Pattern.

EDIT — enter or remove cells#

Populated FT2 Pattern in Edit mode with the EDIT page (shown earlier)

CELL opens contextual cell editing. BLANK advances without writing a note. ERASE clears the selected cell. N-OFF writes a note-off. Edit contains no duplicated Play, Record, or Edit mode buttons.

SET — rotary selectors#

LENGTH opens every note duration from 1/1 through 1/128. ADD opens every advance from 0 through 32 rows. Each selector opens on its current value; turning changes the draft, clicking commits, and Back cancels without changing the stored value. LENGTH and ADD remain independent. COL- and COL+ move the edit cursor between the page's four note columns.

SIZE — Pattern rows#

HALF keeps the top or bottom half of an even-length Pattern. ROW- removes the cursor row, ROW+ inserts an empty row after it, and DOUBLE appends an empty or copied second half. Every operation covers every page and lane. Populated destructive choices report the exact affected-cell count before confirmation; Cancel leaves the Pattern unchanged. SIZE stops active FT2 Play/REC only when committing, preserves the page, column, and safely mapped cursor, and supports the existing 1–256-row range.

Normal FT2 SELECT remains available after leaving Edit and still owns PAGE, PATTERN, SONG, and ROUTE.

Shift-click the main encoder to open the live audio-level mixer from Edit. This keeps the four Edit command pages intact.

SYS — safety, help, and leave edit#

PANIC performs the owned stop. N00B toggles the same independent filter. HELP opens contextual help. EXIT leaves Edit exactly one level and returns to normal FT2 while preserving Pattern, page, column, and cursor row.

FT2 live audio-level mixer#

The mixer keeps the current Play, REC, or Edit mode and restores the exact Arrangement step, Pattern, row, page, lane/column, and controller-menu page on exit. In Play and REC it follows the Pattern the sequencer is sounding; in Edit it follows the Pattern being edited.

At native 40×13 it uses one 4×3 panel for up to twelve strips. Every strip shows its page/name, canonical SYN, DRM, LOP, or INP owner, signed gain, five circular VU LEDs and shared-owner link count. External MIDI without an exact configured stereo SHR return says NO RETURN and exposes no working fader or VU. A configured Input marked M is still monitor-off; opening the mixer never silently changes that safety choice.

With twelve configured active rotaries, pages 1–12 map directly. With fewer rotaries, the ordered available rotary positions control the visible bank. Turn the main encoder or use BANK- and BANK+ to change banks. Direction-only rotaries carry the current gain directly. Pages with the same owner share one gain and VU.

Opening the panel activates the final bus so live audition and transport use owner gain → Project processing/master strip → master volume → limiter/output. SYS retains PANIC, HELP, and EXIT; main-encoder click and Back also exit.

FT2 Cell Edit#

Cell Edit uses a draft copy: adjustments are not published until CONFIRM. The cell can contain a note, inherited or explicit velocity, inherited or explicit gate, an optional per-note program, independent timing, deterministic chance, one loop-aware condition, and one command: cut, delay, retrigger, tempo, or none.

ROUTE — destination defaults for this cell#

DEST, CHANNEL, and INSTR select the cell's route, channel, and inherited instrument fields. Turning the master rotary adjusts the selected field in the draft; the Pattern stays unchanged until SAVE.

SOUND — banks and per-cell program#

BNK MSB, BNK LSB, and PROGRAM select the MIDI sound-routing fields. CLEAR clears only the selected field back to its inherited/default representation. An explicit per-cell program is sent before that note on its exact target and channel.

CELL — musical content and command type#

NOTE, GATE, and VEL select the corresponding value. Gate is a percentage of one row; inherited values use the page/project default. EFFECT selects and cycles cut, delay, retrigger, tempo, or none.

DONE — save or cancel the draft#

PANIC stays reachable. SAVE commits the whole draft. PARAM selects the current command parameter. EXIT cancels and restores the original cell, so a half-edited draft never leaks into the Project.

After TIME, the rotary field list continues with CHANCE, CONDITION, COND A, and COND B. The four visible direct-action pages remain unchanged; use the inactive rotary to select these fields, press to edit, then turn. Conditions are ALWAYS, FIRST, LAST/N, A:B, PRE, and FILL. Normal FT2 SOUND item 4 and keyboard f arm FILL for the next playback-cycle boundary; CLICK is on FT2 Tools SYS.

FT2 Tools#

This detailed child screen remains for Arrangement, Live Patterns, clip operations, Loop Mix, effects, muting, and the read-only Harmony browser. Open it from the SONG overlay's OPEN LOOP / PAGE TOOLS row. Quick Page, Pattern, Song, and Route selection stays in the master overlays.

OPS — open focused tools#

ARR opens the saved Arrangement. LIVE opens Live Patterns. FX opens the Project effects rack. LOOP opens the four-slot Loop Mix.

CLIP — lane and page clipboard#

COPY L, PASTE L, COPY PG, and PSTE PG copy or paste the current lane or full four-lane page. These are in-memory editing clipboards, not saved Projects. COPY PG carries cells only; it does not duplicate the Page route, setup, name, mute, or automation. Complete Page operations remain a future Page-manager task.

PAGE — page mute#

MUTE PG toggles the current four-lane page. MUTE toggles the selected stored tracker lane. Transient performance mute remains on Live Patterns. HARMONY opens a silent browser derived from the current Project key.

The browser shows the counter-clockwise and clockwise fifth neighbours around the current key, its relative and parallel keys, and all seven diatonic triads. English/German note naming follows configuration; enharmonic names use the same canonical sharp spelling as existing SHR note and chord labels. The view has no selection or Apply action: the HARMONY launcher, EXIT, encoder press, Back/Esc, keyboard H, or right-click closes it. Project data, dirty state, transport, FT2 mode, and the exact editor and controller positions stay intact.

SYS — safety, help, and return#

PANIC and HELP retain their normal meanings. EXIT returns to the Pattern editor.

Live Patterns#

Live Patterns performs existing tracker Patterns without changing the saved Arrangement. Browsing changes the white selection only. Green PLAY and yellow Q identify current and queued Patterns independently, while the lower rows show transient lane shaping. Each row's loop count belongs to that Pattern; launch and retrigger switch/restart its MIDI and Loop Mix together. The ordinary rotary browses Patterns or adjusts the selected shape control; Shift-rotary changes lane through the existing Left/Right action.

LAUNCH — select, queue, cancel, retrigger#

Populated Live Patterns with the LAUNCH page (shown earlier)

LAUNCH queues the selected Pattern. CANCEL removes the queue. RETRIG queues the current Pattern deliberately. NOW is the distinct immediate action.

TIMING — boundary and capture#

STOP is literal transport stop. PAT Q and BAR Q choose the next Pattern or complete-bar boundary. CAPTURE arms/stages/cancels temporary launch capture without silently changing Arrangement.

SHAPE — transient four-lane performance#

MUTE, VEL, GATE, and TRANS affect the selected page/lane runtime copy. Values survive navigation in this Project and reset on Project load/new.

SYS — safety and capture confirmation#

PANIC remains global. APPEND or REPLACE explicitly confirms a staged capture; repeated launches remain repeated Pattern references. EXIT returns without moving the editor cursor.

See Live performance for exact boundary ownership, keyboard equivalents, failures, and deliberate limits.

N00B filter and Edit note length#

N00B is an independent scale-filter switch, not a fourth FT2 mode and not a duration control. Player owns the scale choice: enabling N00B there adds one compact SCALE rotary to the unchanged Player screen, and turning the master encoder cycles every chromatic root in major and natural minor. FT2 uses that selection. On a melodic page, an in-scale key keeps its original pitch and an out-of-scale key stays silent; no rejected key is shifted to a nearby note. The FT2 button stays in the same SYS position, toggles the filter immediately, and can stay on through Play, Record, and Edit; moving to Drums turns only the filter off.

Note duration belongs separately to Edit. LENGTH opens an overlay for 1/1 through 1/128; it does not change the independent 0–32-row ADD advance.

Project Files#

Files manages complete saved Projects. Names shown to the musician are editable. Save and Save As publish atomically and never silently replace a collision. Preview uses the selected saved Project without treating it as the current edit.

OPS — save, load, delete, MIDI import#

LOAD opens the selected Project. SAVE writes the current Project and asks before replacement. DELETE requires repeat confirmation. MIDI uses the empty fourth position to open the private Standard MIDI File inbox. Selecting or pressing LOAD first analyses the file and shows parts/pages, Pattern rows, tempo/meter, timing accuracy, stripped-event counts, and warnings; a second action confirms the new unsaved Project. A dirty LOAD or MIDI import first opens the four-row rotary guard: SAVE (AUTO), SAVE (NAME), DON'T SAVE, and BACK. Back or a failed/pending save keeps the Project and exact tracker position.

The MIDI browser follows no symlinks and accepts bounded regular .mid and .midi format 0/1 PPQN files only. It never previews, transmits, or overwrites the source file or an existing Project. Saved-Project PREVIEW remains on the separate PREVIEW command page.

PREVIEW: hear the selected saved Project#

PREVIEW starts or stops a bounded preview of the selected saved Project. It does not replace the Project being edited. Using the same command again, leaving the screen, or using Panic stops the preview.

PROJECT — lifecycle and Pattern child#

NEW creates a confirmed blank Project. SAVE AS writes a numbered non-overwriting copy. NAME opens the current Project display name; rotary click accepts it and computer-keyboard editing is optional. PATTERN opens Pattern tools.

SYS — safety, help, and return#

PANIC and HELP remain available. EXIT cancels pending file actions and returns to the tracker.

Dirty FT2 Exit, New Project, LOAD, confirmed MIDI replacement, and application quit all use the same guard. It opens on SAVE (AUTO). An unsaved automatic save chooses the next free Project name; SAVE (NAME) supplies the same kind of collision-free suggestion before optional editing. Continuation happens only after a completed save. DON'T SAVE explicitly restores the clean Project baseline before leaving FT2, including its routing, effects, and Loop Mix ownership. BACK and Esc return to the exact caller and context.

When saving a changed blank Pattern, SHR can offer its routing as the private default for future Patterns.

CONFIRM queues the template and writes it only after the Project save succeeds; CANCEL keeps the previous default.

SYS keeps panic and exit/cancel reachable; neither choice changes notes.

Pattern tools#

Pattern tools operate on the Pattern referenced by the current Arrangement step. Cleanup deletes only zero-reference Patterns; it never rewrites the Arrangement behind the user's back. Transposition affects melodic pages only.

OPS — Pattern lifecycle#

BLANK opens Pattern setup with empty Loop Mix slots. CLONE creates a separate copy of MIDI and all four loop references/settings and selects it. CLEAR opens a confirmed clear/resize setup; when loops are attached the prompt states how many will detach. DRUMS opens reusable rhythms.

CLIP — Pattern clipboard and cleanup#

COPY stores the complete Pattern, including Loop Mix, in memory. PASTE+ creates an independent new Pattern from it. OVER asks before replacing the current Pattern, including its loops. CLEAN deletes only Patterns not referenced by any Arrangement step and never deletes private WAV files.

TRANS — transpose melody only#

OCT-, NOTE-, NOTE+, and OCT+ transpose melodic notes by −12, −1, +1, or +12 semitones. Percussion pages and note-off commands are left unchanged.

SYS — safety, help, and return#

PANIC and HELP stay available. EXIT returns to Project Files.

Drum patterns#

The library contains bundled read-only grooves plus user-saved four-lane drum Patterns. Filters select genre, 3/4 or 4/4, and supported two-, four-, or eight-bar row sizes. Loading may resize an empty melodic Pattern, but refuses a shape change once melody exists.

OPS — load and manage a rhythm#

LOAD writes the selected rhythm into the percussion page without changing its route. SAVE stores the current percussion page as a user rhythm. DELETE can remove only a user save and requires confirmation.

FILTER — narrow the library#

GENRE- and GENRE+ move among the available genres and ALL. METER toggles 3/4 and 4/4. SIZE cycles the supported Pattern lengths for that meter. Shift-rotary reuses the genre actions in both directions while the ordinary rotary continues to browse rhythms.

MOVE — navigate a long result list#

FIRST and LAST move to the filtered result-list boundaries without loading anything. Turn the rotary for one-step movement, type a first letter to jump, or use keyboard PageUp/PageDown for coarse scrolling; physical pads omit the coarse page commands.

SYS — safety, help, and return#

PANIC and HELP remain available. EXIT returns to Pattern tools.

Pattern setup#

This confirmation context chooses musical meter and row count before a new or destructively cleared Pattern is created. LNGTH opens a rotary overlay with every row count from 1 through 32 plus 48, 64, 96, 128, 192, and 256.

OPS — meter and size#

3/4 and 4/4 choose the meter without silently changing the row count. LNGTH opens the row-count overlay; turning browses and clicking keeps the highlighted value in the still-unconfirmed Pattern setup.

APPLY — confirm or preserve#

CONFIRM performs the requested NEW or CLEAR operation with the displayed meter and length. KEEP also performs the operation, but preserves the current Pattern's meter and length: NEW creates a blank Pattern with that shape, while CLEAR clears content without reshaping it.

SYS — safety and cancellation#

PANIC and HELP remain available. EXIT cancels the setup and returns to Pattern tools.

Arrangement#

Arrangement is the ordered list of Pattern IDs that forms the Project timeline. Repeated steps reference the same Pattern until it is cloned.

OPS — play and insert Pattern references#

PLAY starts at the selected step. JUMP opens that step's Pattern in the editor. APPEND adds the current Pattern at the end. INSERT adds it before the selected step.

STEP — reorder and repeat#

UP and DOWN move the selected step earlier or later. REPEAT duplicates the reference. REMOVE removes only this step, not the underlying Pattern.

SYS — safety, help, and return#

PANIC and HELP remain available. EXIT returns to the tracker.

ROUTE master overlay#

ROUTE is the quick transactional editor for the active Pattern page. The top rows show the page/master destination and its current resolved state, the software engine/instrument, SHR Drums kit, or external MIDI output, and the optional device profile as applicable. The next 16 rows show channel, bank MSB, bank LSB, and program/instrument for each of the page's four columns; profile-provided instrument names appear when available. Long names are deliberately shortened inside the border.

Turn to a row and click/Enter to make that field active. Only then does rotary movement validate and apply the choice to the Project and live route. This allows immediate software instrument, drum kit, and external program audition. A failed engine, kit, or route change restores the previous field value and live route. Click/Enter keeps the current field value; Back/Esc restores the value from before that field was opened.

The standard bottom controller action row always shows APPLY and CANCEL, so neither whole-route action depends on scrolling to the final list row. Positions 5 and 8 activate those exact actions on the controller; mouse and keyboard A/C share them. Apply keeps the current live result. Cancel or Back/Esc from the main list restores the complete route snapshot from when the overlay opened. Back/Esc during a field edit restores only that field. Missing preferred hardware remains visible and saved as preferred; an exact external target stays offline or ambiguous and never uses either the configured hardware default or the Pattern's software synth. AUTO alone keeps portable machine-default behavior and owns no explicit channel/bank/program values.

Tracks and routing#

The Tracks screen edits four-lane pages. Changes are kept as a draft until DONE; EXIT restores the original Project. Turn the encoder to choose a page in normal mode; Shift-turn it to choose a column through the existing bounded Column−/Column+ action. A destination is shared by the page, while channel, bank, and program belong to the selected column.

Open it from the PAGE overlay's MANAGE PAGES / TRACKS row. It intentionally remains a full screen because adding pages and coordinating several fields is more detailed than quick overlay navigation.

OPS — add and route pages#

ADD adds one four-lane page. TARGET opens the destination field. CHANNEL opens the selected column's MIDI channel field. DONE validates conflicts and keeps all page-manager changes. For an external MIDI page, DONE also sends the selected column's bank/program choice immediately for FT2 free play.

COLUMN — choose column and program#

COL- and COL+ select one of the page's four columns. PROG- and PROG+ choose its 0–127 program, using a device profile's name when available. DONE on OPS sends that selected program as well as keeping it in the Pattern.

BANK — choose the selected column's bank#

MSB-, MSB+, LSB-, and LSB+ adjust the MIDI bank-select bytes for the selected column. The configured bank-select order is honored during playback.

SYS — safety, help, and cancel#

PANIC and HELP remain available. ENTRY opens Manual, One column C1–C4, and Drum auto choices for the selected page. EXIT cancels the entire Tracks draft and restores the original Project.

Target field editor#

The target field lists discovered synthv1 presets, the configured external route, and discovered named MIDI outputs. A synth choice belongs to the Pattern, not the standalone Software Synth workspace. Offline selections are retained in the Project rather than silently rewritten.

OPS — confirm destination#

Turn the encoder to choose a device. CONFIRM applies the field to the draft page and returns to Tracks. On eight- and five-button layouts, encoder press is also confirm.

SYS — cancel only this field#

PANIC and HELP stay available. EXIT cancels only the target field and returns to the unchanged Tracks draft.

Channel field editor#

Channel editing affects only the selected column. The visible value is 1–16; the persisted MIDI byte remains the standard zero-based 0–15 representation.

OPS — confirm channel#

Turn the encoder to choose 1–16. CONFIRM applies the field and returns to Tracks. Encoder press also confirms on eight- and five-button layouts.

SYS — cancel only this field#

PANIC and HELP stay available. EXIT discards only the channel draft and returns to Tracks.

Back to detailed guides

SHR-DAW supports two coherent Raspberry Pi paths. On Patchbox OS it retains the distribution's shared JACK service and working real-time policy, then offers only missing SHR-specific CPU isolation. On a clean 64-bit Raspberry Pi OS Lite installation it installs the required packages, can add missing real-time permissions, creates a user JACK command only when no system service or live jackd process owns JACK, and offers the same reviewed CPU profile. Detection comes before mutation. Destructive and unrelated system changes default to no; the single boot-service choice defaults to yes only after the user explicitly selects JACK hardware and timing.

Current connected physical audio and MIDI evidence comes from Patchbox OS based on Debian 12 (Bookworm). The clean Raspberry Pi OS Lite 64-bit install, setup, doctor, and silent-engine path was accepted separately on the Raspberry Pi 5. Those are different evidence: neither proves that every hardware and audio path has been physically accepted on every supported image. Record the exact image and version used rather than treating “Lite” as a reproducible version identifier. The experimental roadmap owns the work order; the Pi 5 plan owns the state comparison.

For the planned native-NVMe Pi 5, first follow Raspberry Pi 5 NVMe installation. It covers safe drive identification, Raspberry Pi Imager, headless customisation, first-boot proof, boot-order recovery, and base-specific PCIe settings. The SHR-DAW assembly uses a bottom NVMe base so its GPIO display can occupy the top of the Pi; it does not use a top-mounted M.2 HAT. Return here only after findmnt proves that the running root filesystem is on the NVMe.

The supported family is Debian-based Linux. The exact Rust toolchain selected by rust-toolchain.toml, a C build toolchain, pkg-config, Python 3, ripgrep, ALSA development/runtime tools, and JACK2 are required to build and diagnose the complete installation. A stale distribution Rust package does not set the project's compiler direction; the installer uses the official per-user rustup toolchain. A running JACK server is optional for browsing and editing but required for software-instrument audio, WAV-loop playback, and multitrack recording. synthv1, Yoshimi, FluidSynth/TimGM, Moj Sint, and SHR Sampler are separate optional melodic engines at runtime. The supported installer installs all five from distribution packages or the exact public revisions in install/compatibility.json. It installs Moj Sint's 16 allowlisted factory presets and SHR Sampler's allowlisted project-authored factory package; it never copies private presets, samples, packages, or user data from a checkout. SHR Drums remains an exact pinned in-process Rust dependency, so there is no separate shr-drums executable or layered drum service. MIDI controllers, external instruments, audio interfaces, and a 480×320 display are optional hardware. On that display the current fixed TTY layout is 40×13 cells; installation does not change its font.

Install#

For a new public installation, clone the current experimental source and run its installer in one command:

git clone --depth 1 https://github.com/PaolaShultz/shr-daw.git && cd shr-daw && ./scripts/install.sh

From an existing checkout, run ./scripts/install.sh. A historical tag may be checked out for reproducibility, but tags are experimental snapshots rather than production releases.

The current source compatibility set is:

Component	Required version	Installation form
Moj Sint	0.2.3	exact public commit, moj-sint, 16 cleared presets
SHR Sampler	0.1.2 (accepted runtime >=0.1.2,<0.2.0)	exact public commit, shr-sampler, one cleared package
SHR Drums	0.2.0 (accepted library >=0.2.0,<0.3.0)	exact public Cargo dependency compiled into shr

The machine-readable source commits and runtime bounds live only in install/compatibility.json; documentation summarizes rather than duplicates their hashes.

SHR-DAW source can host the newer Moj Sint preset schema 8 and its Dual Filter model, but the current compatibility file still pins the earlier public Moj Sint commit whose cleared catalog contains 16 starts. The installer therefore does not install the five Dual Filter starts. Treat the compatibility file, not the broader host capability, as the installation contract.

The installer:

• previews its phases, refuses root invocation, and verifies apt-get and sudo before its first package change;
• after one default-no grouped prompt, installs build, JACK, and ALSA tools;
• resolves the Debian 12/13 JACK client-tools package split so jack_lsp and its small runtime library set are present;
• installs synthv1, Yoshimi, FluidSynth, and the small TimGM SoundFont without recommended desktop frontends or the much larger FluidR3 bank;
• stops and masks the package-enabled per-user FluidSynth daemon while leaving the FluidSynth executable available to SHR;
• detects the current login's rtprio and memlock; if they are inadequate, a separate default-no prompt can add the user to audio and create a helper-owned limits file only when no distribution policy already suffices;
• installs the exact official Rust toolchains selected by each repository, fetches Moj Sint and SHR Sampler by immutable public commit, verifies their declared versions, and creates locked release builds;
• builds SHR-DAW against SHR Drums 0.2.0 from its exact public Git revision;
• stages commands, templates, 21 allowlisted synthv1 presets, 16 allowlisted Moj Sint presets, the allowlisted SHR Sampler package, four allowlisted SHR Drums kits, four allowlisted CC0 48 kHz loops, ten manifest-cleared demo Projects plus MIDI files, profiles, drum data, and documentation;
• preflights the complete payload, refuses a differing unowned destination, and transactionally installs it below /usr/local with hashes, modes, and symlink targets recorded in /usr/local/share/shr-daw-install/manifest.json;
• opens the routing wizard.

The payload manifest owns the installed binaries, compatibility aliases, configuration templates, public presets/instruments/kits/loops/demos, profiles, and documentation. The distribution package manager owns synthv1, Yoshimi, FluidSynth, TimGM, and their libraries. The musician owns every generated XDG configuration, Project, Idea, recording, imported loop, controller map, and private preset/package; those paths are never adopted into the system manifest.

On stock Raspberry Pi OS, the routing wizard asks for a stable ALSA card name such as A96, never a numeric card order. After showing the exact JACK command, it offers one SHR-managed boot service by default. The service is enabled but not started during setup, runs as the musician account, handles the headless session-bus boundary, and can be removed with sudo shr-audio-tune jack-remove. Existing Patchbox or administrator JACK services are detected and retained unchanged.

Before changing packages or services, the installer prints the enabled phases and the exact per-user FluidSynth masking consequence. --plan performs the dependency preflight and exits without packages, policy, builds, installation, or setup. --yes is the explicit non-interactive acceptance for the grouped prompts; without it, a non-terminal invocation refuses to mutate the system. If interactive setup is interrupted, its phase summary distinguishes completed, possibly partial, and not-started work and prints exact rerun or recovery commands for recorded side effects. If installation stops after package mutation begins, it names sudo dpkg --configure -a, the idempotent rerun, the exact FluidSynth unmask, and permission-ledger recovery as applicable instead of attempting to roll package-manager state back.

After package consent, the dependency installer masks the exact per-user fluidsynth.service that its package enables. At the start of interactive routing, setup checks that mask and detects the system-wide amidiminder.service blanket MIDI patcher. When either known conflict remains, a separate default-no choice stops and masks only those exact units. It does not uninstall FluidSynth, stop JACK, disconnect arbitrary routes, or prevent SHR from launching its own FluidSynth process when a SoundFont sound is loaded. The prompt is skipped when both units are absent or already masked.

To deliberately restore those distribution services later:

systemctl --user unmask fluidsynth.service
sudo systemctl unmask amidiminder.service

Unmasking permits them to run again; start or enable them separately only when their automatic audio/MIDI behavior is actually wanted.

Use --no-deps to keep the installer from installing system packages. Use --no-config to skip the routing wizard. Preview or explicitly accept the grouped prompts with:

./scripts/install.sh --no-deps
./scripts/install.sh --no-config
./scripts/install.sh --plan
./scripts/install.sh --yes

Installed commands#

• shr opens SHR-DAW and provides its command-line tools.
• shr-setup opens the routing wizard.
• shr-audio-tune manages optional Raspberry Pi audio CPU tuning.
• moj-sint is the pinned managed synthesis host.
• shr-sampler is the pinned managed sample-package host and offline validator.
• shs and synth-player are compatibility names for shr. They use the same Rust engine ownership, routing, and shutdown path as the main command.

The product and Cargo package are named shr-daw. The main command is shr. Existing shsynth configuration and data paths are kept for compatibility.

Repository-local evaluation#

Contributors can build and inspect the checkout without installing files:

cargo build --locked
SHSYNTH_STATE_DIR=/tmp/shr-daw-judge-state target/debug/shr config init
SHSYNTH_STATE_DIR=/tmp/shr-daw-judge-state target/debug/shr list
python3 scripts/render-readme-screenshots.py --check

This path does not start JACK or transmit MIDI. Delete the explicit temporary state directory afterward. For a persistent private development checkout, ./scripts/setup-local.sh and ./scripts/local.sh redirect configuration, Projects, Ideas, recordings, loops, and private presets below ignored $SHSYNTH_USER_DIR/. They read the public kits directly from tracked kits/, and copy missing public presets, starter loops, and demo Projects without replacing private files. Build the release binary first; neither helper installs packages or builds the program. local.sh launches this checkout's target/release/shr, which carries the visible REL badge. Developers can explicitly set SHSYNTH_BIN=target/debug/shr for a DEV launch.

Upgrade and uninstall boundaries#

Rerunning the same source snapshot is idempotent. A newer checkout or tag first verifies that every previously owned file still matches its recorded hash, then replaces only changed managed files and removes only obsolete unchanged managed files. An identical pre-existing file can be adopted; a differing unowned file or a locally modified managed file stops the update before mutation. An interrupted file transaction retains private backups and a pending journal; the next apply rolls it back before preflight and retry. Package installation, service masking, real-time policy, and CPU tuning are separately idempotent. Existing XDG configuration, controller learning, Projects, Ideas, loops, recordings, and private presets/packages are never payload members and are not reset.

For a default /usr/local installation, run the installed manifest owner:

sudo /usr/local/libexec/shr-daw/managed_install.py uninstall

sudo make uninstall from the matching source checkout invokes the same operation.

This manifest-driven command removes only unchanged files owned by the last successful payload. It refuses to delete a managed file changed afterward, removes owned directories only when empty, and preserves unrelated files in a shared directory. It deliberately preserves user data under ${XDG_STATE_HOME:-~/.local/state}/shsynth/ and ${XDG_DATA_HOME:-~/.local/share}/shsynth/, Moj Sint user sounds under ${XDG_DATA_HOME:-~/.local/share}/moj-sint/, repository-local $SHSYNTH_USER_DIR/, system packages, JACK policy, and setup backups. Optional CPU/audio tuning is also a separate explicit system change; inspect/remove it with shr-audio-tune before uninstalling the command if desired. Never delete those retained directories unless their Projects, Ideas, recordings, loops, and private presets have been reviewed and backed up.

make install-files is a staging-only target and refuses an empty DESTDIR; live installation goes through the transactional helper. The complete hardware-free validation builds a disposable payload and applies, reapplies, updates, recovers, and uninstalls it under a disposable root. No nested Git repository is copied into the runtime tree.

JACK#

JACK must be running before loading a software synth, playing WAV loops, or recording audio. The browser and external-MIDI tracker can start without JACK.

On Patchbox, setup detects and retains the shared jack.service and its /etc/jackdrc; it does not create a competing owner. When no system service or live jackd process owns JACK, setup can create a backed-up ~/.jackdrc for the musician's next explicit JACK start. It never enables, starts, stops, or restarts JACK. Choose a sample rate that matches the WAV loops you intend to use, normally 48000 Hz for the installed cleared loops. Every active Loop Mix slot must also have an interpreted BPM matching its owning Pattern tempo; SHR-DAW stops/faults that slot on mismatch rather than time-stretching or allowing drift, while MIDI and healthy slots continue. Three periods is the safe USB default; lower latency should be earned with xrun measurement.

Optional dedicated audio CPU#

On a Raspberry Pi with at least four cores, the setup wizard can reserve one CPU for JACK and the one software synth managed by SHR-DAW. The wizard asks before making this system-wide change and defaults to no. If accepted, it runs the managed tuning helper immediately; boot-time isolation takes effect only after the user reboots.

The purpose is predictable real-time scheduling under demanding simultaneous playback and recording, such as an 18-input/18-output session. Keeping normal tasks and most interrupts off the audio CPU reduces the chance that a compiler, desktop task, or unrelated device delays JACK at the wrong moment. The tradeoff is deliberate: normal work has one fewer CPU until the profile is removed and the Pi is rebooted. Rust linking is largely serial, so it is often the longest build stage either way; parallel compilation can be somewhat slower with one of four CPUs reserved. Stopping JACK alone does not return an isolated CPU to general scheduling.

The optional profile:

• pins JACK and the managed synth to the selected CPU;
• uses isolcpus=domain,managed_irq,CPU and keeps default IRQ affinity on the housekeeping CPUs;
• adds nohz_full and RCU callback offload only when the installed kernel was built with their required options;
• enables a managed performance governor service for the next boot without changing the live governor during setup;
• records exact boot tokens and file hashes in /var/lib/shr-audio-tune/;
• refuses to replace CPU isolation settings it did not create.

Preview, diagnose, recover, or remove the managed settings with:

shr-audio-tune plan 3
shr-audio-tune status
shr-audio-tune doctor 3
shr-audio-tune jack-plan shome A96 48000 128 3
sudo shr-audio-tune jack-remove
sudo shr-audio-tune recover
sudo shr-audio-tune remove

After removing them, clear audio.engine_cpu in shsynth.conf and reboot. CPU isolation leaves fewer cores for normal system work. It can improve audio scheduling, but it cannot prevent every xrun caused by hardware, firmware, or an unsuitable JACK buffer size.

The full setting-by-setting decision matrix, Patchbox versus stock baseline, rollback rules, rejected folklore, and primary-source provenance are in Raspberry Pi audio-system optimization.

Continue with First run.

Back to detailed guides

This is the supported clean-storage path for the planned SHR-DAW Raspberry Pi 5. It installs a fresh official Raspberry Pi OS Lite 64-bit image directly on the NVMe drive. Do not clone the Pi 4 microSD system or copy its tuning files.

This procedure is for a Raspberry Pi 5 NVMe drive connected through the PCIe connector. The planned SHR-DAW assembly uses a bottom-mounted NVMe base, not a top-mounted M.2 HAT. The top of the Pi is reserved for the 480×320 display, which connects through GPIO rather than HDMI. A Raspberry Pi 4 has no equivalent native-NVMe connector; an NVMe drive attached to a Pi 4 boots as USB mass storage and follows a different path.

Before writing the drive#

You need:

• a Raspberry Pi 5, suitable power supply, active cooler, bottom-mounted PCIe-to-NVMe base, and compatible NVMe drive;
• a temporary Raspberry Pi OS SD card or a USB NVMe enclosure connected to another computer; and
• Raspberry Pi Imager.

Disconnect power before fitting or removing the base, ribbon cable, or drive. Install the active cooler first. Follow the base manufacturer's ribbon orientation and mounting instructions. Raspberry Pi's M.2 HAT+ photographs are not assembly instructions for this bottom-mounted base. Keep the GPIO header and the space above the Pi available for the display.

The write operation below erases the selected NVMe completely. Disconnect other removable drives when practical, and identify this one by both model and capacity before accepting Imager's warning.

Write Raspberry Pi OS Lite 64-bit#

The shortest path is to put the NVMe in a USB enclosure and run Imager on another computer. If no enclosure is available, use this staging path:

1. Use the familiar SD-card procedure to create a temporary Raspberry Pi OS with Desktop card. Boot the Pi 5 from it with the NVMe base installed.

2. Confirm that the NVMe is visible:

   lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS
   ls -l /dev/nvme*
   

   The whole drive normally appears as /dev/nvme0n1. Stop if the model or capacity is not the intended drive.

3. Install and open Raspberry Pi Imager:

   sudo apt update
   sudo apt install rpi-imager
   rpi-imager
   

Whether Imager runs on the Pi or another computer, make these selections:

1. Device: Raspberry Pi 5.
2. OS: Raspberry Pi OS Lite (64-bit).
3. Storage: the NVMe drive whose model and capacity were just confirmed.
4. Customisation: set the intended hostname, musician account, locale and timezone. Enable SSH and install the normal public key or password needed for headless access. Configure Wi-Fi if Ethernet will not be available.
5. Review the storage name once more, accept the erase warning, and let Imager finish both writing and verification. Do not skip verification.

For a reproducible acceptance record, note the Imager version, OS selection and date. After first boot, record /etc/os-release, uname -m, uname -r, the bootloader version, and the source revision installed. If a downloaded image was selected with Use Custom, also retain its exact filename and checksum.

First NVMe boot#

1. Shut the staging system down cleanly:

   sudo poweroff
   

2. Disconnect power and remove the temporary SD card. Keep it unchanged until the NVMe boot has been verified.

3. Reconnect power. With no bootable SD card inserted, a Raspberry Pi 5 should boot automatically from an NVMe drive on a compatible M.2 adapter.

4. Connect over SSH and prove that this boot is using the NVMe:

   findmnt -no SOURCE /
   lsblk -o NAME,SIZE,MODEL,FSTYPE,MOUNTPOINTS
   uname -m
   cat /etc/os-release
   

   The root filesystem should resolve to an NVMe partition, normally /dev/nvme0n1p2, and uname -m must report aarch64. Do not continue with SHR-DAW installation if the root filesystem is still on the SD card.

Continue with the normal SHR-DAW installation. Treat the Pi 5 as a new machine: do not copy the Pi 4 boot command line, systemd drop-ins, JACK configuration, runtime configuration, or Cargo output.

If the Pi does not boot from NVMe#

Keep changes narrow and test one cause at a time:

1. Reinsert the staging SD card, boot it, and rerun the lsblk and /dev/nvme* checks. If the NVMe is absent, power down and inspect the adapter, ribbon seating and orientation, drive seating, and power supply.

2. If the drive is visible, run:

   sudo raspi-config
   

   Choose Advanced Options → Boot Order → NVMe/USB boot, finish, and reboot.

3. If the bootloader is old, inspect it first:

   sudo rpi-eeprom-update
   

   Apply an available normal update with sudo rpi-eeprom-update -a, then reboot. Do not rewrite EEPROM configuration merely because NVMe exists.

4. Do not assume that this bottom-mounted base is discovered like an official M.2 HAT+. Follow the exact base manufacturer's instructions. A non-HAT+ design may require dtparam=pciex1 in /boot/firmware/config.txt and PCIE_PROBE=1 in EEPROM configuration. Apply those only when the exact adapter documentation requires them.

5. Leave PCIe at the supported Gen 2 speed. Raspberry Pi does not certify Pi 5 PCIe Gen 3 operation, so dtparam=pciex1_gen=3 is unsuitable as an installation default and especially unhelpful while diagnosing audio reliability.

Do not re-image repeatedly before checking the boot diagnostics, NVMe visibility, adapter requirements, and boot order. Do not edit the NVMe's cmdline.txt by hand to substitute device names; Raspberry Pi Imager writes the partition identifiers needed by the image.

Authoritative references#

• Raspberry Pi's M.2 HAT+ NVMe boot procedure, used here for Pi 5 boot behaviour only; its physical HAT assembly does not describe the SHR-DAW NVMe base.
• Raspberry Pi's operating-system installation with Imager.
• Raspberry Pi's NVMe boot order and PCIe configuration.

Back to detailed guides

This document owns SHR-DAW's installation and host-optimization decisions. It separates what is configured from what the running kernel, services, and processes actually do. It is not a generic Linux-audio tuning checklist.

Evidence labels used below are:

• observed: current repository source, isolated fixtures, or direct read-only inspection of the development Pi;
• authoritative: the primary sources listed under Provenance;
• project judgment: a conservative SHR-DAW choice where no source proves a universal performance win;
• physical gate: requires a real Pi/interface workload and is not proved by fixtures.

Supported motion#

On both platforms, install.sh shows consequences before changes. Package and service changes require one explicit consent; --yes is the non-interactive equivalent. Real-time permission changes are a separate consent. shr-setup then detects an existing JACK owner, live RT limits, CPU topology, kernel features, and existing tuning before it offers changes. Every system-changing setup choice defaults to no.

Patchbox OS already supplies a shared system jack.service, /etc/jackdrc, the jack service account, RT service limits, and usually the Debian @audio PAM limits. SHR retains that ownership and lifecycle. It may add only its separately owned CPU-affinity drop-in and performance/isolation profile after consent. Patchbox documentation still advertises an old RT-kernel image, so the name “Patchbox” is never accepted as proof that the installed kernel is RT, full-tickless, or otherwise tuned.

Stock Raspberry Pi OS Lite 64-bit receives the required packages, Debian/JACK RT policy and audio-group membership when missing and accepted, and a stable-name JACK choice. With no existing or live owner, setup offers one marked, reversible boot service so keyboardless use works after reboot; declining it writes a backed-up ~/.jackdrc fallback. The optional dedicated-CPU profile is the same managed profile on both systems.

shr-audio-tune plan is read-only. install never starts or restarts JACK and now enables the governor service without starting it live. A reboot activates boot isolation and starts that governor service. doctor reports persistent intent and live state separately. recover rolls an interrupted transaction back. remove deletes only exact owned boot tokens and unchanged owned files; later administrator edits are retained.

Optimization matrix: baseline and decision#

ID	Candidate and change	Current SHR implementation	Patchbox baseline	Stock Lite 64 baseline	Detection	Decision, measurable benefit, and overlap
A1	RT scheduling: rtprio=95, unlimited memlock	Installer/setup can call owned permissions-install; doctor checks files and the live login separately	Debian audio.conf and JACK unit limits were observed correct	jackd2 can install audio.conf; current login may still lack policy until logout	Parse every limits file; inspect user group and live limits	Necessary. Enables JACK/client FIFO scheduling and memory locking. It does not require an RT kernel. Unit limits do not replace client-user PAM limits.
A2	Audio group and file capabilities	Owned membership is added only after consent; no executable capabilities are added	Development user is already in audio and jack	Image/user groups vary; never assume	/etc/group, id, /proc/self/limits; inspect unexpected file capabilities if diagnosing	Audio group necessary when PAM policy uses it. Capabilities rejected. CAP_SYS_NICE/CAP_IPC_LOCK on broad binaries expands privilege and duplicates scoped limits.
A3	PREEMPT versus PREEMPT_RT kernel	Doctor reads the installed kernel config, not uname text alone	Current Pi is CONFIG_PREEMPT=y, not RT; old Patchbox docs are stale	Current Raspberry Pi OS kernels vary by release/model	/boot/config-$(uname -r), /proc/config*, /sys/kernel/realtime when present	PREEMPT is supported; PREEMPT_RT is optional, not required. Test RT only against a measured workload; Raspberry Pi maintainers describe RT builds as experimental.
A4	CPU frequency governor	Owned oneshot service records/restores governors and selects performance at boot	Not a guaranteed Patchbox property; current development Pi uses the ordinary dynamic governor	Usually dynamic governor	Service configured/active state plus every policy's live scaling_governor; frequency/throttle telemetry is separate	Optional with dedicated-core profile. Removes frequency-selection delay/jitter; costs power and heat. schedutil already raises frequency for RT tasks, so benefit must be measured.
A5	isolcpus=domain,managed_irq, irqaffinity, housekeeping set	Managed boot tokens; JACK drop-in; managed synth inherits audio.engine_cpu; ordinary SHR/writers/builds stay elsewhere	Not assumed; current development Pi removed its SHR-owned CPU 3 profile for four-core build throughput	Absent by default	Selected boot file, /proc/cmdline, /sys/devices/system/cpu/isolated, IRQ masks, JACK and synth process affinity	Optional, retained design for measured demanding 18×18 work. Stronger than affinity alone because unrelated scheduler work is excluded. Costs one general/build CPU until removal and reboot, so the four-core development default is shared CPUs.
A6	nohz_full and rcu_nocbs	Now conditional on CONFIG_NO_HZ_FULL and CONFIG_RCU_NOCB_CPU; owned stale tokens are removed on repeated install	Current Pi's 6.12 kernel rejects both despite their command-line text	Often not built in	Kernel config, boot log, live nohz sysfs, and configured/live command lines	Conditional only. Can reduce tick/RCU jitter, but adds no benefit when unsupported. nohz_full already offloads RCU callbacks, making a separate rcu_nocbs token partly redundant on supporting kernels.
A7	systemd CPUAffinity, AllowedCPUs, RT/memlock/scheduling directives	The optional dedicated profile's JACK drop-in uses CPUAffinity, LimitRTPRIO, LimitMEMLOCK; JACK itself requests FIFO priority	Patchbox JACK unit already provides RT/memlock; SHR adds affinity only with the dedicated profile	Managed stock service consumes the same drop-in when chosen	Unit fragment/drop-ins, systemctl show, MainPID, /proc/PID/status and limits	Keep CPUAffinity only with an intentionally installed dedicated profile; always keep the required RT/memlock limits. Reject duplicate AllowedCPUs and forced unit FIFO. AllowedCPUs is a cgroup cpuset control with parent constraints; affinity already supplies the required process placement. JACK owns its RT-thread policy.
A8	JACK owner and boot lifecycle	Detect/retain external owner; otherwise offer one marked boot service or .jackdrc fallback; no setup start/restart	Shared system service enabled at boot is intended and retained	Managed service offered after stable hardware/timing selection	Unit fragment, enabled/active/failed state, process count, headless environment, ownership hashes	One owner only. Retain external ownership; make stock keyboardless boot deterministic; reject live/duplicate owners and later administrator edits.
A9	JACK device, rate, period, periods, priority, timeout/watchdog	Setup rejects numeric cards, validates timing, and doctor compares configured/live commands plus connected stable name	/etc/jackdrc is Patchbox-owned; current measured setting is 48 kHz, 128, 3, priority 95	Stable ALSA name and timing are selected interactively	Exact command, /proc/asound/cards, unit process arguments, jack_lsp, logs, xruns	48 kHz and three periods are safe USB defaults; period size is workload-specific. Names survive USB order changes. Larger periods lower xrun risk and raise latency.
A10	IRQ placement, threaded IRQs, USB topology	Default IRQ affinity excludes audio CPU; no per-device IRQ rewriting	Current USB host IRQ is effectively on housekeeping CPU; Pi kernel exposes forced-threading support	Hardware/kernel dependent	/proc/interrupts, default/effective affinity, kernel config, lsusb -t	Global housekeeping mask retained. Per-IRQ/rtirq recipes rejected by default. Moving the wrong storage/network/timer IRQ can reduce reliability; managed IRQ affinity is best-effort and topology-specific.
A11	USB audio/MIDI autosuspend	Detect only; no global udev or usbcore.autosuspend=-1 rule	Current leaf audio/MIDI devices are observed power/control=on	Device/driver dependent	USB topology, per-device power/control, disconnect/reset logs	No blanket change. Disable autosuspend only for an identified device with measured suspend/reset failures. Global disable costs power and can mask another fault.
A12	PipeWire, PulseAudio, FluidSynth, MIDI auto-patchers	Exact FluidSynth/amidiminder units are offered for masking; unrelated services remain	Shared JACK can coexist with PipeWire/Pulse when they do not own the same ALSA device; current standalone synth/router units are masked	Desktop services may be absent on Lite	Unit/process owner, ALSA device use, JACK-provider/process count, routes	Prevent duplicate owner, not package presence. Mask exact known synth/router conflicts only after consent. Do not call active PipeWire alone a duplicate JACK server.
A13	Swap, zram, swappiness	No changes	Current Pi has a small swap file and default swappiness	Image/release dependent	swapon, zramctl, memory/swap pressure, OOM and callback measurements	Retain OS policy. Zram may help memory pressure but consumes CPU; disabling swap can turn pressure into OOM. No measured audio win supports a universal value.
A14	Dirty writeback sysctls	No changes	Current defaults retained	Kernel defaults	Configured/live sysctls, writer high-water, fsync time, drops, storage latency	Reject generic ratios/intervals. Lower thresholds may smooth bursts but increase ongoing I/O; higher thresholds enlarge durability loss and later stalls. SHR's bounded writer and fsync/publication contract is the owner.
A15	Filesystem, microSD/NVMe, mount advice	Recording uses bounded writers, fsync, manifests, and atomic no-replace publication; no mount changes	Current Pi 4 evidence is microSD; Pi 5 NVMe remains unmeasured	Storage chosen by user	Mount source/options, free space, SMART/NVMe data where available, recorder stress and real-device tests	No universal mount tweak. NVMe should improve throughput/endurance but requires physical measurement. Never trade fsync/durability for benchmark latency.
A16	journald/log suppression	No changes	Retained	Retained	Persistent/volatile mode, disk use, rate-limit drops, service logs	Retain logs. Logs are required for JACK, power, USB and recovery diagnosis. Rate/size policy may be adjusted only for demonstrated storage pressure.
A17	cooling, throttling, power supply	Doctor/state inspection can report evidence; tuning does not overclock	Current Pi showed no throttle flags during this audit; temperature is only a momentary observation	Hardware/supply/cooling dependent	vcgencmd get_throttled, thermal sysfs, kernel undervoltage messages, sustained workload	Necessary operational prerequisite, not a software “optimization.” Performance governor raises power/heat; active cooling and a suitable supply prevent clocks being capped.
A18	clock stability, high-resolution timers, tick rate	Detect kernel capability; do not set clocks/timers	Current kernel has high-resolution timers and 250 Hz base tick	Kernel dependent	Kernel config, clocksource, latency/xrun measurements	Retain kernel defaults. Audio clocks come from the interface/JACK rate. Overclocking, arbitrary timer-source switches, and HZ=1000 rebuilds lack evidence here.
A19	Disable networking/Bluetooth/SSH/services	No blanket disabling	Patchbox uses networking for remote control/modules; SHR Help can use LAN	Lite may need SSH, updates and remote setup	Actual IRQ/CPU/network load during reference workload	Rejected by default. Product and recovery cost is immediate; benefit is unproved. Isolate a demonstrated offender only for a named performance session.
A20	MIDI/controller background services	SHR owns selected inputs/routes and consumes command-pad on/off; setup masks only exact conflicting auto-services	Patchbox may supply amidiauto/amidiminder-style routing	Usually absent unless installed	ALSA clients/routes, exact units, selected controller/performance roles	Exact ownership required. Prevent doubled notes/unintended routes without disabling unrelated MIDI hardware or transmit paths.
A21	Shutdown, All Notes Off, interruption and restoration	Existing bounded shutdown sends all-channel panic, stops only owned engines, restores owned routes; tuner has transaction recovery	Retained	Same application contract	Process/route snapshots, recovery fixtures, physical tests only with approval	Necessary safety invariant. Optimization may not bypass cleanup, kill unowned engines, or replace durable recording publication.
A22	Pi 4/Pi 5, 32/64-bit, boot layout	Contiguous topology required; both command-line locations supported; Pi optimization refuses non-aarch64	Pi image/history varies; current Pi 4 is aarch64 and uses /boot/firmware	Current official Lite target is 64-bit; Bookworm/Trixie use /boot/firmware while older images may use /boot	Architecture, model, online CPU list, actual boot files, config-selected cmdline, kernel release	64-bit Pi 4/5 supported path. Refuse unusual/hotplug layouts. Never edit both boot files or infer the live file from version alone.

Mechanics, persistence, recovery, and validation#

IDs	Correct mechanism and persistence	Default / consent	Backup, ownership, idempotency, rollback	Doctor and validation
A1–A3	Use distro limits when sufficient; otherwise helper-owned 95-shr-audio.conf and audio membership. Login boundary activates PAM policy. Kernel replacement is outside normal setup.	RT policy prompt: no. RT kernel: never automatic.	Record user, pre/post group hashes and policy hash. Removal touches only matching owned state; later group/limits edits are retained.	Files versus current group/live limits; fixture missing policy, repeat, removal and admin edit; real JACK RT success remains physical/live validation.
A4–A7	One managed governor service; boot tokens in the one detected cmdline; JACK systemd drop-in. Reboot for isolation/governor; next JACK start for affinity.	Dedicated profile prompt: no, after read-only preview.	Original cmdline retained; manifest records exact tokens and hashes. Same-CPU repeat converges. Transaction rollback/recover handles failures. Removal deletes exact tokens/files only.	Boot file, /proc/cmdline, sysfs isolation/nohz, kernel config, service configured/active, process affinity/limits. Fixtures cover both boot paths, conflicts, unsupported features/topology, retry and reboot.
A8–A12, A20	Preserve one JACK owner. Patchbox/admin owners remain untouched; stock setup offers marked /etc/jackdrc plus jack.service, with .jackdrc fallback only when declined. Exact service masks only.	Existing owner retained. Managed stock service defaults to yes only after explicit hardware/timing selection; setup never starts it.	Hash ledger, idempotent same-value install, collision refusal, live-removal refusal, exact remove; user fallback is dated before replacement.	Unit enabled/active/failed state, headless reservation environment, stable connected card, command drift, process count/affinity, routes and ports. Fixtures cover lifecycle and Trixie reservation failure without hardware operations.
A13–A19	Observe OS/storage/power state; apply no generic persistent change.	No prompt because no change is proposed. Workload-specific experiments require a new explicit request and baseline.	OS/admin ownership remains intact.	Synthetic recorder/final-mix tests are storage/software evidence only; real interface, power, thermals, IRQ and xrun acceptance require the exact Pi workload.
A21–A22	Application owns engine/route/recording recovery; helper owns only its ledger. Boot path and CPU topology are discovered each run.	Safety cleanup is automatic for owned state; hardware tests require explicit permission.	No user data or unrelated routes/processes are touched.	Fixtures plus existing shutdown tests; real Pi 4/Pi 5 and 18×18 acceptance remain physical gates.

Workload effects and tradeoffs#

Setting	Audio	Compilation	Network/general use	Storage/durability	Power/thermals	Maintenance
Dedicated CPU and IRQ housekeeping	Expected lower worst-case scheduler/IRQ interference; high-channel benefit must be measured	Three rather than four general CPUs; parallel compile can slow; final Rust link remains mostly serial	One CPU permanently unavailable until removal/reboot	Writer stays on housekeeping CPUs	Performance governor increases draw/heat	Strong boot-time protection, but requires kernel-aware doctor and reboot
Full tickless/RCU offload when supported	May further reduce OS jitter	Negligible direct gain; more housekeeping work elsewhere	Can complicate general-purpose tuning	No durability change	May change idle efficiency	Kernel-build dependent; unsupported text is harmful false confidence
Performance governor	Avoids frequency ramp delay	Faster sustained compile while active	Less energy-efficient general use	No direct durability change	Higher heat and supply demand	Managed service restores prior values when stopped
RT limits/memlock	Required for reliable low-latency JACK/client threads	No material effect	Grants selected users elevated scheduling/locking rights	Prevents paging of locked audio memory	Can let a broken RT task monopolize CPU	Scoped group policy, explicit consent and logout boundary
JACK buffer/rate	Smaller period lowers latency but raises deadline risk; three periods is robust for USB	None	None	Higher channel/rate increases recording bandwidth	More callback work at small periods	Must match device and material; validate xruns, not folklore
Rejected generic VM/filesystem/service tweaks	No established benefit	May reduce build/cache/network convenience	Can break SSH, updates, Bluetooth, desktop or remote Help	May weaken fsync durability or create write bursts	Often trades power for unproved latency	Avoids a second hidden system-policy owner

Provenance#

Primary sources supporting policy-affecting claims:

• Linux kernel command-line parameters: https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html (isolcpus, managed_irq, nohz_full, rcu_nocbs, irqaffinity and their required build options).
• Linux CPU isolation guide: https://docs.kernel.org/admin-guide/cpu-isolation.html.
• Linux CPU frequency policy/governors: https://www.kernel.org/doc/html/latest/admin-guide/pm/cpufreq.html.
• Linux VM/writeback sysctls: https://www.kernel.org/doc/html/latest/admin-guide/sysctl/vm.html.
• Linux USB runtime power management: https://www.kernel.org/doc/html/latest/driver-api/usb/power-management.html.
• systemd execution and cgroup controls: https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html and https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html.
• JACK real-time setup: https://jackaudio.org/faq/linux_rt_config.html; JACK/Debian option semantics: https://manpages.debian.org/bookworm/jackd2/jackd.1.en.html.
• Debian JACK policy: https://wiki.debian.org/JACK and the installed jackd2 package's /etc/security/limits.d/audio.conf.
• Raspberry Pi boot layout and live command line: https://www.raspberrypi.com/documentation/computers/configuration.html; kernel/config selection: https://www.raspberrypi.com/documentation/computers/config_txt.html.
• Raspberry Pi power, thermal and throttle reporting: https://www.raspberrypi.com/documentation/computers/os.html#vcgencmd and https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply.
• Official Raspberry Pi OS image generator: https://github.com/RPi-Distro/pi-gen.
• Patchbox shared-JACK baseline and current configuration model: https://blokas.io/patchbox-os/docs/ and https://github.com/BlokasLabs/patchbox-os-debs/tree/master/blokas-jack.

The development Pi audit on 2026-07-24 observed Debian 12/Patchbox packages, arm64 Raspberry Pi kernel 6.12.93+rpt-rpi-v8, CONFIG_PREEMPT=y, CONFIG_NO_HZ_FULL unset, CONFIG_RCU_NOCB_CPU unset, active scheduler-domain isolation of CPU 3, default/effective IRQ housekeeping on CPUs 0–2, active performance governor, one Patchbox-owned JACK server confined to CPU 3 with FIFO priority 95, correct RT/memlock limits, and no current throttle flag. Its boot log explicitly rejected nohz_full=3 and rcu_nocbs=3; this is machine evidence for the repaired feature detection, not a universal Raspberry Pi kernel claim.

On 2026-08-29 the owner removed that optional profile on the four-core development Pi because its build-throughput cost outweighed an unmeasured audio benefit in the current workload. The helper removed the persistent CPU/IRQ, governor, and JACK-affinity settings without restarting live JACK; the next normal reboot completes the transition to four shared CPUs. This machine choice does not remove the reversible profile or claim that isolation cannot benefit a later measured 18-channel workload.

Physical gates#

Fixtures prove file ownership, parsing, transaction, cancellation defaults and configured/live classification. They cannot prove xrun performance, USB stability, thermal headroom, supply quality, microSD/NVMe durability, Pi 5 behavior, or 18-channel recording/playback. Follow the focused measurement and MR18 plans after explicit hardware authorization. Do not convert a synthetic or read-only pass into a physical-support claim.

Back to detailed guides

This guide owns configuration keys, persisted route fields, and machine fallbacks. The Tracker guide owns the musical workflow, while the Controller interface owns visible actions.

Machine defaults and hardware fallbacks belong in shsynth.conf or controller.conf. Only a page deliberately bound to exact hardware stores that preferred target in a Project. Hardware names are never compiled into the program.

Both configuration files use one KEY=VALUE entry per line. A comment must start with # after optional leading whitespace; # inside a value is kept as part of a hardware name or path rather than treated as an inline comment.

The installed templates live under share/shsynth/. On first use, shr copies them without replacing existing files to ${XDG_STATE_HOME:-~/.local/state}/shsynth/. A repository-local launch uses the checkout's config/ and private $SHSYNTH_USER_DIR/ tree instead. Environment overrides are documented in Installation.

For an owned synthv1 child, SHR sets XDG_CONFIG_HOME to the managed engine's private config/ directory below that state root. This prevents synthv1 from writing into the caller's normal desktop configuration; a caller-supplied XDG_CONFIG_HOME is not used for that child process.

Runtime key reference#

Repeated midi.performance_input, audio.output, audio.internal_output, yoshimi.preset_root, yoshimi.category, fluidsynth.soundfont, shr_sampler.instrument_root, external_midi.channel, external_midi.percussion_note, capture.input, capture.track, and loop.output keys build ordered lists. Empty optional values disable that choice. The current parser accepts:

Group	Keys and constraints
Startup and status	synth.startup_timeout_ms; optional status.cpu_temperature_path
Display	display.note_names (german for B/H or english for A#/B)
synthv1	synthv1.command, .client, .presets, .midi_output; legacy synth.command, synth.client, presets.directory, and midi.synth_output remain accepted
Yoshimi	yoshimi.command, .client, .midi_output, repeated .preset_root and .category, .presets_per_category
FluidSynth	fluidsynth.command, .client, .midi_output, .gain, repeated .soundfont
Moj Sint	moj_sint.command, .client, .midi_output, repeated .preset_root, and exactly two .output short names
SHR Sampler	shr_sampler.command, .client, .midi_output, repeated .instrument_root, exactly two .output short names, and .validation_timeout_ms (1000–600000)
SHR Drums	drums.client, .kit_directory, and .maximum_callback_frames

Moj Sint defaults to command moj-sint, client/MIDI identity shs-moj-sint, and output short names out_l then out_r. Discovery indexes at most 512 regular, non-symlink .mojsint files of at most 1 MiB and strictly validates schemas 1–8 before showing them. Schema 8 adds the Dual Filter model, its exact 15-control fields, and persisted industrial/counter core state; schemas 1–7 remain readable and migrate in memory. Each discovered instrument keeps a model-qualified stable identity. The host is invoked only by LOAD as moj-sint --client-name NAME --preset FILE. Playback user saves add the private XDG Moj Sint preset root to discovery and store all six models beneath separate model directories. Repository-local launches keep that root below ignored $SHSYNTH_USER_DIR/. SHSYNTH_MOJ_PRESET_DIR may select another explicitly private root; public checkout, factory, system, and symlink paths remain read-only. The destination must be an absolute normalized path; symlinked roots, parents, model directories, and preset files are refused. Synthv1 uses the existing private SHSYNTH_PRESET_DIR override or its XDG user preset directory. Save New allocates the first unused User NNN name without replacement. Overwrite is available only for a regular numbered file in that private root. Serialization and strict format validation finish before atomic publication, so a failed save leaves the prior file, live values, held notes, and engine session unchanged.

SHR Sampler defaults to command shr-sampler, client/MIDI identity shs-shr-sampler, and exact outputs out_l then out_r. Discovery indexes at most 512 regular non-symlink .shrinst directories and reads a bounded top-level manifest for stable ID and display name. LOAD first checks the executable's shr-sampler VERSION response against the central compatibility contract and runs its strict offline validate PACKAGE command within the configured timeout. Only then may the exclusive owned-host replacement begin. The live invocation is shr-sampler --client-name NAME --instrument PACKAGE; SHR Sampler never auto-connects itself. Packages are read-only catalog entries, while Ideas persist their stable ID and configured path without copying sample content into private Project storage.

| Managed MIDI/audio | midi.autoconnect; legacy ordered controller fallbacks in repeated midi.input; midi.controller_musical_input; simultaneous repeated midi.performance_input; audio.autoconnect, exactly two preferred audio.output entries, ordered audio.internal_output=NAME|LEFT|RIGHT fallbacks, final optional audio.headphone_output=NAME|LEFT|RIGHT; optional audio.engine_cpu | | Owned final bus | audio.graph.enabled, .client, .maximum_callback_frames (1–4096), .input, monitoring confirmations | | External tracker MIDI | external_midi.enabled, .client, .output, .max_tracks, repeated .channel, .melody_channel, optional .percussion_channel and .percussion_program, .percussion_input_base, repeated .percussion_note, .bank_select (off, cc0, or cc0+cc32), .program_changes, .send_transport, .default_tempo (decimal 20.00–300.00), private .import_directory, .pattern_rows (1–256), .steps_per_beat (1–16), .live_thru, .profile, .gate_percent (1–100), .gesture_settle_ms | | Controller clock | controller_clock.enabled, .client, .output; disabled by default, with one exact stable ALSA MIDI output name required when enabled | | External transport input | external_clock.enabled, .input, .start (arrangement or pattern); disabled by default, machine-owned, and requires midi.autoconnect=true plus one exact stable ALSA MIDI input identity | | Synchronized capture | capture.directory, .client, repeated capture.track=ID|LABEL|GROUP|ROLE|ARMED|EXACT_SOURCE, legacy stereo capture.input=NAME|LEFT|RIGHT, .ring_frames (1024–4194304), .maximum_callback_frames (16–65536) | | WAV loop | loop.client, loop.import_directory, exactly two repeated loop.output entries when playback is used |

Boolean values are true or false; numbers and structured entries are rejected when malformed or out of range. Commands, clients, paths, and ports remain data: copy the template and change them for the actual machine instead of editing Rust constants.

The 18-channel Levels overview needs no additional key and adds no Project data. It uses the first 18 ordered capture.track records and their exact resolved sources. Fewer configured tracks remain visibly missing; extra tracks still belong to Audio Recorder setup/capture but are outside this fixed native overview. The recorder-owned meter and take clients are mutually exclusive and use capture.client; neither guesses a source or changes unrelated routes. Keyboard actions are built in, while physical menu/encoder messages continue to come from the selected controller profile or learned controller.conf mapping rather than a hardware name compiled into Rust.

FluidSynth loads every valid repeated fluidsynth.soundfont once when its owned process starts. List order assigns each file a non-overlapping effective MIDI-bank offset. Saved software routes include the configured SoundFont index, filename, bank, and program; an unambiguous filename/bank/program fallback keeps a Project usable if distinct SoundFonts are reordered. A missing or ambiguous required SoundFont/preset is refused rather than substituted.

display.note_names changes Playback chord roots, slash bass notes, and the held-note row together. It does not transpose MIDI or alter the keyboard-state positions. The default is german, matching the existing central-European B and H convention; english names those pitch classes A# and B. shr-setup asks with the two example scales C D E F G A B C and C D E F G A H C (B means B-flat) and writes this key.

Controller and performance MIDI inputs#

controller.conf input= is the active control-surface selector. Explicit MIDI Learn for a reviewed controller also saves controller-mappings/PROFILE-ID.conf beside it, so reconnecting a known model restores that model's private mapping instead of borrowing or destroying the mapping of the previously connected model. When controller.conf input= is empty, repeated midi.input= values are tried in order as legacy alternatives; they do not open multiple devices. The default midi.controller_musical_input=true preserves combined-device behavior: mapped commands are consumed and unmatched notes or performance messages pass to the active route. Set it to false for a control-only surface.

Each non-empty repeated midi.performance_input= is an independent musical source and is opened when available. Performance sources never enter controller command, encoder, mapped-control, or learning interpretation. The same exact resolved ALSA port may be named for both roles; SHR deduplicates it to one connection. Partial absence and ambiguous substring matches are reported per role without disabling the other inputs or the computer keyboard.

midi.autoconnect=true
midi.input=Control Surface MIDI
midi.controller_musical_input=false
midi.performance_input=Performance Keyboard MIDI
midi.performance_input=Second Keyboard MIDI

For a combined controller/keyboard, omit the performance entries and leave the controller musical setting true. For keyboard-only use, leave both controller selectors empty, set the controller musical setting false, and configure one or more performance inputs. external_midi.output is an output destination, not an input; one interface may safely be configured in both directions.

Stable ALSA endpoint identities and in-app editing#

Setup, runtime discovery, status, diagnostics, external output routing, controller clock, and the Routing screen share one deterministic identity policy. From AudioBox USB 96:AudioBox USB 96 MIDI 1 32:0, only the volatile trailing numeric address is removed; the stable configured value is AudioBox USB 96:AudioBox USB 96 MIDI 1. The legacy whitespace form AudioBox USB 96 AudioBox USB 96 MIDI 1 remains compatible only when unique. There is no substring/fuzzy fallback, and volatile numeric addresses are never written.

The Routing screen edits detached drafts. Confirming any row validates the whole runtime/controller candidate, creates backups, atomically saves, then replaces SHR-owned MIDI inputs without layering them. Activation failure restores the previous files and route. Merely browsing, highlighting, or confirming an output choice does not open that output or send MIDI. Audio- output changes are marked NEXT START and take effect on the next managed engine start. Controller-clock output changes also take effect on the next SHR start; MIDI input, controller-role, and external-transport input changes activate immediately while stopped. Startup does not silently migrate legacy names; canonical form is written only after a confirmed Routing edit. Every configured performance input has its own compact PERF n row and an explicit add row. Editing or removing one preserves all other entries, retained offline identities remain visible, and duplicates are refused.

Dedicated controller clock and transport#

The controller sync route is separate from every tracker page and from the managed instrument. It opens only the one exact standard-MIDI output selected by controller_clock.output; it never broadcasts and never falls back to a tracker, synth, DIN THRU, MCU/HUI, or ALV port. Its protocol is deliberately closed: F8 Timing Clock, FA Start, and FC Stop are the only bytes the connection can send. SHR uses directly addressed ALSA sequencer events from a non-exportable source port, so an automatic JACK bridge cannot subscribe to or copy the clock. It cannot send notes, CCs, bank/program selection, Song Position Pointer, feedback, identity requests, or configuration SysEx.

controller_clock.enabled=false
controller_clock.client=shs-controller-clock
controller_clock.output=

shr clock ports performs read-only output discovery. Each current: line is what ALSA reports now; the paired configure: value removes only the trailing volatile ALSA client address and remains an exact client-and-port-name match. If zero or multiple ports have that stable exact name, SHR leaves controller clock offline rather than guessing. For the MiniLab 3 choose its standard Minilab3 MIDI endpoint, never DIN THRU, MCU/HUI, or ALV.

SHR's transport is the authority. Every accepted FT2 Play, Play from start, or Record launch is a fresh run, so it sends one FA. Playback PLAY does the same for the live controller arpeggiator even when no MIDI take exists, and Playback RECORD starts that transport while capturing the generated notes. Playback STOP, FT2 Stop, and clean shutdown send FC when appropriate. SHR has no paused position that could truthfully use FB Continue. Pattern repeats remain one continuous transport and do not emit another Start. F2 Song Position Pointer is not used: the MiniLab arpeggiator needs tempo and run state, while SHR does not expose pause/continue or remote song-location semantics.

Timing Clock runs whenever the feature is enabled and SHR is open; Start and Stop follow the visible FT2 or Playback transport. Playback TAP changes the current Pattern/controller tempo but deliberately does not start transport; PLAY is the explicit start. Direct hardware validation found that the MiniLab must detect clock before it receives Start; sending Start before the first pulse left its External-Sync arpeggiator waiting. Continuous stopped-state clock is therefore the least surprising live-safe behavior. It lets the controller know the tempo before Play, while FC still stops its arpeggiator. When external_clock.enabled=true, the controller-clock worker is fully suspended—including stopped-state Timing Clock—so SHR cannot compete with or feed back the incoming owner. The next internal Play resumes its configured clock behavior. When controller clock is enabled, SHR permits an otherwise empty Pattern to run with FT2 transport; Playback can launch the live arpeggiator directly without a recorded take. Clock stays at 24 PPQN from the current transport tempo (or configured default tempo before the first run); cell timing, number of pages/destinations, and swing/event placement do not create or move pulses. A live tempo change preserves the remaining pulse phase, and a delayed worker skips missed deadlines instead of producing a catch-up burst.

External USB MIDI transport input#

external_clock.enabled=false
external_clock.input=
external_clock.start=arrangement

Routing exposes these as SYNC, SYNC IN, and SYNC POS. Enabling external sync requires one currently resolvable exact input; the saved value omits only the volatile trailing ALSA numeric address. Missing or duplicate stable identities remain visibly refused and never select a substitute. Hardware and source names stay in this machine configuration, never in a Project.

External mode follows F8 at 24 PPQN and accepts FA Start plus FC Stop. arrangement Start means Arrangement step 1, row 1; pattern means row 1 of the selected Pattern (or selected Live Pattern). Seven clocks establish a usable estimate, the valid tempo range is 20.00–300.00 BPM, and more than 500 ms without a pulse is loss. Stop, loss, source replacement, or fault requires clock reacquisition and a fresh Start; clocks alone never resume. Continue, Song Position Pointer, and clock thru are not implemented. See Priority 7 external transport sync acceptance for the exact filter, phase, cleanup, UI, output, and evidence contract.

Raspberry Pi setup, backup, verification, and rollback#

Run all of these on the Raspberry Pi. Do not use MIDI Control Center or write controller memory.

1. Stop SHR-DAW and any synth, then list ALSA subscriptions with aconnect -l. Run shr clock ports and identify the one configure: line paired with the MiniLab standard MIDI endpoint.
2. Back up the active shsynth.conf before editing it. For a normal install it is below ${XDG_STATE_HOME:-$HOME/.local/state}/shsynth/; for a checkout, use the private state path selected by scripts/local.sh. Give the copy a date-stamped name and do not replace an older backup.
3. Set controller_clock.output to that complete configure: value, then set controller_clock.enabled=true. Leave MiniLab arpeggiator Sync at External.
4. Run shr doctor. Start SHR and confirm aconnect -l shows the shs-controller-clock source as non-exportable with no subscriptions; its events are directly addressed rather than represented by an ALSA subscription. In Playback, press PLAY, enable the MiniLab arpeggiator, and play keys; STOP should end it without unloading the sound. Repeat with FT2 transport; no tracker page should target the controller.
5. To disable without losing the remembered endpoint, set controller_clock.enabled=false and restart SHR. Confirm the shs-controller-clock client is gone. To roll back completely, stop SHR and restore the dated backup of shsynth.conf.

The official MiniLab 3 manual states that External Sync takes arpeggiator rate from host tempo and requires clock plus host playback. The MIDI Association's MIDI 1.0 message summary defines Timing Clock as 24 per quarter note and distinguishes Start, Continue, Stop, and Song Position Pointer. These are protocol facts; the channel-10 pad mapping below is direct evidence from this Raspberry Pi/controller pair. Arturia's current MiniLab 3 support page documents the four separate ports, identifies MiniLab 3 MIDI as the standard port, and lists DAW Shift as CC27. The current directly learned default instead uses the connected unit's Shift CC9 and shifted encoder CC112; the earlier DAW-mode CC27/CC29 pair remains compatible. Its download page currently lists firmware 1.2.0. SHR does not infer the installed firmware or claim that a controller-side setting persists: the no-clock behavior and program/pad messages are observations of the connected unit in the stated test state.

Audio CPU isolation#

audio.engine_cpu is an optional zero-based CPU number. When set, SHR-DAW pins the one synth process it owns to that CPU before the process starts, allowing its JACK threads to inherit the same affinity. It deliberately does not pin the TUI, MIDI routing, or recording disk writer.

Do not set this key by itself and assume the CPU is reserved: ordinary kernel and user work can still run there. On supported Raspberry Pi installations, use sudo shr-audio-tune install CPU or the opt-in setup-wizard step. That tool records and backs up the boot command line, configures JACK affinity and the performance governor, and provides matching recover and remove operations. It applies full-tickless and RCU-offload boot keys only when the running kernel's build configuration supports them. It never starts or restarts JACK. Reboot after installing or removing the isolation settings. Use shr-audio-tune doctor CPU to compare recorded intent, persistent files, and live kernel/service state; a matching line in a file alone is not proof that a setting is active. See Raspberry Pi audio-system optimization.

Owned audio graph#

The SHR-owned JACK client sums whichever optional managed instrument, SHR Drums, and Loop sources are present plus one configured stereo capture pair. The melodic instrument retains its Project-persisted source insert rack and three aux buses. The complete sum then passes through the master rack, live master level, fixed Project MASTER STRIP, final meter, final stereo recorder tap, and playback. Automatic startup remains disabled by default; MTR Input MON ON explicitly starts this same bus for input-only monitoring:

audio.autoconnect=true
audio.output=system:playback_1
audio.output=system:playback_2
audio.graph.enabled=false
audio.graph.client=shr-graph
audio.graph.maximum_callback_frames=4096
audio.graph.input=External mix|system:capture_1|system:capture_2
audio.graph.input_direct_monitoring=false
drums.client=shr-drums
drums.kit_directory=
drums.maximum_callback_frames=4096
audio.graph.confirm_doubled_monitoring=false

The distributed setup fills an empty or legacy default drums.kit_directory with the installed public kit root, normally /usr/local/share/shsynth/kits. Repository-local helpers instead select the checkout's tracked kits/ tree. An explicitly configured non-default directory is preserved, and SHSYNTH_KIT_DIR can deliberately select another root before setup or launch. The four public package directories are governed by kits/cleared-kits.txt; factory kits are never copied into private $SHSYNTH_USER_DIR/ storage.

Exactly two audio.output entries are the preferred direct route and the graph's main destinations. audio.graph.input is LABEL|LEFT|RIGHT; both JACK capture names are resolved exactly. If it is absent, the first legacy capture.input supplies a backward-compatible preference. Missing, ambiguous, or identical ports keep the bus visibly unavailable—SHR-DAW never picks a nearby name. This key assigns the two ports only: MTR's live Input control chooses stereo or dual mono and the two dual-mono pans without rewriting configuration or raw recorder tracks. The callback frame bound may be 1–4096 and must cover the active JACK period; an unexpectedly larger callback faults final recording and writes safe silence rather than overrunning fixed memory.

Input software monitoring starts OFF every time. MON ON requires only the exact input and playback pairs; no synth, Loop, or drum source is launched or required. Present optional sources are connected to their fixed graph inputs and their exact owned direct links are removed transactionally. Missing optional sources remain silent and can attach later; disappearance removes only that source, and the same exact ports reconnect when they return. Activation failure leaves monitoring OFF and restores the prior owned links. Shutdown restores only available owned direct links; unrelated JACK clients and connections are not changed.

A managed engine is ready only after one client resolves to exactly two unambiguous JACK audio outputs; the presence of a MIDI port is insufficient. SHR first prefers the exact configured client, then accepts one unique prefixed client such as Yoshimi's generated yoshimi-<configured-name> form. Zero or multiple client matches and a non-stereo output set are surfaced as errors. Direct playback uses SHR's checked JACK client API, accepts an exact connection that the managed synth has already established, and surfaces every other connection failure. A host that publishes its port names before becoming active may settle and retry only within the one configured startup deadline.

Physical MIDI configuration uses stable exact ALSA identities. The three managed-backend .midi_output values additionally retain their historical short-selector behavior: the selector must occur in exactly one live destination published by the owned synth. Zero or multiple matches fail instead of choosing a nearby endpoint.

Software monitoring means the configured capture pair passes through the final bus and adds JACK-buffer plus complete strip latency: 133 samples (2.770833 ms) at 48 kHz or 123 samples (2.789116 ms) at 44.1 kHz. Interface direct monitoring is outside SHR-DAW. If both are declared, MON ON is refused unless audio.graph.confirm_doubled_monitoring=true deliberately acknowledges the doubled/comb-filtered path. SHR cannot change the interface hardware monitor control. See Final performance bus.

The FX rack/editor remains available while the bus is inactive, and those validated Project edits do not publish a runtime plan. With the bus active, stop transport and all recording before an FX change can rebuild and publish the owned graph. Projects save their racks in either mode, but direct playback does not process or meter them.

The fixed MASTER STRIP is reached from the MASTER FX context and MTR. Its numerical controls and smoothed section bypasses may change during playback because no topology is rebuilt. Final recording rejects those edits. When the owned graph is disabled, the same edits update only current Project state. The true-peak limiter remains active whenever the final bus is active and has no bypass. Exact ranges and latency are in Fixed stereo MASTER STRIP.

Each rack holds at most eight effects; the complete graph holds at most 16, including at most two reverbs. Source and master racks offer Utility, EQ, Compressor, Distortion, Delay, Reverb, Chorus, Flanger, Phaser, Tremolo/Pan, Filter, Gate, and Crusher. Aux creation offers Delay, Reverb, Chorus, Flanger, and Phaser and fixes their wet signal to 100% and dry signal to zero so an aux return never doubles the source. BYPASS fades a source/master effect toward dry passthrough. An all-bypassed aux is silent; a delay configured to keep its tail may drain that wet tail with new input muted. See the audio graph contract for exact schemas, publication rules, meters, and topology limits.

Do not enable this merely to perform a routine setup check. The first authorized dry-path comparison is recorded in Phase 1 dry audio graph measurement. Phase 2's software and Pi performance gates are recorded in Phase 2 insert-effects measurement. The time/modulation, reverb, aux, and master evidence is recorded in Phase 3/4 effects measurement.

The maintainer-only low-gain performance command is:

shr effects-checkpoint ENGINE:PRESET [PROFILE] [SECONDS]

Phase 2 profiles are dry, eq, compressor, soft-cubic, hard-clip, asymmetric, gate, filter-lp, filter-bp, filter-hp, crusher, and full. Expanded profiles are delay, chorus, flanger, phaser, tremolo, autopan, time-full, reverb-room, reverb-plate, reverb-hall, two-reverbs, and phase4-full. The last profile deliberately uses eight source inserts, two reverb buses, and one master compressor. Duration is bounded to 1–60 seconds. The command enables the graph only in its cloned in-memory configuration, sends note 48 at velocity 8, measures the owned graph and synth processes, restores the exact direct route, and stops only the engine it owns. It also prints final-bus peak/RMS, clip and non-finite counters plus Unix-microsecond control-thread lifecycle markers so JACK journal events can be assigned to startup, measurement, graph restore, or teardown. It does not persist graph enablement or JACK settings.

Non-destructive runtime fallbacks#

Saved configuration is preference, not a cache of what happens to be connected today. At each safe engine or loop activation SHR-DAW compares visible JACK ports without changing the configuration it will later save. It tries the preferred audio.output pair, each configured audio.internal_output in order, and audio.headphone_output last. The final entry is for the Pi analogue jack or another lowest-quality emergency route; no port name is assumed. The status names the fallback and missing preferred pair. If none is visible, audio reports unavailable while retaining the preference for the next activation.

Failure to open a controller or performance input leaves the TUI and tracker computer keyboard active and reports each role independently. Other available MIDI inputs still open. An exact Project MIDI target stays offline or ambiguous when its stable identity cannot resolve; it never falls back to the configured external output or the Pattern's software synth. Portable AUTO pages alone resolve the current machine default. Transport resolves every target again on the next play so reconnected hardware is used without rewriting the Project.

Controller menu layouts#

controller.conf records physical identity only. rotary.2 through rotary.16 name the fifteen direction-only turns; rotary 1's relative turn and the clicks on rotaries 1 and 9 use the separate encoder.* fields. pad.1 through pad.8 name physical pads. Instrument and screen tables—not the controller profile—give those positions their current parameter or action. The current context is described in the complete controller map.

Each rotary entry identifies the CC emitted by that physical control:

rotary.2=74
rotary.3=71

Eight-button layout:

menu.layout=8
pad.1=note.10.36
pad.2=note.10.37
pad.3=note.10.38
pad.4=note.10.39
pad.5=note.10.40
pad.6=note.10.41
pad.7=note.10.42
pad.8=note.10.43

Only channel-10 presses, releases, velocity-zero Note On releases, and polyphonic pressure for those notes are consumed. Notes 36–43 on channel 1 or any other channel remain musical input. A pad that emits a CC instead uses, for example, pad.1=cc.10.44. Use any in place of the channel only for a device whose message must remain channel-agnostic.

Five-button layout:

menu.layout=5
pad.1=note.10.36
pad.2=note.10.40
pad.3=note.10.41
pad.4=note.10.42
pad.5=note.10.43

The page-cycle action may instead be a held chord. This example holds CC27 and uses CC93 on the same MIDI channel; the trigger may also be a normally mapped control because its ordinary behavior remains active when the modifier is not held:

menu.layout=5
page_cycle.modifier=cc.1.27
page_cycle.trigger=cc.1.93

Use note.CHANNEL.NUMBER for a note-based modifier or trigger.

The main encoder may have a separate held modifier. On the FT2 grid, an ordinary turn moves rows and a modified turn moves columns across page boundaries:

encoder.modifier=cc.1.27
encoder.modified_relative_cc=29
encoder.modified_relative_reverse=false

Parameter rotaries carry SHR's current value by the signed left/right step. Preset load, RESET, mixer-bank changes, and linked controls continue from the current value because the hardware never claims a parameter position.

Use note.1.27 instead when the button sends a note. Omit encoder.modified_relative_cc when held turns keep using the ordinary encoder.relative_cc; otherwise the shifted CC is consumed but navigates only while the configured modifier is down. The reviewed MiniLab 3 profile maps the currently learned Shift CC9 and shifted rotary CC112 automatically. The earlier DAW-mode CC27/CC29 pair remains compatible. MIDI Learn's optional ENCODER SHIFT step captures two separate gestures: Shift plus left, release, then Shift plus right and release again. It stores a separate shifted relative CC when an explicit MIDI modifier is present. For the MiniLab mkII, whose hardware Shift selects an alternate CC without sending a standalone modifier message, it stores that alternate relative CC directly.

Four-button layout:

menu.layout=4
pad.1=note.10.40
pad.2=note.10.41
pad.3=note.10.42
pad.4=note.10.43

The note numbers above are examples only. Use the notes sent by the configured controller. In four-button mode, press the configured encoder to enter visible page-selection mode, turn it to choose page 1–4, and press it again to restore normal list/row/choice operation. Eight-pad screens interpret pads 1–4 as the four page positions and pads 5–8 as the four visible action positions. The five-pad layout uses pad 1 for page cycle and pads 2–5 for visible actions; the four-pad layout uses pads 1–4 for visible actions. Those meanings are runtime layout rules and are not stored in the controller profile.

Legacy pad.NOTE=ROLE and button.cc.NUMBER=ROLE entries remain readable and migrate in memory to the same PAD positions. Positional continuous mappings from cc.INCOMING=TARGET or version-8 pot.1 through pot.12 are read only long enough to drop them; they are never reinterpreted as direction steps. New saves use only rotary.2 through rotary.16 for learned relative controls. Command-note on/off and matching polyphonic pressure remain consumed; unmapped musical notes pass through. Disabled (-) and planned (~) entries never dispatch actions.

List or change controller mappings with:

shr pads list
shr pads input "Controller port name"
shr pads layout 5
shr pads rotary 2 74
shr pads pad 1 note 10 36

encoder.relative_reverse=true supports relative encoders whose clockwise messages are below 64. Positional 0–127 rotary output is unsupported. MIDI Learn asks for Relative 1 or Relative 2 instead of recording an absolute mode. encoder.modified_relative_reverse=true applies the same convention to a separate shifted turn CC. encoder.press_note=N stores rotary 1's click as a note; encoder.secondary_press_note=N does the same for rotary 9. The saved synth.press_cc or synth.press_note alias lets that same physical second click drive a model-owned action such as Dual Filter's core toggle. Normally shr-setup or shr pads learn writes these details. See Automatic controller setup and MIDI learn.

Tracker pages#

Every FT2 page has four note lanes. Pages are stored inside each FT2 Pattern, not globally on the Project. Pages in the current pattern play at the same time and each page stores:

• its target;
• four column channel/bank/program setups, with channels 1–16;
• page velocity, mute, and percussion settings;
• note-entry mode, One-column anchor, and optional drum-role/choke overrides;
• four lane names, lane mute states, and independent cycle/rate/direction settings;
• a reserved list of MIDI setup messages for later use.

Open FT2 SELECT → PAGE, then choose MANAGE PAGES / TRACKS. The resulting TRACKS screen edits pages and columns. Use the main encoder to select a page. ADD creates another four-lane page in that Pattern. TARGET chooses AUTO (portable machine default), an internal software route, or external MIDI. An internal route then chooses ENGINE before INSTR. Moj Sint additionally chooses MODEL before PATCH; an external route chooses MIDI OUT before its per-column channel/bank/program values. AUTO displays an AUTO channel and does not permit channel/bank/program editing because those values would bind the Project to one machine. CHANNEL chooses 1–16. Encoder press confirms a field. DONE keeps all page changes; SYS → ENTRY chooses Manual, One column anchored at C1–C4, or Drum auto for future notes; SYS → EXIT restores the Project from before TRACKS opened. On the COLUMN and BANK pages, COL−/COL+, PROG−/PROG+, and the bank controls edit the selected column. In a target/channel chooser, CONFIRM keeps that field and EXIT cancels it.

FT2 SELECT → ROUTE is the quick route editor. Its 38×9 bordered overlay shows TARGET, ENGINE, Moj Sint MODEL and PATCH, ordinary INSTR, or the SHR Drums KIT, plus MIDI OUT, optional PROFILE, and the 16 per-column channel/bank/program rows in a scrolling 36×7 content area. The overlay begins at (1,1), its content begins at (2,2), and the standard controller page/action rows remain immediately above the shared status row. Opening and browsing use cached discovery information; they do not create a MIDI discovery client, send MIDI, synchronize routes, or start an engine. A field changes only after click/Enter activates it. Back/Esc cancels that field first.

Turning an active field validates and applies each choice to the Project and live route. A failed choice restores the previous field value and route. Click/Enter keeps the current field value; Back/Esc restores the value from before that field was opened. APPLY ROUTING keeps the resulting route. The controller action row's direct CANCEL action, or Back from the main list, restores the complete route snapshot from when ROUTE opened.

An internal melodic route stores the engine identity together with that engine's stable instrument identity. Moj Sint identities include their synthesis model, so equal patch names in different models cannot collide. An SHR Drums route instead stores the stable kit ID and remains independent of the melodic engine choice. Applying a different kit resets tuning overrides owned by the prior kit while retaining the Project key and drum effects. Changing the standalone/current engine or catalog order cannot retarget either route.

An exact hardware port name is saved as the route. If it is missing, the page shows OFFLINE; if the stable identity matches more than once it shows AMBIG. Neither state changes, deletes, or falls back from the saved route. When the same interface port returns, playback resolves it without rewriting the Project. Discovery reports only whether the configured computer/interface output is available. It cannot discover, verify, or restrict instruments, splitters, chains, power state, MIDI channels, or programs behind a DIN socket.

Configured output#

The external_midi.* settings provide the machine route resolved by portable pages in new Projects and newly created FT2 Patterns. They also hold tracker timing, gate, bank/program, transport, live-thru, and optional drum-map defaults.

The most important output keys are:

external_midi.enabled=true
external_midi.client=shs-tracker
external_midi.output=stable client-name:port-name identity
external_midi.melody_channel=1
external_midi.percussion_channel=10

These example values are not device requirements. A configured interface MIDI output is enough: advanced users may attach one instrument, a splitter, a chain of 100 devices, or change the downstream chain while SHR-DAW is running. The route remains saveable while the interface is offline. Without a profile, the browser retains raw channels 1–16 and numeric programs 0–127.

external_midi.profile selects optional naming/bank metadata for the configured route. Use roland-d-50 for D-50 labels or raw-midi for no downstream assumption. Profiles never enable transmission, limit raw channel/program values, or imply that the hardware was detected. JSON profiles are discovered, in override order, from SHSYNTH_DEVICE_PROFILE_DIR, ${XDG_DATA_HOME}/shsynth/midi-devices/, the installed shared-data directory, and the checkout's midi-devices/ directory. The FT2 route stores an optional profile id separately from its output, channel, bank, and program values.

Project files#

Projects are stored as .shsong text files below ${XDG_DATA_HOME:-~/.local/share}/shsynth/songs/. Current Project format 18 stores each FT2 Pattern as a self-contained unit with its own tempo, meter, EIGHTH/SIXTEENTH swing, page targets, setup messages, four lanes per page, four column channel/bank/program setups, per-page entry mode/anchor, automatic Note Off choice, and drum classification, every cell field including independent signed 1/96-row timing, deterministic probability and a loop-aware condition, exactly four optional Loop Mix slots, explicit software engine/instrument identity, and optional external profile metadata. The Project continues to own the source insert rack, aux routing, master rack, fixed MASTER STRIP, final-bus routing, recording configuration, and unrelated Project state, plus the Project-wide tonic/mode, selected drum kit, fixed Reverb-then-Delay drum rack, and OFF, FOLLOW KEY, or MANUAL per-piece drum tuning. A format-4-or-newer default target plus four default column markers is the canonical portable/unassigned state; it is not channel zero, mute, or disabled. Versions 0 and 1 migrate with empty effects routing; version 2 retains its source rack and gains empty aux/master routing; format 3 keeps every explicit target/channel unchanged. Version 0 page-wide channel/bank/program data is copied to all four columns. Unknown newer versions, unknown fields, and invalid effect data are refused rather than partly loaded or written back.

Formats 8–11 write each populated WAV slot under its owner as pattern_loop=PATTERN|SLOT|FILE|SOURCE_BPM_X100|MODE|START|LENGTH|OFFSET|LEVEL|FILTER. Slots are 1–4, level is 0–1500, and filter is -1000..1000. Duplicate, missing, unknown, malformed, unsafe, or over-limit ownership is refused before the current Project changes. Format 7's loop_slot=SLOT|FILE|SOURCE_BPM_X100|MODE|START|LENGTH|OFFSET|LEVEL|FILTER records migrate in memory into every distinct Pattern. Format 6's one loop=FILE|SOURCE_BPM_X100|MODE|START|LENGTH|OFFSET record migrates to slot 1 of every Pattern with unity level (1000) and neutral filter (0). Only filenames/settings are copied; private WAVs are not. Loading, previewing, or inspecting an old Project does not rewrite it. Formats 0–8 also gain a neutral fixed strip only in memory. Formats 0–9 store whole-number tempo fields and migrate them to integer hundredths in memory. Format 10 stores Pattern and tempo-command values as deterministic integer hundredths; 10050 means 100.50 BPM. Format 10 infers automatic Note Off ON for melodic pages and OFF for percussion pages; format 11 persists the per-page choice. Format 12 adds the Project key, selected drum kit, tuning state, and internal-drum page target. Format 13 adds the drum rack; Format 14 adds bounded sparse automation; Format 15 adds Pattern swing and cell timing. Format 16 adds cell probability and conditions; formats 0–15 load them as 100%/ALWAYS. Format 17 adds independent lane cycle length, rate, and direction; formats 0–16 load FULL/1X/FORWARD. Format 18 expands the bounded Project aux inventory from two buses to three; older Projects retain their exact existing aux routes and load the third slot empty. Formats 0–14 load straight/on-grid in memory. Format 12 and older routing remains unchanged and receives restrained family defaults in memory. Explicit save writes format 18. Unknown newer formats and malformed, non-finite, out-of-range, unknown-field, or newer MASTER STRIP records remain refused.

Format 6 stores note-entry layout on pattern_page and optional non-GM classification as repeated pattern_drum_class=PATTERN|PAGE|NOTE|ROLE|CHOKE records. ROLE is core, long, or other; CHOKE is - or group 1–127. General MIDI is used when no override exists: notes 35–40 are core, 42/44 are short hi-hats in choke group 1, 46 is a long hi-hat in that group, and 49/51/52/53/55/57/59 are long-tail cymbals. Every unknown note is short other, never a cymbal. Project/kit tooling may write overrides for non-GM maps; the Tracks UI owns mode and anchor selection. Formats 0–5 retain their explicit percussion-page auto layout; other pages load as Manual/C1, and all load with no classification overrides.

On FILES, NEW PRJ requires a second press and creates the next available project-001 style unsaved name. SAVE AS writes a non-overwriting <current-name>-copy-001 style copy and makes it current. Normal SAVE asks for a second press only when it would replace an existing Project. Arrangement repeat/remove operations live on the separate ARRANGE screen. NAME accepts a printable display name while deriving a safe filename; an existing Project is published under the new name without replacing a collision.

external_midi.import_directory is the private .mid/.midi inbox. An empty value uses ${XDG_DATA_HOME:-~/.local/share}/shsynth/midi-inbox; the local launcher therefore keeps imports below its ignored $SHSYNTH_USER_DIR/ boundary. FILES → MIDI lists regular files only, analyses the selected file without starting transport, and requires a second action after showing its musical and loss report. Imported files are read in place and are never copied into the public repository or used to overwrite a .shsong.

Reusable drum patterns are independent .shdrum files. Bundled patterns are installed below share/shsynth/drum-patterns/; controller-created user saves go below ${XDG_DATA_HOME}/shsynth/drum-patterns/. They store four lanes of cells including independent timing and the four lanes' playback settings, plus meter and row count, but deliberately do not store Pattern swing, MIDI destinations, channels, banks, or programs. Formats 1–3 migrate missing timing/probability/condition or lane-playback data to their safe defaults; explicit saves use format 4. Loading therefore keeps the current percussion page's hardware routing intact. The installed .shrdrums catalog is a compact authored collection used to build filtered 24/48/96-row 3/4 and 32/64/128-row 4/4 phrase variations. It is read-only like the individual bundled grooves.

FT2 Loop Mix routing and storage#

Loop hardware and source locations are configured rather than compiled in:

loop.client=shs-loop
loop.import_directory=~/.local/share/shsynth/loop-inbox
loop.output=system:playback_1
loop.output=system:playback_2

Exactly two loop.output destinations are required when loading a loop. At application start its in-memory route follows the same resolved audio fallback pair described above; its remembered configured pair is not rewritten. The four slots share one internally summed JACK client and output pair. The player owns only that client and its ports; it never starts/restarts JACK, layers a synth engine, or disconnects another client. Missing servers or ports leave the MIDI tracker usable and produce a useful error.

loop.import_directory is only the browseable inbox. A chosen WAV is validated and copied without replacement to ${XDG_DATA_HOME:-~/.local/share}/shsynth/loops/, or the matching SHSYNTH_USER_DIR tree set by the local launcher. Each Pattern slot retains the private filename, source BPM, cut region, bar placement offset, level, and bipolar filter. Disk I/O, decoding, allocation, import, and auto-alignment analysis happen outside the JACK callback.

On first setup, the inbox is placed below the active XDG data root and seeded without replacement from the four CC0 48 kHz WAVs in the installed loops/cleared-loops.txt allowlist. Setup copies the selected JACK playback pair to loop.output. Its optional MusicRadar download adds private 85, 110, 120, and 140 BPM drum loops to the same inbox after explicit confirmation; the raw files are not part of the public package.

Stored Patterns are not decoded eagerly. Preparation holds at most the active and incoming Pattern and publishes a fixed four-slot state. The callback sums four fixed renderer positions and publishes one bounded stereo LOOP OUT snapshot after each slot's region, phase, filter, level, transport gate, and edge fades. It uses the same client, output_l/output_r ports, and destinations above; it does not create a graph route or additional JACK connection. It allocates and locks nothing. Stop, unload, load failure, oversize, and client loss clear stale levels without faulting healthy slots.

TOOLS → LOOP → REMOVE requires a second press and clears only the selected Pattern slot. It never deletes the imported WAV from private storage. The LIBRARY action opens the shared browse overlay for that slot, which lists regular inbox and private WAV files, marks their ownership and saved-Project references, and imports or attaches the rotary-selected file to the FT2 cursor's Pattern without exposing unsafe paths. INBOX imports and loads; PRIVATE, CURRENT, and SAVED attach and load. This overlay does not delete files.

Healthy Loop Mix slots need no extra state label. Active, queued, muted, missing, and faulted states remain visible on their own rows; one fault does not hide or stop healthy slots.

Loop playback is native-speed and native-pitch. Every active slot must have an interpreted BPM equal to the owning Pattern tempo; incompatible combinations are refused instead of drifting. Every WAV must also match the JACK sample rate. Choose 44100 Hz in JACK setup for 44.1 kHz loops, or 48000 Hz for 48 kHz loops, and restart JACK yourself when safe. Each decoded WAV is capped at 6,000,000 frames, about 46 MiB of stereo memory and 125 seconds at 48 kHz. Different whole-bar lengths remain phase-aligned at that Pattern's tempo and meter. Pattern changes restart local phase and stop empty outgoing slots. Import, attach, and auto-align prepare against the prospective detected hundredths-BPM tempo first. Only successful preparation publishes both the slot settings and Pattern tempo; failure restores the previous runtime and leaves the old Pattern, attachment, and private files unchanged.

See Live performance for launch/stop scheduling, filter/level bounds, controller and keyboard access, and unsupported DJ features.

FT2 cell fields#

The contextual CELL EDIT menu has four direct-action pages: ROUTE (Destination, Channel, inherited Instrument), SOUND (Bank MSB, Bank LSB, per-cell Program, Clear selected field), CELL (Note, Gate, Velocity, Effect), and DONE (Panic, Save draft, Effect Parameter, Exit/cancel). Empty positions are silent. Save writes the draft; Exit/cancel discards it without leaving a preview note. The rotary field sequence additionally exposes CHANCE, CONDITION, COND A, and COND B after Timing without adding a fifth controller page. Normal FT2 SOUND item 4 is FILL; CLICK is available on FT2 Tools SYS.

Gate is inherited or 1–100% of a row. Velocity and program are inherited or MIDI 0–127. The single command field supports cut C and delay D ticks 0–15, retrigger R counts 1–8, and decimal tempo T values 20.00–300.00 BPM. The letter is shown in the first spacer after velocity; blank means no command. Multiple commands in one cell are not supported. Per-cell program overrides use the selected column bank and exact page destination/column channel, occur before that note, and do not mutate the inherited column program.

Choosing PROGRAM replaces the grid with a named MIDI program browser. Browsing alone sends nothing. An explicitly played controller note auditions through the selected page target/column channel without being inserted into the pattern or duplicated through generic live-thru. Raw MIDI still shows every numeric program. Confirm commits the cell and cancel restores its original value and selection.

Note ownership#

Tracker events are sent only to their page target and channel. Controller command pads, the encoder, and mapped controls stay inside SHR-DAW. STOP, page mute, lane mute, Project replacement, route changes, and exit release notes only on affected destinations. Lanes that share a device/channel keep separate note ownership; a shared note is released only after its last lane owner ends.

The selected FT2 page also owns live keyboard and ordinary musical MIDI audition. A software page uses its saved engine and instrument identities; each MIDI page uses its own output/channel/program; a percussion page uses its drum mapping. Switching any route field cancels the old route first. Internal channels and programs are zero-based MIDI values, while every FT2 screen shows channels 1–16 and programs 1–128.

FT2 REC uses the selected page's exact online target, including a Pattern-owned software instrument or configured/exact MIDI output. It refuses an offline target rather than substituting another destination. REC from stop loops only the selected Pattern. REC during Play follows the current Arrangement; each note-off is written to the exact Pattern/page/lane owner captured by its note-on, even after cursor movement, Pattern wrap, or an Arrangement boundary.

Pattern setup starts with 4/4 row counts of 8, 16, 32, 64, and 128, or matching 3/4 counts of 6, 12, 24, 48, and 96. Its length overlay additionally offers every value from 1 through 32 plus 48, 64, 96, 128, 192, and 256 for either meter. New patterns are distinct pattern records and are appended to the Arrangement; clone duplicates the selected Pattern, while repeat adds another order reference to the same pattern.

Fresh Patterns use the private routing template at ${XDG_DATA_HOME:-~/.local/share}/shsynth/ft2-routing-defaults.shsong. Without one, the factory pages are Software Synth (first synthv1 preset), MIDI (channel 1/program 1), and Drums (channel 10). Saving a changed but note-empty Pattern asks whether to replace this template; confirm changes it, cancel does not. Projects with notes never update it implicitly. The confirmed template write is deferred until the Project save succeeds, so a pending/refused/failed Project save leaves the old template intact. Legacy Projects without Pattern synth routing receive safe in-memory defaults and are rewritten only by an explicit save.

Back to detailed guides

External instrument knowledge is JSON data, not Rust device logic. Profiles live in midi-devices/; installation copies them to share/shsynth/midi-devices/. Private or locally corrected profiles can override a bundled id from ${XDG_DATA_HOME}/shsynth/midi-devices/ or a path listed in SHSYNTH_DEVICE_PROFILE_DIR.

Profiles are optional convenience metadata only. RAW MIDI needs no profile and retains every channel 1–16 and program 0–127. A profile may add friendly names, a bank protocol, controller maps, or documentation; it never gates transmission, limits raw values, or claims the downstream DIN instrument was physically detected. Interface discovery can only report whether the computer's configured MIDI output port is currently available.

Schema version 1 records:

• a stable id, manufacturer, model, and optional MIDI-port name fragments;
• whether program selection uses no bank select, CC0, or CC0 plus CC32;
• one or more banks with their optional MSB/LSB, Program Change offset, native slot labels, optional names, and whether the memory is writable;
• research sources and a note explaining device-specific selection behavior.

slots and names are parallel arrays. A missing or JSON null name means the slot exists but its current name is unknown. This is important for user memories and removable cards: the UI must not invent a name for mutable data. Private overrides may supply the names actually loaded on one owner's device.

The program browser always retains numeric MIDI 0–127 access. For banks with distinct Program Change ranges, such as the D-50 internal and card groups, a single cell program can select the whole range. For devices that reuse the same Program Change values across CC0/CC32 banks, the page's MSB/LSB selects which bank's names are shown; the existing cell program remains a program-only override.

The bundled roland-d-50 profile is the first example, not a special mode. Its factory names come from Roland's D-05 Parameter Guide “Preset 1: Original D-50” list. Its MIDI range behavior comes from Roland's D-50 MIDI Implementation: Program Change 0–63 selects internal memory and 64–127 selects the card memory group.

Before adding a profile:

1. Use manufacturer documentation for MIDI behavior and names when available.
2. Represent writable/unknown names as null; do not guess what a user's hardware contains.
3. Keep all MIDI values zero-based in JSON, even if a manual prints 1–128.
4. Add parser/lookup tests and confirm the generic numeric fallback still works.

Back to detailed guides

SHR-DAW uses a small reviewed input-controller catalog plus model-owned MIDI learn. A controller profile describes messages produced by physical knobs, encoders, and buttons. It is different from an external-instrument profile, which describes messages accepted by a synthesizer.

Run the normal setup wizard after connecting a controller:

shr-setup

The wizard selects an ALSA MIDI input, loads a matching known profile, or offers non-audible MIDI learn for the missing controls. Learning never forwards messages to a synth. The current surface model identifies all sixteen physical rotaries, the clicks on rotaries 1 and 9, and numbered physical pads. Rotary 1 uses either supported direction convention for relative navigation. Rotaries 2–16 must report direction-only steps and carry SHR's current value. It never shows or stores an instrument parameter or screen action as a controller identity. An optional ENCODER SHIFT step learns the rotary's Shift-layer turn used for secondary navigation. MiniLab 3 emits a standalone modifier plus a shifted turn; MiniLab mkII consumes Shift internally and emits the alternate encoder CC documented by Arturia. Each step keeps the first qualifying gesture. The in-app learner visibly keeps OK on that role until the physical gesture is finished: a button advances on its matching CC-off, Note Off, or velocity-zero Note On, while a rotary advances automatically after its CC stream has been quiet for the short settle period. Extra values and encoder neutral/reset packets extend that same gesture instead of becoming the next role. On entry, release the control that opened MIDI Learn and wait for the ready indication; its release and already queued traffic are quarantined.

Each in-app session replaces the private midi-learn-last.log in SHR's configured state directory. The trace records the requested physical step, learner state, and every received MIDI message as hexadecimal bytes, including traffic that is filtered or rejected. It remains after Save or Cancel so the last failed physical attempt can be inspected without repeating it first.

First turn rotary 1 left and let it settle, turn it right and let it settle, then click and release it. At the optional encoder Shift step, press Shift and turn rotary 1 left until three left packets are verified, then release Shift. Press Shift again, turn right until three right packets are verified on the same CC, then release Shift again. Learn waits briefly for the shifted turn so a Shift button packet cannot win before the rotary packet arrives. Learn stores either an explicit MIDI modifier plus its relative turn CC, or the MK2-style alternate relative CC when Shift itself produces no MIDI event. The shifted axis learns its own direction encoding; it may be the reverse of the ordinary rotary. Skipping Shift remains valid. Learn then proceeds literally through rotaries 2, 3, 4, and so on to rotary 16 before the PAD positions. Rotary 9's click is captured immediately after its turn, just as rotary 1's special click and Shift actions stay with rotary 1. As soon as rotary 1's left/right axis is learned, turn it left or right to move one Learn step back or forward; no click is required. The selected step re-enters the short input quarantine, so trailing packets from that turn cannot move twice. For each performance rotary, turn left slowly until Learn verifies three left-direction packets, let the gesture settle, then turn the same rotary right until three right-direction packets are verified. The MIDI channel and CC must match in both directions. Once a candidate rotary has started its proof, traffic from a different CC is ignored without losing that proof. A wrong-direction or positional packet from the candidate itself rejects that attempt, waits for the gesture to be released, and automatically re-arms the same step. Direction changes, success, and retry remain visible through a 650 ms quiet window, which also prevents late packets from the previous turn being treated as the next requested direction. Packet proof counts remain in the private trace rather than flashing onscreen. Sweeping a positional knob through the values around 64 therefore cannot become a mapping and needs no keyboard recovery. One completed left/right proof moves by exactly one role regardless of how many packets either gesture emits. Each learned PAD advances after release. The learner ends at one explicit Review step; only there does a rotary-1 click save the mappings under the reviewed controller model, make a backup, activate that model, and exit after release. Earlier clicks cannot save or end the session. The controller workflow requires no computer keyboard. The in-app Learn screen shows exactly two rows total and no status footer. The first row starts with the complete required action; the second contains only its immediate instruction, success, or retry. It does not repeat the Learn title, mapping counts, safety commentary, recovery prose, or navigation summaries. Conflicting assignments from a different already-mapped control are rejected without replacing an accepted OK message with errors from trailing traffic. Relative encoders using either the center-64 convention (61–63 left and 65–67 right) or high/low values (125–127 left and 1–3 right, with neutral 0) are supported.

The first twelve learned turns, physical rotaries 2–13, control the existing twelve-parameter instruments and mixer positions. They add or subtract from SHR's value immediately and have no physical position to catch. Dual Filter uses rotaries 2–16 for its fifteen parameters and rotary 9's click for its core toggle. On other current instruments, turns 14–16 and the second click remain safely consumed without leaking their messages to the synth.

SHR does not guess how many pads the controller has. The in-app path determines an eight-pad layout when any of the first four page-row positions is captured, a five-pad layout when the alternate first-pad page-cycle gesture is captured, and otherwise a four-pad action-row layout. The displayed identities remain PAD 1 onward in every case; page and action meanings belong to the runtime layout and current screen.

Page-cycle may be one dedicated button or a held modifier plus another control. For a dedicated button, press and release it once, then press it again to confirm; this prevents a single exploratory Shift press from becoming the mapping. For a chord, hold the modifier and move or press the intended trigger, then release the modifier. The trigger may reuse a normally mapped knob or button because it cycles the page only while that learned modifier is held; one held chord triggers once regardless of packet count. Partial layouts are valid, so spare hardware buttons can remain musical or unassigned.

The generic installed controller.conf is deliberately empty. An unknown device therefore remains a normal musical MIDI input instead of accidentally inheriting another controller's command notes. Selecting a different unknown device with shr pads auto clears the previous device's mappings before MIDI learn begins; the old file is backed up first.

Commands#

shr pads ports                 # list detected MIDI inputs
shr pads profiles              # list installed known profiles
shr pads auto [PORT_MATCH]     # select input and apply a known profile
shr pads learn [PORT_MATCH]    # learn only what remains unassigned
shr pads update                # download the reviewed SHR catalog
shr pads list                  # show the resulting mapping
shr pads rotary 2 74           # bind physical ROTARY 2 to incoming CC 74
shr pads pad 1 note 10 36      # bind PAD 1 to channel-10 note 36

The bundled catalog lives in controller-profiles/catalog.json. Installation copies it below share/shsynth/controller-profiles/. shr pads update downloads the current catalog from the SHR-DAW public repository, validates it fully, and atomically installs it below ${XDG_DATA_HOME}/shsynth/controller-profiles/. Set SHSYNTH_CONTROLLER_PROFILE_DIR for a private override. controller.conf is the active private mapping. Each explicitly learned known model is also retained in the private state directory as controller-mappings/PROFILE-ID.conf. On later startup, the sole connected reviewed controller automatically restores its model-owned mapping; a model without a learned copy uses its bundled reviewed default. Automatic switching backs up and replaces only the active selector and never overwrites another model's learned copy. The setup helper uses SHSYNTH_STATE_DIR internally when an explicit --state-dir is supplied.

When no private controller.conf exists, startup uses the explicitly configured controller input to select one unique reviewed profile before the MIDI router opens. When a previously selected controller is offline, startup also adopts one exact connected endpoint if and only if it is the sole endpoint with a reviewed profile. It rebuilds the mapping from that profile instead of copying messages from the absent device. Unknown inputs and multiple reviewed replacement candidates remain unselected rather than guessed.

The bundled MiniLab 3 default retains only its verified direction-only and button mapping: encoder turn CC 114 and press CC 115 on channel 1, plus the eight Arturia/DAW factory pads on channel 10. The currently learned Shift CC 9 on channel 1 is the held encoder modifier, and its shifted turn is relative CC 112. Ordinary turns therefore stay on the directly learned CC114 while held Shift turns are classified on CC112. The earlier reviewed DAW-mode CC27 modifier and CC29 shifted turn remain a catalog-declared compatibility variant, so an older learned MiniLab mapping receives only its missing shifted CC in memory; SHR does not rewrite the private file. Its positional parameter knobs are not mapped. Unknown or ambiguous controllers remain unmapped rather than inheriting this device-specific default.

The bundled MiniLab mkII entry is deliberately a partial identity profile. The official hardware manual establishes its sixteen assignable encoders, clickable encoders 1 and 9, and two banks on eight physical pads, but those controls can emit user-programmed messages from several hardware memories. Startup can therefore select one connected MK2 automatically, then recommends MIDI Learn; it assigns no rotary, PAD, encoder, or command message before direct learning.

Upstream mapping sources#

There is no universal controller-description standard. These projects provide useful input-controller knowledge:

• Ardour MIDI maps cover many keyboard controllers and control surfaces.
• Mixxx controller mappings cover many DJ and grid controllers, including USB identifiers and scripts.
• Zynthian controller drivers demonstrate matched plug-and-play drivers plus MIDI learn.

Their mappings bind hardware to application-specific actions and may execute device setup or LED scripts. SHR-DAW does not download or run those files. Reviewed profiles may use their documentation as a source, but raw note/CC facts must be verified on hardware and recorded with provenance. This keeps a foreign transport command from silently becoming an SHR panic, record, or navigation command. Those upstream repositories use copyleft licences; none of their mapping data is included in the MIT SHR catalog.

The Pencil Research MIDI dataset is CC BY-SA 4.0 and is valuable for external synth CC/NRPN and drum-note profiles. It does not describe the physical controls emitted by USB input controllers, so it is not used for controller autoloading.

Catalog profile format#

Each JSON entry has stable id, display name, normalized ALSA match_names, a 4/5/8-pad layout, and any known mappings. rotaries maps physical rotary numbers 2–16 to incoming CC numbers; rotary 1 has separate turn fields. The in-app left/right gestures accept Arturia Relative 1 and Relative 2 and reject positional 0–127 output with an instruction to change the hardware mode. note_pads and cc_pads map one-based physical PAD positions to incoming notes or CCs; the parallel note_pad_channels and cc_pad_channels objects qualify those positions with 1-based MIDI channels. MIDI learn records the observed channel for every PAD, and save/load retains it. Instrument parameters and screen commands are absent from this schema. Rotary 1 turn, optional shifted turn, rotary 1 press, rotary 9 synth press, held modifier, and optional lock messages are separate so they cannot collide with continuous controls. The held modifier is stored as encoder.modifier=cc.CHANNEL.NUMBER or note.CHANNEL.NUMBER. A controller that changes the rotary CC while Shift is held also stores encoder.modified_relative_cc; its direction convention uses encoder.modified_relative_reverse. A direct alternate relative CC is valid without a standalone modifier when hardware consumes Shift internally. Relative-mode recognition does not depend on the controller emitting a neutral packet between the learned left and right turns. All physical note and CC numbers must be valid MIDI data bytes (0–127), and an encoder press cannot reuse a PAD note. Rotaries 2–16 always emit signed direction steps; their incoming values are never treated as parameter positions. An optional shifted_encoder_compatibility array retains previously reviewed ordinary CC, modifier, shifted CC, direction, and channel tuples. These entries never change a fresh profile; they only complete an older learned map in memory when every identifying field matches. Learned page-cycle chords are stored as page_cycle.modifier and page_cycle.trigger values such as cc.1.27; the modifier and trigger must be different messages, while the trigger may deliberately reuse a normal mapping.

Profiles may be partial. After one is loaded, shr pads learn asks only for rotary, PAD, and encoder positions that are still empty.

Version-7 private files and older downloaded catalogs remain parseable. Semantic button roles are converted in memory to physical positions, while old positional continuous-control entries are dropped rather than guessed as relative steps. SHR does not rewrite an existing private file merely to migrate it; the next explicit save writes only learned relative rotary.2 through rotary.16 syntax.

The reviewed MiniLab 3 profile maps PAD 1 through PAD 8 to factory Arturia/DAW notes 36–43 on channel 10. At runtime the eight-pad layout uses positions 1–4 for pages and positions 5–8 for the current screen's contextual actions. The profile itself contains none of those action names. Direct capture on this unit found User 1 pads on channel 1, the same channel as its keyboard, so User 1 pads are not safe command pads: their messages are indistinguishable from keyboard notes. The current learned Shift emits CC9 and is bound only as the held encoder modifier; its shifted rotary CC112 is accepted only while that configured modifier is down. Neither is a persistent pad lock, so normal arpeggiator, program, and bank gestures cannot toggle SHR lock state. The earlier reviewed DAW-mode CC27/CC29 pair remains compatible but is not the fresh-profile default. Selecting the controller's DAW program does not itself require a proprietary DAW script for these ordinary MIDI note commands. Arturia mode has the same captured channel-10 pad notes, so use DAW mode only if another ordinary mapping has been verified to be useful.

Back to detailed guides

Help me install, recover, or customize SHR-DAW on this Raspberry Pi.

Before acting, read AGENTS.md, docs/WORKSPACE_HANDOFF.md, README.md, and the existing user configuration. Treat install.sh and shr-setup as the supported path. This session should diagnose or customize that path, not replace it with an undocumented machine-only workaround.

Inspect the operating system, dependencies, terminal geometry, ALSA MIDI ports, JACK ports, audio interface, controller, and current SHR-DAW configuration. Run the normal setup and checks where safe. If a repository defect blocks setup, repair the project and add proportionate validation so the normal installer works for the next person.

Give me one physical action at a time. Explain what it checks before asking me to do it.

For controller discovery, listen without forwarding MIDI to a synth. Ask me to move or press one control at a time. Identify the 12 continuous synth controls, main relative encoder, encoder press, lock control, and command pads. Verify the relative-encoder direction and value convention. Reject duplicate or conflicting assignments, require Relative 1 or Relative 2, back up controller.conf, and show me the proposed map before calling it complete.

Help with JACK, ALSA, external-instrument, tracker-page, and SoundFont routing when requested. Keep hardware names and routes in configuration, never in Rust constants. Keep private downloads and user sound data outside the public repository. Preserve source and licence notes, and never describe uncleared material as redistributable.

Preserve existing configuration, presets, Ideas, Projects, recordings, unrelated processes, and repository changes. Do not start or restart JACK, launch an audible synth test, overwrite user data, publish, or make destructive or system-wide changes without explaining the exact action and receiving my permission. Never stop a synth process that SHR-DAW does not own. Back up files before changing them, and keep repository repairs separate from private machine settings.

Finish with proportionate non-audible validation. Run shr doctor only when JACK is already available. Report what you found, changed, backed up, verified, left untested, and what I should do next.

Back to detailed guides

SHR-DAW is a small music workstation built from several deliberately separate parts: role-separated controller/performance inputs, one managed software engine, in-process SHR Drums, a FastTracker II (FT2)-style MIDI sequencer, a private WAV loop player, a synchronized raw multitrack recorder, and an optional owned final performance bus. This guide connects those parts and explains what the musician can do with them. For exact configuration keys use Configuration and routing; for the DSP and real-time contract use Audio graph and DSP contract.

In architecture pages, owned means started or created by SHR-DAW and therefore safe for it to change or stop. An exact route is a saved endpoint that is never guessed. To publish a graph plan means making a validated, bounded plan active for the audio callback.

The whole signal model#

The shortest useful picture is:

controller / MIDI keyboard
        |
        v
SHR input router
  |                    |
  | commands/controls  +---- musical notes ----------------------+
  v                                                           |  |
screen, menus, relative controls                managed synth <-+  |
                                                or FT2 page -------+

FT2 scheduler -> each page's MIDI destination -> software or hardware instrument

managed synth audio -> direct JACK playback (graph disabled)
SHR Drums audio ----> direct JACK playback (graph disabled)
private WAV loop  --> direct JACK playback (graph disabled)

managed synth SOURCE/AUX --+
private WAV loop -----------+-> MASTER rack -> live fader -> MASTER STRIP
SHR Drums ------------------+
configured input 1/2 -------+-> stereo or dual-mono pan -> FINAL OUT + final WAV + playback
configured JACK sources -> fixed 18-channel meter snapshot
                        \-> shared callback timeline -> mono stems + manifest

The raw-stem recorder remains separate. The application owns the final bus independently of its optional synth, SHR Drums, and Loop sources. Input MON ON can therefore activate only the exact two-port Input and playback pair; it does not launch missing sound sources. Present optional direct routes move into the bus transactionally and reconcile when sources disappear or return. FINAL OUT, final WAV, and playback then share the same post-strip samples. They do not secretly include unrelated JACK clients or downstream interface processing.

Controller and performance input roles#

SHR-DAW opens each exact ALSA source at most once, then classifies messages by the configured role before they reach an instrument:

• menu buttons, the main encoder, encoder press, and the 15 relative performance rotaries stay inside SHR-DAW; the loaded backend decides whether those positions control synthesis or Project aux sends;
• command-pad note-on, note-off, velocity-zero release, and polyphonic pressure are consumed only when note and optional channel both match, so releasing or pressing a menu pad cannot leak while the same note on another channel stays musical;
• performance-only inputs bypass every controller mapping; ordinary notes, velocity-zero releases, sustain/modulation CCs, pitch bend, channel pressure, polyphonic pressure, and other supported channel messages keep the musical path;
• a combined input consumes its mapped commands and passes unmatched musical messages, while a control-only input suppresses unmatched traffic; and
• pad lock can temporarily treat command pads as notes when that is wanted.

Controller learning listens only to the selected controller source. Separate performance devices do not need special MIDI channels; channel-qualified mappings remain available for one combined port. Active-note ownership includes source, channel, and note, so one device's release, All Notes Off, disconnect, or route change cannot release an identical note still owned by another.

The reviewed MiniLab factory mapping uses channel 10 for notes 36–43. Its captured User 1 program uses the keyboard's channel 1 and is therefore not used for commands. The current learned Shift CC9 is not an SHR pad-lock control; the earlier compatible DAW-mode Shift is CC27.

On a combined input, the captured 12-byte Arturia program notification SysEx is still forwarded by the generic musical route when an instrument is active. A control-only input suppresses it with other unmatched traffic. It is device metadata, but SHR deliberately does not apply a manufacturer-wide SysEx filter: the current profile schema cannot distinguish that exact notification from other device traffic. There is no captured evidence that synthv1 acts on this foreign manufacturer message. An exact profile-qualified metadata rule can be added if a future workflow needs it; unrelated SysEx must continue to pass.

Controller clock ownership#

An optional dedicated output makes SHR the MiniLab clock/transport master. It uses the central tracker transport tempo but owns a separate exact ALSA standard-MIDI connection that can emit only Start, Timing Clock, and Stop. It never reuses a musical tracker page, so page notes/programs cannot feed back to the controller and multiple pages cannot multiply pulses. Its ALSA source port is non-exportable and every event is directly addressed to the selected port, preventing JACK's automatic sequencer bridge from becoming a second clock subscriber. Clock is 24 PPQN and continues evenly across event timing and live phase-preserving tempo changes.

Clock runs whenever the feature is enabled and SHR is open, using the default tempo before the first transport run. This lets the MiniLab detect clock before Play; direct capture showed that Start sent before any detected clock was not enough to launch its External-Sync arpeggiator. With the feature enabled, an empty Pattern may run specifically for live arpeggiation. Playback PLAY also starts the controller without requiring a recorded take; RECORD starts it for capture, STOP ends it without unloading the sound, and TAP changes tempo but does not imply Start. Every SHR play is a fresh launch (FA), not a resume; there is no FB Continue or F2 Song Position Pointer because SHR has no pause/resume transport state. Stop and an active clean shutdown each produce one FC as appropriate, while F8 keeps the stopped controller ready at the current tempo until SHR exits.

A controller profile describes what a physical device sends. The setup wizard can apply a reviewed profile or learn direction-only rotary messages, encoder direction, CC/note buttons, and an encoder press without forwarding the learning messages to a synth. Learned mappings remain private; reviewed catalog updates are validated and published atomically. See Controller profiles.

The synth controls use signed relative steps. After a preset or Idea loads, or after RESET, turns continue from the stored value, so stale hardware position cannot make the sound jump. Playback indicators compare each value with the original preset: green is more than 0.03 below it, bright yellow is within 0.03, and red is more than 0.03 above it. Reset changes only those mapped parameters and does not restart the engine.

Held notes drive the Playback note/chord display and its continuous keyboard strip. Each pitch also has its current MIDI Note On velocity shown directly beneath its name. Note Off removes only that channel's instance; if multiple channels hold one pitch, the display deterministically uses the highest still held velocity. German B/H spelling is the default; display.note_names=english uses A#/B spelling. Naming changes only the display, never the MIDI notes.

Software instruments and ownership#

The musician-facing behavior of the complete SHR-DAW instrument system is collected in SHR-DAW instruments and drums. This section owns the lower-level process and route boundaries.

The whole-system installation presents five melodic instrument families through one SHR-DAW workflow. Their runtime hosts are:

• synthv1 for subtractive synth presets;
• Yoshimi for .xiz instruments and banks;
• FluidSynth for .sf2 and .sf3 SoundFonts;
• Moj Sint for strict .mojsint Model D, Six-Op PM, Strange Oscillator, Swarm Machine, Bass Matrix, and Dual Filter presets; and
• SHR Sampler for strict preloaded .shrinst sample packages.

Only one SHR-managed software engine process runs at a time. synthv1 and Yoshimi retain one current preset. FluidSynth is the exception at the instrument level, not the process level: its one owned process may hold several SoundFont presets on compatible MIDI channels while producing the same one stereo source. Loading another standalone sound may reuse or replace the owned process; replacement sends All Notes Off, performs a clean shutdown, and starts the next configured host. SHR-DAW records enough process identity to stop only the engine it started. It neither layers managed backends nor kills an unrelated synthv1, Yoshimi, FluidSynth, Moj Sint, or SHR Sampler process opened by the user.

Moj Sint is started with --client-name and --preset, publishes exactly out_l/out_r, accepts timbre/ADSR on its established CCs, and accepts shared instrument volume on CC 7. SHR verifies the configured port names and owns only the child it started. The browser never launches it; LOAD is the transaction boundary.

SHR Sampler is preflighted with its machine-readable version and strict offline package validator before the current engine is disturbed. It is then started with --client-name and --instrument, publishes exactly the two configured outputs, and exposes one configured ALSA input. It does not connect itself. A missing executable/package, malformed package, incompatible version, validation timeout, startup failure, or unexpected exit becomes a visible managed-backend fault. Failed replacement gets one attempt to restore the previous owned session; no second melodic child remains layered.

A managed host becomes ready only after SHR resolves one unambiguous stereo JACK output pair for it; a MIDI JACK/ALSA port alone is not readiness. Exact configured client names are preferred. A single uniquely prefixed client is also accepted, which covers Yoshimi's generated names, but zero or multiple matches and anything other than exactly two audio outputs are refused. An exact direct connection already made by the managed synth is accepted; otherwise the checked JACK API aborts or rolls back the owning route change. Port connection may retry within the one startup deadline because some hosts publish names just before their JACK client becomes active. Managed synth MIDI selectors retain unique short-name matching for generated ALSA destinations, while physical MIDI devices continue to require their stable exact identities.

SHR's FluidSynth process uses JACK audio, ALSA sequencer MIDI, and its piped command input; it does not open FluidSynth's TCP server. Startup loads the configured SoundFonts once. Each planned channel receives only its effective 14-bit SoundFont bank and program, using a non-overlapping bank offset for each configured SoundFont. The persisted route includes the configured SoundFont identity as well as bank/program, so equal bank/program numbers in different files remain different sounds. Identical route/channel pairs are deduplicated; selecting one channel does not broadcast a program change to the other 15. The fresh FT2 Drums page resolves the General MIDI drum preset from that discovered metadata, stores its explicit FluidSynth identity, and gives all four columns zero-based channel 9. Live input and transport prepare that exact bank/program on channel 10 before sending 0x99 note-ons. A missing or failed selection stays explicit, offline, and silent instead of falling through to a previous part, Player sound, channel 1, or external MIDI. Saved Project routes and channels are never replaced by this fresh-Project default. All FluidSynth parts still cross the same stereo JACK boundary. They share the managed synth strip, source effects, meters, final-bus routing, and recording path; there are no per-instrument EQ/compressor/aux strips, stems, or JACK outputs. MIDI channel volume and pan remain ordinary channel messages where a Project uses them.

Interactive setup also offers to mask the distribution's always-running FluidSynth unit and blanket amidiminder patcher. This keeps a controller from reaching the same synth or hardware destination through an unowned background route while leaving all three engines available on demand.

Commands, client names, preset roots, SoundFonts, MIDI ports, and JACK ports are configuration. The engine code does not assume the development hardware. The five catalogs also remain separate: synthv1 XML, Yoshimi instruments, SoundFont programs, .mojsint files, and .shrinst packages never borrow one another's parsers or controls.

Maintained component repositories#

Three maintained repositories supply SHR-DAW components. Their boundaries are part of the installation and recovery contract.

Component	Runtime boundary	Component ownership	SHR-DAW ownership
SHR Drums	Rust library compiled into shr; there is no drum child process	Format 1 .shrkit validation, bounded sample decode, voice rendering, and the offline shr-kit compiler	Pattern timing, MIDI note dispatch, JACK publication, effects, kit selection, and public kit allowlists
Moj Sint	One managed moj-sint process with an ALSA input and stereo JACK output	Preset schema, synthesis models, MIDI controls, audio rendering, and the factory preset manifest	Exact command/preset configuration, process identity and shutdown, route connection, replacement rollback, private saves, and Project state
SHR Sampler	One managed shr-sampler process with an ALSA input and stereo JACK output	Format 1 package parsing, integrity checks, decoded samples, voice rendering, live host, and the cleared factory package	Version/package preflight, exact command/instrument configuration, process identity and shutdown, route connection, replacement rollback, and Project state

The current machine-readable pins are exact commits: SHR Drums 0199297b3efd160a67e3f47df64a6bf418c20df2, Moj Sint 693ad165271ae04bc2da6746642b87af1875b553, and SHR Sampler 9f2115f5fcc25d6ffa82a7106ee069cad47ce592. Cargo.toml owns the SHR Drums dependency; install/compatibility.json owns installer revisions and accepted runtime ranges. The Moj Sint pin contains the 16-start catalog through Bass Matrix. SHR-DAW source can also host schema 8 and Dual Filter, but the installer will not provide those five newer starts until its compatibility pin changes.

Each component refuses malformed or unsupported owned data before replacing a working session. SHR-DAW isolates a drum-kit failure to that source and keeps healthy sources running. For external instruments, it attempts one restoration of the previous owned session after replacement fails and never stops a matching process it did not start.

Public installation copies only files named by the relevant cleared manifest. Private presets, kits, samples, packages, renders, Projects, and recordings stay outside all four repositories. Developers should read the SHR Drums package format, Moj Sint documentation index, and SHR Sampler host architecture. Musicians should start with SHR-DAW instruments and drums, which describes the shared load, play, save, and recovery workflow.

Three different kinds of recording#

SHR-DAW uses “record” for three intentionally different jobs:

1. An Idea captures free-time MIDI while playing a managed sound. It keeps event timing and instrument identity; synthv1 and Moj Sint Ideas also keep a private preset snapshot and backend-specific mapped control values, while SHR Sampler Ideas keep only the stable package ID and configured public path without copying sample content. PLAY plays that MIDI back through the restored instrument. An Idea is not audio.
2. FT2 REC quantizes notes into the selected Pattern page using that page's Manual, One-column, or Drum-auto allocator. Recording from stop loops the selected Pattern; punching in during Play keeps the current Arrangement schedule. Each note-on owns its exact Pattern/page/lane until the matching release, including across cursor moves, loops, and Arrangement boundaries, and auditions through the page's exact online software or hardware target.
3. Audio recording captures every armed exact JACK source on one shared callback timeline. It writes separate mono 24-bit stems and a session manifest. Its separate Levels overview compares the first 18 configured source levels at once. It records arriving audio, not the MIDI events that produced it.

Idea take playback runs independently of screen redraw. Stop, route changes, replacement, panic, and exit release the exact notes still owned by that take. Ideas publish into new private directories without replacing a same-named Idea.

The audio callback copies a whole multichannel callback into one fixed ring or rejects all of it; an ordinary worker performs every file operation. A unique *.take.part session is published without replacement only after all mono WAVs and the manifest finalize. Recognized interrupted stems recover only their common whole-frame prefix and remain visibly incomplete; .part symlinks are never followed. Overflow, xrun, source/JACK loss, callback mismatch, RIFF limit, disk or finalization errors prevent a successful state. The recorder does not provide audible software monitoring, so use safe hardware direct monitoring.

The Levels client and take client are mutually exclusive owners of the same exact configured inputs. The meter callback computes bounded RMS/sample peaks for 18 fixed slots and publishes them through atomics; it allocates, locks, formats, and performs file I/O exactly zero times. UI smoothing, peak hold, decay, and labels happen outside the callback. This metering neither duplicates the final-bus route nor changes unrelated JACK connections. See the complete recorder contract.

Projects, Patterns, pages, and columns#

A Project is the complete tracker work saved as one .shsong file. It contains:

• distinct Patterns;
• an Arrangement whose ordered steps reference Pattern IDs;
• each Pattern's tempo, meter, rows, pages, lanes, and cells;
• page/column MIDI routing and setup data;
• the optional private WAV-loop reference and placement; and
• the source, aux, and master effects state.

The current saved hierarchy stops at Project. SHR loads one Project at a time, and the FT2 SONG control navigates that Project's Arrangement steps. There is no Playlist object above it. The proposed higher layer is documented in Playlist above Song; it adds no current screen, file, or runtime behavior. Patterns already own tracker Pages, and the missing whole-Page edit operations are recorded separately under Future Page operations.

A Pattern is reusable musical data, while an Arrangement step is a place that plays a Pattern. REPEAT adds another reference to the same Pattern, so later edits affect every repeated use. CLONE or paste-new creates a separate Pattern when the copies need to diverge. Cleanup deletes only Patterns with no Arrangement reference and never silently rewrites the Arrangement.

Each Pattern owns one or more pages, and every page has four note columns. All enabled pages play together. A page chooses one MIDI destination: portable AUTO, an explicit software engine/instrument pair, the configured external output, or an exact saved ALSA MIDI port. An AUTO page persists no device/channel/bank/program route and resolves the current machine defaults at playback. An explicit page's columns show channel 1–16 and program 1–128 while storing their zero-based MIDI values, plus bank MSB/LSB, lane name, and mute state. External-MIDI columns may share the same destination/channel only when their master bank/program selections match, because MIDI program changes affect the whole channel. Software pages take their preset from the saved route, so their external bank/program fields do not impose that restriction and stored setup messages cannot replace the route-owned bank/program.

This separation makes several useful routes possible in one Pattern: one page can play its named software instrument, another can address a drum machine, and another can play a hardware synth on a different port. FluidSynth pages add a second axis: several saved presets may play through one owned process when each MIDI channel has one stable preset. Repeating an identical route/channel across pages does not create another engine part or collapse lanes; every page still contributes four independent lanes. Different presets on one channel are refused across the whole playback loop because note tails and Pattern/Arrangement boundaries are not yet safe dynamic preset-change points. A disconnected exact target is displayed as OFFLINE and never substitutes another port; its name and notes stay in the Project. Destinations are re-resolved on each play, so a returned interface is selected without editing the Project. Ambiguous stable identities are reported and not guessed. For software pages, “online” additionally means the managed engine has the exact saved route selected on that page's runtime channel; resolving a label alone is not readiness.

External MIDI device profiles optionally add bank labels and program names to the column and cell program browsers. They remain JSON data, can be privately overridden for writable user memories, and never remove raw channels 1–16 or the musician-facing 1–128 numeric fallback. They describe rather than detect downstream DIN hardware. See MIDI device profiles.

FT2 ownership#

Play, Record, and Edit are separate modes over the same Pattern data. Each Pattern page owns four lanes, its route, entry layout, automatic Note Off choice, and live-audition destination. Record quantizes performance input. Edit writes deliberate cells with independent note length and row advance. N00B is a scale filter layered over those modes, not another mode.

Manual, One column, and Drum auto change only future entry. They do not rewrite existing cells or move the visible cursor. Cell Edit remains transactional: Confirm publishes the complete cell and Exit restores the original. Probability and loop-aware conditions are Cell data. The scheduler evaluates conditions before a deterministic percentage gate. Normal FT2 rebuilds the event plan at its selected Arrangement playback-span boundary; Live Patterns rebuild at their Pattern boundary. Route/engine preflight includes every conditional trigger, while context-free MIDI export uses pass 1 with Fill off.

An explicit page route is authoritative. A genuinely new, empty, unsaved Project may adopt the current Player instrument for page 1 without restarting it; saved or otherwise changed Projects keep their own routes. Route changes release the old destination before the new one is armed.

Pattern setup, drum-library loading, transpose, and Arrangement operations change Project records without changing private source libraries. The exact musician workflow and field behavior belong to the Tracker guide. The Project storage sections define what is persisted.

The managed audio graph#

Without the owned graph, the managed instrument, SHR Drums, and owned loop use their exact configured direct playback routes. audio.graph.enabled=true starts the bus automatically; MTR Input MON ON can start it explicitly with only one exact configured stereo JACK capture pair and the playback pair. Whichever optional sources are present move transactionally into this route:

managed instrument -> SOURCE inserts + AUX returns --+
owned WAV loop ---------------------------------------+-> stereo sum
SHR Drums --------------------------------------------+
configured capture L/R -------------------------------+
 -> MASTER rack -> live master level
 -> fixed INPUT/TONE/GLUE/COLOR/IMAGE/LOUD strip -> FINAL OUT
 -> final stereo WAV tap -> configured playback L/R

There are four useful placement ideas:

• A source insert processes the instrument in series. It is the normal place for tone shaping, dynamics, distortion, or an effect that belongs to this sound.
• An aux send makes a parallel copy. PRE takes it before source inserts; POST takes it after them. Each of AUX 1, AUX 2, and AUX 3 has its own send, rack, return gain, and meter.
• An aux return brings only the effected copy back into the sum. The normal aux editor offers Delay, Reverb, Chorus, Flanger, and Phaser and forces them to 100% effect/0% dry so the original instrument is not accidentally doubled.
• The master rack processes the complete source-plus-returns sum. It is the place for final corrective EQ, bus compression, overall utility changes, or deliberate whole-mix coloration.
• The fixed MASTER STRIP follows the live master level. It provides saved mastering gain/cleanup, broad tone, linked full-band glue, declared harmonic colour, conservative image width, and protected true-peak output in one non-reorderable order. It is Project-global rather than Pattern-owned.

Send and return levels run from -60 to +12 dB. A new aux starts with a conservative -18 dB post-insert send. The compact controls use 3 dB steps; sends below -60 dB show OFF. Each serial rack holds at most eight processors, the complete graph at most 16, and no more than two reverbs. These limits are rejections, not silent truncation.

Effect possibilities#

Source and master racks can use all 13 effect types:

• Utility trims level, pans, changes stereo width, inverts either channel, or mutes. It is useful for gain staging and stereo correction rather than a flashy sound.
• EQ provides a low cut, low/high shelves, two broad mid bands, and output trim. Use it to remove rumble, reduce boxiness or harshness, or emphasize the part of a sound that should speak.
• Compressor controls peaks and movement with threshold, ratio, knee, attack, release, makeup, parallel mix, and sidechain high-pass. Fast attack restrains transients; slower attack lets the front of a note through.
• Distortion offers soft cubic, hard clip, and asymmetric modes plus drive, bias, tone, output, and mix. They range from rounded saturation to an intentionally sharp edge; output trim is important for fair comparison.
• Gate reduces sound below a threshold with hysteresis, depth, attack, hold, and release. It can clean gaps or deliberately shorten a noisy/long texture, but aggressive settings can cut note tails.
• Filter is a resonant low-pass, band-pass, or high-pass with drive and mix. It can darken, thin, isolate a moving band, or add a resonant sweep.
• Crusher reduces bit depth and sample-hold rate, with optional dither and parallel mix, for stepped digital texture.
• Delay supports stereo, ping-pong, and mono-to-stereo echoes, free time or tempo divisions, feedback, stereo ratio, tone, wet/dry mix, and optional tail-on-bypass.
• Reverb offers room, plate, and hall voicings with predelay, decay, size, damping, input low cut, width, and wet/dry balance. Pre-delay is independent of decay; the diffuse FDN has no single room/echo repeat.
• Chorus uses a short modulated delay to add width and gentle pitch motion; rate, depth, stereo phase, feedback, mix, and dry level shape the result.
• Flanger uses a much shorter modulated delay and signed feedback for moving comb-filter sweeps, from subtle motion to metallic resonance.
• Phaser uses four or six stable all-pass stages with rate, center, range, feedback, stereo phase, and mix for a smoother notched sweep.
• Tremolo/Pan changes level or stereo position with sine, triangle, or smoothed-square motion, plus rate, depth, stereo phase, and output trim.

Exact names, defaults, physical ranges, and delay divisions are centralized in the effect schema table. The rack UI uses those schemas rather than a different hidden set of values.

Bypass, tails, meters, and publication#

Source/master bypass fades toward the dry signal rather than switching on one sample. An aux cannot use that same fallback because raw send audio on a return would double the source. If every wet generator on an aux is bypassed, its return fades to silence. A delay with tail-on-bypass may stop accepting new input while its already-created wet echoes drain; serial conditioning can continue to pass an already-wet signal or feed another active wet generator.

Internal drums own one fixed Reverb-then-Delay Project rack before their direct or graph output boundary. Bypassing the two slots exposes OFF, REVERB, REVERB + DELAY, and DELAY without changing routing. Tracker Stop drains this rack naturally; Panic, Project replacement, route-host replacement, and shutdown clear it.

Every processor publishes bounded input/output peak and RMS plus clip and non-finite state. Compressor editing also exposes its detector-derived gain reduction through a lock-free value; the LED display responds immediately to increasing reduction and uses a fixed 250 ms release for visual stability. Bypass publishes zero reduction. Each aux meters after its return gain. FINAL OUT follows the fixed strip and its stereo-linked 8× true-peak limiter. It distinguishes sample peak, dBTP, GLUE/limiter reduction, correlation, and LUFS-M/S/I. The recorder tap and playback receive the same final buffer after that meter boundary. Exact strip controls and latency are in Fixed stereo MASTER STRIP.

The FX rack and parameter editor remain available while the graph is disabled, so a Project can be designed silently without an audio callback to rebuild. When the graph is enabled, every FX change that would publish a replacement runtime plan requires stopped transport and no active recording. The complete plan, coefficients, buffers, ports, and memory are prepared and validated away from the real-time callback. Stable instance IDs let compatible effects retain DSP state when moved. The callback uses fixed memory and atomics: no file access, subprocess, logging, allocation, or locks.

MASTER STRIP values and section bypasses are different from rack structure: they are smoothed atomic updates and may be auditioned during playback. They are rejected during a final recording. Whole-strip comparison keeps the same delay and true-peak protection, and never overwrites the edited values.

The graph remains opt-in and disabled by default. The managed engine, internal drums when active, and loop are connected directly first. The graph is activated muted, its four stereo inputs plus playback boundary are connected, and the owned direct links are removed as one rollback-capable transaction before graph output is published at a block boundary. Validation, activation, or connection failure leaves or restores the exact prior direct links. Shutdown deactivates the callback before restoring them, avoiding a doubled final block.

FX state is saved in the Project while the graph is disabled, but direct playback cannot process or meter it. The graph instantiates exactly four source kinds: managed instrument, SHR Drums, owned loop player, and one two-port live Input. That Input can preserve stereo or independently pan its two ports in dual mono. The graph deliberately has no general strips, pan for other sources, solo, hardware insert, per-input effect chain, or arbitrary wiring.

Live Patterns, Loop Mix, and the final bus#

Live Patterns is a sequencer-owned performance view over existing Pattern records. Browsing is UI state. Successful activations occur at validated Pattern or bar boundaries. Temporary lane shaping changes a runtime copy and is dropped when the Project is replaced.

Each Pattern owns four optional references to private WAVs. The fixed renderers share one owned JACK client and sum to one logical Loop source. Only the active and incoming Pattern are prepared. The callback publishes a fixed renderer set without allocation, locks, decoding, or file access. A failed slot stays silent without stopping healthy slots or MIDI.

Arrangement steps and Live retriggers restart Pattern-local phase for MIDI and loops together. In direct mode the Loop output connects to playback. An active final-bus transaction moves that same output into the sum and removes the direct links, so the path is never doubled. Removing a slot detaches its Project reference and keeps the private WAV.

See Live performance for launch, preview, capture, and boundary controls. See Audio graph and DSP contract for the callback and routing limits.

Note ownership and failure behavior#

MIDI notes are owned by physical destination, software route, channel, note, column/lane, and playback source. Owners are global across Pattern pages, not reset per four-lane page. Two lanes on different pages may therefore hold the same note on the same destination/channel; SHR-DAW sends note-off only after the last owner releases it. Scheduled notes and live audition use the same ledger, so an audition release cannot cut a matching tracker note. Stop, page/lane mute, route change, Project replacement, Idea/take stop, recorder stop, panic, output failure, and exit deduplicate cleanup by the physical note while retaining the all-channel engine panic. This prevents one page, lane, or screen from cutting off another shared note.

Realtime FT2 capture adds a bounded input-owner ledger above that unchanged playback ledger. Each note-on remembers its exact Pattern, page, lane, start row, and generation. A note-off closes only the current generation for that lane; an older overwritten One-column note cannot close the newer note, and repeated identical owners require their final release. Pattern wrap and Arrangement transitions write the release into the same global page/lane identity. Stop, mute, panic, route/output failure, Project replacement, and exit discard every capture owner and run the normal destination cleanup.

Missing JACK leaves browsing and external-MIDI sequencing usable. A missing controller leaves the computer keyboard active. Audio resolves preferred, ordered internal, then final headphone routes in memory. A missing external MIDI target remains offline without rewriting or falling through to another port. Ambiguous ports are reported and refused. Missing optional engines or sound banks remain visible with an explanation. A failed graph returns to direct playback. None of those failures authorizes SHR-DAW to rewire unrelated clients or terminate processes it does not own.

Project and private-data safety#

Project format 18 persists the complete tracker state, integer-hundredths Pattern/command tempos, exactly four optional Loop Mix slots under each Pattern, effects routing including the internal-drum rack, one Project-global fixed MASTER STRIP, per-page entry mode/anchor, automatic Note Off choice, drum-role/choke overrides, explicit software engine/instrument identities, optional external profile metadata, Project tonic/mode, selected drum kit, drum tuning, and bounded Pattern-owned sparse automation lanes, Pattern swing, independent signed 1/96-row cell timing, deterministic probability/condition per note trigger, and independent lane cycle length, rate, and direction. Format 15 and older Projects gain 100%/ALWAYS trigger defaults. Format 14 and older Projects gain straight/on-grid rhythm defaults; Format 13 and older Projects gain empty automation in memory. Format 7's former Project-global four slots migrate in memory into every distinct Pattern. Format 6's single WAV record migrates to slot 1 of every Pattern. Formats 0–8 gain a neutral strip in memory. No migration copies audio or rewrites the file. Formats 0–16 gain FULL/1X/FORWARD lane playback. Format 18 expands the bounded aux inventory to three without changing any older saved route; only an explicit save writes format 18. Format 12 keeps its routing and gains safe family drum-effect defaults in memory. Format 10 infers the Note Off choice from the percussion flag. Format 5 and older ordinary pages gain Manual/C1 entry defaults in memory; explicitly marked percussion pages retain their prior automatic drum entry. Format 3 remains loadable and keeps its device/channel routes explicit. Formats 0 and 1 migrate with empty effects; format 2 retains its source rack and gains empty aux/master routing. Unknown newer formats, fields, malformed rack data, unsafe paths, and over-limit structures are refused rather than partly loaded and then written back.

Opening the automation editor does not create a lane. Lane creation and confirmed clearing are explicit, populated lanes cannot lose points through target browsing, and capture is disarmed before an Arrangement boundary could redirect a lane index into another Pattern. Effect removal and confirmed type replacement atomically discard only the automation lanes whose exact rack/effect identity can no longer resolve; cancelling the type change keeps both the effect and its automation.

Normal Project save asks again before replacing an existing file. SAVE AS chooses a numbered non-overwriting copy. Rename publishes the complete new Project before removing the old filename and refuses collisions. New Ideas, audio recordings, imported loops, and user drum patterns likewise choose or require unused destinations. Destructive deletion is explicit and scoped: Pattern cleanup checks zero Arrangement references, and Pattern loop removal keeps the WAV. The current loop browser has no file-deletion workflow.

Configuration lives below ${XDG_STATE_HOME:-~/.local/state}/shsynth/; private user data normally lives below ${XDG_DATA_HOME:-~/.local/share}/shsynth/. A repository-local launch redirects both into ignored $SHSYNTH_USER_DIR/. Important private data includes Ideas, Projects, recordings, imported loops, user drum patterns, learned controller configuration, profile overrides, and uncleared presets. Public packaging uses only cleared preset and component manifests, authored drum data, and files named by the cleared demo manifest. See Licensing and redistribution.

Performance information and honest limits#

With the graph inactive, MTR retains its CPU and legacy managed-source display. With the graph active, it shows four source readiness/level states, MUTE for Synth/Loop/Drums, the one MON ON/MON OFF action for Input, master level, post-strip sample/true-peak and loudness state, linked gain reduction, correlation, and final-recording status. Direct mode reports final-bus metering unavailable instead of creating a hidden tap or displaying unrelated audio.

Maintainer checkpoints separately collect callback count, mean, p95, p99, maximum, deadline misses, oversized blocks, xruns, process/core CPU, memory, and shutdown behavior. The earlier one-source graph passed its recorded Raspberry Pi engineering checkpoints. The fixed four-node final bus has separate hardware-free stress evidence; full-duplex interface acceptance remains a future hardware test and is not implied by synthetic validation.

Back to detailed guides

This document is the current implementation contract for SHR-DAW's owned audio graph and effects racks. The graph is implemented and Raspberry Pi measured, but remains opt-in and disabled by default. Direct JACK routing is both the default and the conservative fallback. The current product compiler instantiates four bounded stereo boundaries: the managed software instrument, SHR Drums, the owned WAV loop, and one exact configured JACK capture pair. The capture boundary can preserve stereo or explicitly matrix its two ports as separately panned mono inputs before the dry sum.

This page owns DSP topology, bounds, and callback safety. The menu manual owns screen actions, while the final performance bus owns monitoring and final recording.

The active signal flow is:

managed instrument -> SOURCE inserts -------------------------------\
       |                    |                                            ^
       |                    +-> POST send gain -> wet AUX 1/2/3 -> return -+
       +----------------------> PRE send gain  -> wet AUX 1/2/3 -> return -+
owned WAV loop ------------------------------------------------------+-> dry sum
configured JACK input 1/2 -> stereo or dual-mono pan matrix -------/
in-process SHR Drums -> Project DRUMS Reverb -> Delay --------------/

dry sum -> MASTER inserts -> live master level
        -> fixed MASTER STRIP (INPUT/TONE/GLUE/COLOR/IMAGE/LOUD)
        -> FINAL OUT meter -> final stereo WAV tap -> playback L/R

Each of the three bounded aux buses has its own send level, pre/post source-insert tap, forced-wet serial rack, return level, and return meter. Each return is mixed exactly once. Compiled send taps retain lock-free linear-gain controls. Player/FT2 surface changes use a 10 ms ramp during held notes or transport without deactivating or recompiling the graph; OFF is a prepared zero-gain route. Recording refuses those changes. Tap point, rack, and processor edits remain structural. The complete dry-plus-wet sum then passes through the master rack, live master level, fixed Project-owned strip, and post-limiter meter immediately before the recorder tap and playback. The final WAV and JACK playback buffers contain the same post-strip samples. The exact final-bus contract is in Final stereo performance bus. The measured history is in the Phase 1 dry, Phase 2 insert, and Phase 3/4 bus records. New hardware-independent strip evidence and algorithm provenance are in Fixed stereo MASTER STRIP; the dated Pi runs remain historical rather than being rewritten.

Send and return gain are each bounded to -60..+12 dB. The compact UI changes sends by 3 dB and treats below -60 dB as OFF; a newly created aux starts with a -18 dB post-insert send. Return changes also use 3 dB steps and wrap from -60 to +12 dB. These are Project values, not JACK port gains.

Ownership boundary#

One application-owned JACK client contains the current stereo graph. Its lifetime is independent of every optional sound source, so MTR Input MON ON can activate it without a managed synth, Loop, or drums. Effects are internal processors, not separate JACK clients or processes. That client has four stereo input boundaries and one stereo output boundary to the runtime-resolved pair. The saved preferred audio.output pair, ordered internal pairs, and final headphone pair remain machine configuration. Exact JACK and hardware names come from configuration, never Rust constants.

The compiled plan has fixed ManagedEngine, InternalDrums, LoopPlayer, and LiveInput nodes, but only the exact configured live input and playback pair are required for input monitoring. Optional sources attach silently when their exact ports exist and can disappear or return without stopping the bus or creating a duplicate playback path. SHR Drums is a library hosted in-process by SHR-DAW, not a second managed synth process. Its fixed Project drum rack runs in that host before either the graph boundary or direct playback, so drum effects remain correct when the owned graph is disabled. The loop remains its own rendering client; when the final bus is active its output is moved off direct playback and into the owned sum. The raw synchronized multitrack recorder remains a separate capture client. External instruments return only through the configured two-port Input owner. That owner alone may preserve the pair as stereo or treat its ports as two independently panned mono signals. There is no hardware insert, per-input effect rack, or separate JACK client per interface channel.

The graph may connect and disconnect only SHR-owned endpoints. It must not alter unrelated JACK connections or terminate a client/process it does not own. Until the graph is activated successfully, the managed engine and loop use their exact direct routes. The raw recorder routes are unchanged.

The owned callback publishes silence while the required input/output links and each currently available optional source boundary are prepared. Only exact SHR-owned synth, loop, or drum direct links are removed in the same rollback-capable transaction. Only after that commit does an atomic flag publish graph output at a block boundary. A rejected graph, activation failure, ambiguous optional output pair, or connection failure leaves monitoring off and restores the exact prior owned topology.

On normal shutdown, the publish flag is cleared and JACK deactivation joins the owned callback before available synth, loop, and drum direct links are restored. Closing that client then releases only its registered ports and their graph-boundary connections. This ordering prevents a final already-started graph block from overlapping the restored direct path.

src/jack.rs is the shared dynamic-loading and lifetime boundary for current and future JACK clients. A caller owns its callback allocation and keeps it alive until client deactivation returns.

Project data and typed graph model#

Project formats 10–13 store the managed-source InsertRack, ProjectAuxRouting, and fixed MasterStripSettings as strict JSON inside the versioned .shsong line format. Format 13 adds the fixed internal-drum rack. Project format 18 and typed graph format 2 expand the bounded aux inventory from two buses to three; older Projects retain their exact existing routes. Format 12 and older Projects keep their exact page routing and migrate a restrained family-specific Reverb-plus-bypassed-Delay rack in memory. Formats 0 and 1 migrate to an empty rack and routing; format 2 keeps its source rack and adds empty aux/master routing; format 3 retains explicit routes. Unknown current fields, malformed rack data, and newer Project/effect versions are refused on load and on overwrite. Rack order is a separate list of stable effect IDs, so moving an effect does not recreate its identity.

Formats 0–8 migrate one neutral strip in memory. The strip is Project-global and therefore does not change when Arrangement or Live Patterns changes Pattern. INPUT, TONE, GLUE, COLOR, and IMAGE default bypassed; the 8× true-peak limiter remains active. Its fixed processor follows the compiled master rack and live master fader rather than appearing in master_chain, so it cannot be reordered or instantiated twice.

The active Pattern's four WAV slots are mixed inside the one owned Loop client before this graph. One prepared incoming four-renderer set is published through a bounded atomic pointer handoff; the callback never allocates or frees it, and the owner thread reclaims the retired set. Stored Patterns create no additional clients or sources. The graph still sees exactly one logical stereo Loop source, so direct/final-bus publication and rollback are unchanged and the complete four-slot sum reaches the limiter and final recorder exactly once.

The runtime compiler expands those Project fields into a typed graph definition with stable non-zero IDs:

format_version
enabled
nodes[] { id, kind, channel_layout, configuration }
edges[] { id, from_node, from_port, to_node, to_port }
effects[] { instance_id, kind, version, bypass, parameters-by-name }
source_chains[] { source_id, ordered effect instance IDs }
master_chain { ordered effect instance IDs }
aux_buses[] { id, ordered effect instance IDs, return_gain }
sends[] { source_id, aux_id, level, enabled, pre_or_post }
monitoring_mode
recording_tap

Effect parameters use stable names and physical units rather than positional arrays. Interactive controls clamp to their visible range. Persisted parameters must already be finite and valid or the whole proposed graph is rejected.

Typed nodes#

Source node kinds are ManagedEngine, InternalDrums, LoopPlayer, LiveInput, and HardwareReturn. Processor kinds are Utility, Eq, Compressor, Distortion, Delay, Reverb, Chorus, Flanger, Phaser, TremoloPan, Filter, Gate, and Crusher. Bus kinds are StereoMixer, SendTap, and AuxReturn. Sink/tap kinds are MainPlayback, HardwareSend, RecordPreFx, RecordPostFx, and RecordMaster.

Edges carry stereo audio. A mono source requires an explicit adapter and is never silently duplicated; Input dual mono is the deliberate boundary matrix for its two named capture ports. A hardware send and its own return may not form a path, and a master/sink may not feed a source.

Validation before publication#

A complete proposed graph is built and validated away from the JACK callback. Validation checks:

• unique node, edge, port, and effect-instance IDs and references to existing objects;
• compatible channel layouts or an explicit adapter;
• an acyclic graph with deterministic topological order and no self-edge;
• no hardware-send/own-return, master/input, or other feedback path;
• exact, unambiguous configured JACK boundary ports;
• no unintended sink reachability or duplicate aux return;
• no simultaneous direct and software monitoring unless the user explicitly accepts the doubled-path warning;
• every non-empty aux rack contains a wet generator; delay, reverb, chorus, flanger, and phaser are forced to 100% wet with zero dry signal;
• runtime plan publication only while transport and recording are stopped; graph-disabled Project edits validate and persist without touching audio; and
• every capacity and memory bound below.

The graph plan, filter coefficients, port resolution, delay memory, and all callback buffers are prepared before activation. External connection failure or rejected validation leaves the old graph and direct route unchanged.

The synchronized raw recorder remains outside this Synth/Loop/Input/Drums graph. Its dedicated Levels overview opens at most one recorder-owned meter client for the first 18 exact configured capture sources. Starting a take deactivates that client before activating the recording client; returning to Levels may activate metering again only after the take has stopped. It does not add a software-audible monitor, duplicate the final-bus input, or touch unrelated JACK connections.

The meter callback publishes a fixed 18-channel RMS/sample-peak/clip snapshot through atomics. Its channel and frame loops are bounded by 18 and the configured maximum callback frames, with no allocation, locks, file access, formatting, decoder work, or unbounded retry. UI-only code performs smoothing, 900 ms peak hold, 24 dB/s decay, clipping hold, colour selection, and text.

Initial hard bounds#

These are rejection limits, not targets and not silent truncation points:

Resource	Bound
Stereo source strips	4 instantiated
Aux buses	2
Effects in one serial chain	8
Active effect instances	16
Typed nodes	32
Edges	64
Simultaneous reverbs	2
Delay per delay instance	2 seconds at active rate
JACK frames per callback	4096
Total owned delay/effect memory	16 MiB

The meter RMS window is also bounded to 4096 frames. The graph may initially reserve one preallocated stereo block per node. Buffer-liveness reuse is a measurement-led optimization, not permission to raise a bound.

Callback contract#

The process callback may read and write only fixed memory, atomics, and lock-free bounded queues. It must not allocate or free, take a lock, access a file, run a subprocess, log, format text, panic, or calculate trigonometric functions per sample.

Parameter targets are finite and range checked on the control side. Cheap values are smoothed in the sample path. Biquad coefficients and LFO recurrence steps are calculated before callback use. Every processor guards non-finite input, output, and state; a poisoned processor resets and yields a bounded dry or silent fallback instead of propagating NaN/infinity.

Structural publication is intentionally stopped-only. The publish flag is cleared and JACK deactivation joins the callback before the control thread rebuilds the plan. Compatible kind plus stable instance ID moves the existing runtime slot into the replacement plan, retaining recursive DSP, smoothing, dither, and meter state. The same client is reactivated and its exact boundary transaction is rechecked before output is armed. A failure restores the direct fallback; no old and new callback plan can run together. Live two-plan crossfading remains future work and is not implied by the current stopped-only workflow.

Live automation parameter publication is separate from structural publication. Each compatible running slot exposes a stable effect ID, kind, version, and named schema through a validated control-thread handle. Valid normalized values are converted to physical or discrete values before a fixed atomic publication. At a block boundary the callback consumes at most the schema's bounded parameter count; it allocates nothing, takes no lock, logs nothing, performs no I/O, and retains the same DSP instance, recursive history, meters, delay memory, bypass fade, and smoothing. Removing or retyping a slot deactivates its old handle. Missing IDs, stale handles, unknown names, invalid values, and kind/version mismatches are rejected visibly without changing the graph or another effect.

The final bus also owns the metronome oscillator. Its beat-one accent uses precomputed recurrence coefficients and fixed callback state. Clicks are mixed inside the final boundary; they have no MIDI destination, synth voice, drum voice, allocation, or extra JACK client.

Shared DSP foundation#

src/dsp/mod.rs provides finite/denormal guards, stereo frames, smoothed values, dB conversion, one-pole filters, a DC blocker, transposed-direct-form-II biquads, bounded fractional delay, an envelope follower, a recurrence sine LFO, and fixed-window peak/RMS metering with atomic publication. Construction and configuration are control-thread work; their sample-processing methods are allocation-free. Delay, chorus, and flanger use a centered four-point, third-order Lagrange read above the two-sample safety margin and retain linear interpolation for shorter reads that cannot refer to a future sample.

The biquad formulas are an original Rust implementation guided by the W3C Audio EQ Cookbook, which documents Robert Bristow-Johnson's public coefficient formulas. JACK lifecycle and port behavior follow the official JACK 2 API header. No third-party DSP implementation code is copied into SHR-DAW.

Effect algorithm provenance#

The following publications describe the equations or signal topology actually used by each current processor. SHR's Rust is independently implemented; no third-party DSP source code is incorporated. Except where an equation requires a constant, the parameter ranges/defaults, smoothing lengths, delay capacities, reverb voicings, safety clamps, and musical mappings in the schema below remain documented SHR product or engineering choices rather than claims about the literature.

Effect	Engineering authority and relevant material
Utility	A. D. Blumlein, UK Patent GB394325A (filed 1931, published 1933), sum/difference stereo matrix; W3C Web Audio API 1.1 §6.3.3, sine/cosine equal-power panning. SHR uses a center-unity balance variant and its own 0–200% width scale.
EQ	Robert Bristow-Johnson / W3C, Audio EQ Cookbook (W3C Note, 2021), §2 and the HPF, peaking and shelf equations; Stephen Butterworth, “On the Theory of Filter Amplifiers” (1930), pp. 536–541. The fourth-order high-pass Q pair is derived from the Butterworth poles; bell Q, ranges and defaults are SHR choices.
Compressor	D. Giannoulis, M. Massberg and J. D. Reiss, “Digital Dynamic Range Compressor Design—A Tutorial and Analysis,” JAES 60(6), 2012, §2, Eqs. 3–8. Stereo max linking, sidechain cutoff range and lookup-table resolution are SHR choices.
Distortion	J. O. Smith, Physical Audio Signal Processing, “Nonlinear Elements,” hard-clip and cubic equations; S. Bilbao, F. Esqueda, J. D. Parker and V. Välimäki, “Antiderivative Antialiasing for Memoryless Nonlinearities,” IEEE Signal Processing Letters, 2017, §§II–III; F. Esqueda et al., “Virtual Analog Models of the Lockhart and Serge Wavefolders,” Applied Sciences 7(12), 2017, Eqs. 45 and 50. First-order ADAA now suppresses foldback in all three branches without oversampling storage or integer-sample graph latency. The normalized cubic and asymmetric coefficients remain SHR voicing choices, not diode-circuit claims.
Delay	J. O. Smith, Physical Audio Signal Processing, “Delay-Line and Signal Interpolation,” Eq. 5.7 and the order-3 central-span guidance; “Comb Filters” and “Filtered-Feedback Comb Filters.” Routing modes, tempo map, 20 ms time glide, cutoff mapping, linear fallback below two samples, and two-second capacity are SHR choices.
Chorus	S. Disch and U. Zölzer, “Modulation and Delay Line Based Digital Audio Effects,” DAFx-99, §2.2 Eq. 5; J. O. Smith, Physical Audio Signal Processing, “Chorus Effect.” Delay/rate ranges, feedback cap and read-head margin are SHR choices.
Flanger	J. O. Smith, Physical Audio Signal Processing, “Flanging,” Fig. 5.3 and feedback discussion; Disch and Zölzer, DAFx-99, §2.2. Delay/rate ranges and signed-feedback limit are SHR choices.
Phaser	J. O. Smith, Physical Audio Signal Processing, “Phasing with First-Order Allpass Filters,” §§9.19–9.20, including the first-order all-pass and bilinear coefficient. Four/six stages, shared stage tuning and sweep maps are SHR choices.
Tremolo/Pan	Disch and Zölzer, DAFx-99, §2.1 Eq. 1, amplitude modulation; W3C Web Audio API 1.1 §6.3.3, equal-power panning. The unity-center normalization, waveform set and 5 ms square smoothing are SHR choices.
Reverb	J. Stautner and M. Puckette, “Designing Multi-Channel Reverberators,” Computer Music Journal 6(1), 1982, pp. 52–55, Eqs. 1–3; J. O. Smith, Physical Audio Signal Processing, “FDN Reverberation,” “Hadamard Matrix,” and “Achieving Desired Reverberation Times,” Eqs. 4.5–4.10; J. Dattorro, “Effect Design, Part 1: Reverberator and Other Filters,” JAES 45(9), 1997, Fig. 1 and §1.3.3, pp. 662–664, cascaded all-pass input diffusion. The normalized Hadamard matrix, RT60 line-gain equation, and all-pass topology are sourced invariants; the four FDN line sets, four input-diffuser lengths, 0.55 diffusion gain, damping map, and room/plate/hall labels are original SHR tuning.
Filter	A. Simper, “Linear Trapezoidal Integrated State Variable Filter With Low Noise Optimisation,” Cytomic, 2013/2016 corrections, pp. 2–7, Eqs. 1–5; Bilbao et al. (2017), §§II–III, first-order ADAA. Resonance mapping and the pre-drive blend are SHR choices. The cubic pre-drive now uses independent per-channel ADAA state before the TPT filter, without oversampling storage or integer-sample latency.
Gate	M. Terrell, J. D. Reiss and M. Sandler, “Automatic Noise Gate Settings for Drum Recordings Containing Bleed from Secondary Sources,” EURASIP JASP, 2010/2011, §2.1; Giannoulis et al. (2012), Eqs. 5–8. Detector constants, hysteresis, stereo max link and ranges are SHR choices.
Crusher	S. P. Lipshitz, R. A. Wannamaker and J. Vanderkooy, “Quantization and Dither: A Theoretical Survey,” JAES 40(5), 1992; R. A. Wannamaker et al., “A Theory of Non-Subtractive Dither,” IEEE Transactions on Signal Processing 48(2), 2000. The two-uniform, 2-LSB peak-to-peak TPDF is source-backed; signed endpoints, LCG seeds and sample-hold range are SHR choices.

Direct sources: Blumlein patent, Web Audio API, Audio EQ Cookbook, Butterworth paper, compressor tutorial, Smith nonlinear elements, Bilbao et al. ADAA, Esqueda et al. ADAA Eq. 45/50, Smith Lagrange delay interpolation, Smith comb filters, Disch/Zölzer modulation, Smith flanging, Smith phasing, Stautner/Puckette FDN, Smith FDN, Dattorro reverb, Simper SVF, Terrell/Reiss/Sandler gate, and Wannamaker et al. dither.

Objective reverb tests use the normalized echo-density definition from J. S. Abel and P. Huang, “A Simple, Robust Measure of Reverberation Echo Density,” AES Convention 121, paper 6985, 2006: the proportion outside one local standard deviation is normalized by the Gaussian expectation. That metric establishes density growth, not musical preference. See the AES publication record.

Deterministic tests cover silence/step/impulse behavior, supported sample-rate limits, reset and non-finite recovery, stereo independence, long-running finite state, chunk-size invariance, and callback-path allocation detection. Live rate changes preserve the running LFO phase in chorus, flanger, phaser, and tremolo/autopan; changing the explicit stereo-phase parameter still re-phases the affected oscillator as requested.

The effect rack adds one canonical named parameter schema per effect kind in src/effect_schema.rs. Persisted values may omit older/defaulted controls, but unknown names, non-finite values, invalid discrete choices, and values outside the declared physical range reject the complete graph. src/effects/ provides fixed runtime slots with stable instance identity, placement-safe finite fallback, click-conscious bypass, reset, and separate input/output peak/RMS, clip, and non-finite meters. The EQ, compressor, distortion, crusher/reducer, gate, multimode filter, delay, chorus, flanger, phaser, tremolo/autopan, and shared-topology reverb have passed their deterministic software response gates. They are available in source and master racks; delay/reverb/modulation effects on an aux are validated as 100% wet. Two independently scaled pre/post sends feed two metered returns, which are mixed exactly once before the ordered master chain. Source and master bypass retain dry passthrough. Aux bypass tracks wet generators explicitly: an all-bypassed bus returns silence, a delay may drain a wet-only tail with muted input, and serial conditioning may pass an already-wet signal. The final mastering snapshot after the fixed strip and immediately before playback supplies the MASTER/FINAL OUT reading. The compact rack/editor uses four controller pages, with OPS first and EXIT at page 4/item 4, and shows input and output peak/RMS, clipping, non-finite counts, and compressor gain reduction. Raspberry Pi whole-chain evidence is documented in the Phase 2 measurement and Phase 3/4 measurement; the consolidated human-curation gate remains open in the latter.

The source/master effect meters observe each processor's input and output; return meters observe the wet bus after return gain; FINAL OUT observes the complete owned graph after the fixed strip. Rack meters publish bounded peak/RMS, clip, and non-finite state; the strip additionally publishes dBTP, LUFS-M/S/I, correlation, and linked gain reduction through atomics. They do not observe the separate loop client, recorder capture, hardware, or unrelated JACK clients. The MTR keeps its non-decaying numeric L/R maxima entirely in UI presentation state; the audio callback continues to publish only the bounded lock-free snapshots. The bar's brighter circular peak LED retains its existing hold and decay behavior. The numeric maxima reset on MTR RESET, every downward mapped synthv1 Volume movement and meter/engine session boundaries. The MTR CPU bars are whole-core /proc/stat load and deliberately cannot diagnose per-process DSP cost, callback deadlines, scheduling jitter, or xruns; those belong to the explicit checkpoint counters and JACK evidence.

Internal drum ambience and delay#

The DRUMS target is deliberately a fixed two-slot rack: Reverb, then Delay. The musician changes parameters or bypass, but cannot add, remove, retype, or reorder these slots. Their bypass states name four unambiguous modes: OFF, REVERB, REVERB + DELAY, and DELAY. Delay-only never enters the reverb; combined mode places the rhythmic echo after the diffuse ambience with restrained wet defaults.

Reverb is a four-line Hadamard feedback-delay network with two input all-pass diffusers per channel, independent 0–200 ms pre-delay, RT60 decay, acoustic line-size scaling, high-frequency damping, input low cut, and stereo width. Pre-delay does not alter feedback or decay. Every accepted feedback gain is below one. A tail is cleared after 1.5 times its selected RT60 plus 0.4 seconds of propagation allowance, giving a 12.4-second design maximum at the 8-second RT60 limit. Bypass fades the input and dry/processed mix over 5 ms, then clears hidden state.

Delay has a two-second-per-channel storage limit, feedback limited to 92%, feedback-path low-pass filtering, smoothed free/synchronised time changes, and stereo, ping-pong, or mono-to-stereo routing. The drum host supplies the active Pattern tempo without allocation or locking in the callback. Ordinary tracker Stop drains voices and ambience naturally. Panic, All Notes Off, Project or drum-effect replacement, route-host replacement, and shutdown clear recursive state deterministically.

Effect parameter schemas#

These stable names and physical ranges are the persistence and control contract. Values in parentheses are defaults. Discrete numeric modes are listed in their current order.

Effect	Parameters
Utility	trim_db -60..12 (0); pan -1..1 (0); width_percent 0..200 (100); invert_left, invert_right, mute toggles
EQ	low_cut_enabled; low_cut_hz 20..500 (80); low_shelf_hz 40..800 (120), low_shelf_db -18..18 (0); low_mid_hz 80..3000 (500), low_mid_db -18..18 (0); high_mid_hz 400..12000 (3000), high_mid_db -18..18 (0); high_shelf_hz 1500..20000 (8000), high_shelf_db -18..18 (0); output_trim_db -18..12 (0)
Compressor	threshold_db -48..0 (-18); ratio 1..20 (4); knee_db 0..12 (6); attack_ms 0.1..100 (10); release_ms 20..1500 (150); makeup_db -12..18 (0); mix_percent 0..100 (100); sidechain_highpass_hz 20..250 (20)
Distortion	mode 0 soft cubic, 1 hard, 2 asymmetric (0); drive_db 0..30 (6); bias -0.5..0.5 (0); tone_hz 800..18000 (12000); output_db -24..0 (-6); mix_percent 0..100 (100)
Delay	mode 0 stereo, 1 ping-pong, 2 mono-to-stereo (0); tempo_sync; tempo_bpm 20..300 (120); division 0..7 (4); time_ms 1..2000 (375); feedback_percent 0..92 (30); stereo_ratio 0.5..2 (1); tone_hz 500..18000 (8000); wet_percent 0..100 (25); dry_percent 0..100 (100); tail_on_bypass
Reverb	type 0 room, 1 plate, 2 hall (0); predelay_ms 0..200 (20); decay_seconds 0.2..8 (1.5); size_percent 0..100 (50); damping_percent 0..100 (50); input_low_cut_hz 20..500 (80); width_percent 0..100 (100); wet_percent 0..100 (25); dry_percent 0..100 (100)
Chorus	base_delay_ms 5..30 (15); rate_hz 0.05..5 (0.5); depth_percent 0..100 (35); stereo_phase_degrees 0..180 (90); feedback_percent 0..35 (0); mix_percent 0..100 (35); dry_percent 0..100 (100)
Flanger	base_delay_ms 0.2..8 (2); rate_hz 0.03..5 (0.25); depth_percent 0..100 (50); feedback_percent -80..80 (25); stereo_phase_degrees 0..180 (90); mix_percent 0..100 (50); dry_percent 0..100 (100)
Phaser	stages 4 or 6 (4); rate_hz 0.03..5 (0.25); center_hz 100..5000 (1000); range_octaves 0.5..6 (3); feedback_percent -75..75 (0); stereo_phase_degrees 0..180 (90); mix_percent 0..100 (50); dry_percent 0..100 (100)
Tremolo/Pan	mode 0 tremolo, 1 pan (0); rate_hz 0.05..15 (4); depth_percent 0..100 (50); shape 0 sine, 1 triangle, 2 smoothed square (0); stereo_phase_degrees 0..180 (180); output_trim_db -18..12 (0)
Filter	mode 0 low-pass, 1 band-pass, 2 high-pass (0); cutoff_hz 20..20000 (1000); resonance 0..90 (20); drive_db 0..12 (0); mix_percent 0..100 (100)
Gate	threshold_db -80..0 (-48); hysteresis_db 0..24 (6); range_db -80..0 (-60); attack_ms 0.1..100 (2); hold_ms 0..500 (40); release_ms 5..2000 (150)
Crusher	bit_depth 4..16 (12); hold_factor 1..32 (1); dither; mix_percent 0..100 (100)

Delay sync divisions 0..7 are the note values 1/16, 1/8, 1/4, 1/2, 1, 2, 4, and 8 (0.25 through 32 quarter-note beats). The source and master racks allow all 13 types. The normal aux editor offers Delay, Reverb, Chorus, Flanger, and Phaser and forces their wet/dry values; conditioning effects can exist in a loaded aux chain only when the chain also contains one of those wet generators.

The dry client additionally publishes allocation-free callback count, total, mean, maximum, missed-deadline, and oversized-callback counters. One fixed one-microsecond histogram increment per callback lets the owner calculate p95 and p99 outside the callback. The headless daemon records the final timing summary in its private engine log during an orderly stop; the full measurement report remains owner-thread/Pi checkpoint work.

Measurement and curation gates#

Effect quality has an objective engineering part and a musical-curation part. Tests and controlled captures must establish the technical part against a declared design target rather than stopping at basic finite-output checks. Use impulses, steps, steady and swept sines, multitone/noise, silence, and bounded program material as appropriate. Measure response/cutoff/slope/resonance, transfer and dynamics curves, harmonics/intermodulation/aliasing/DC, envelope timing and stereo linking, transient overshoot/ringing, discontinuities and zipper/bypass clicks, noise/headroom, latency, chunk/sample-rate consistency, long-run recovery, and whole-chain callback cost where each applies. Report deviations numerically and treat a measurable defect as an engineering issue, not merely a subjective preference.

Those measurements can establish accuracy to the intended response, stability, bounded artifacts, click-conscious operation, and Pi performance. They cannot alone decide whether a deliberate coloration is inspiring or appropriate for particular music. Each phase therefore also needs an authorized, low-gain, level-matched release-mode listening checkpoint. Record JACK rate/period settings, callback mean/p95/p99/max, missed deadlines, xruns, process/core CPU, RSS, owned effect memory, meters, and shutdown/client-loss behavior. Provide an evidence-based technical KEEP, IMPROVE, or DROP recommendation; the creator makes the final musical curation decision, and only kept/improving choices remain visible as product effects.

The first authorized graph checkpoint compared one dry source with the direct fallback and verified bit-exact stereo output, one path, callback headroom, and clean fallback/ownership behavior. The exact Pi evidence is recorded in Phase 1 dry audio graph measurement. It does not imply that an unmeasured creative effect or later graph phase is safe.

Back to detailed guides

The owned audio graph has one deliberately small final bus. It is not a free-wiring view or a general-purpose mixer. This page owns source availability, software-monitor safety, and final stereo recording. DSP algorithms and rack schemas belong to Audio graph and DSP contract.

Input is the only required source; the managed synth, Loop Mix, and SHR Drums attach when present:

managed software instrument -> owner gain -> source inserts/aux ---\
owned four-slot native-rate Loop Mix sum -> owner gain -------------+-> stereo sum
configured JACK capture 1/2 -> stereo or dual-mono pan -> owner gain/
SHR Drums rack/stereo bus -> owner gain -----------------------------/
    -> optional aux returns, where routed from the managed source
    -> master insert rack
    -> master level
    -> fixed Project MASTER STRIP
       INPUT -> TONE -> GLUE -> COLOR -> IMAGE -> LOUD/true-peak limiter
    -> FINAL meter
    -> final 24-bit stereo WAV tap
    -> configured JACK playback L/R

FT2's live mixer activates this owned bus even when the passive Performance screen was not enabled in runtime configuration. Activation does not enable Input monitoring: an external-return strip remains visibly marked until the musician deliberately enables the safe software-monitor path. Failure to activate leaves the prior direct routes unchanged and the FT2 editing location intact.

The logical Loop and external-input bus strips do not gain individual insert racks, aux sends, solo, automation, or waveform editing. Drums has only its fixed Reverb-then-Delay rack before this bus; it does not become a general mixer strip. Synth, Loop, and Drums retain a smoothed level and mute. Input instead has one unambiguous MON ON/MON OFF control in the same MTR source-control position; it is never shown beside a duplicate Input mute. Input also switches between the original stereo mapping and DUAL mono. Dual mono treats configured port 1 and port 2 as independent mono signals with an equal-power pan for each. Its initial 1L100 2R100 positions reproduce the stereo mapping exactly; changing either pan routes only that input across the final stereo mix. Mode and pan transitions use the same 10 ms ramp as source levels. Loop Mix applies its four slot-local level/filter/mute controls before this one logical source. The managed source keeps its existing Project-owned insert/aux routing. Master level follows the complete sum. Source gain is bounded to -60..+6 dB, master gain to -60..0 dB, and all level/mute transitions use a 10 ms sample ramp. New runtime buses start each source at -6 dB to leave basic summing headroom. Input monitoring always starts OFF. These live performance controls are not Project data; current Project format 18 stores effect racks/routing and the fixed MASTER STRIP at Project scope and four Loop Mix settings under each Pattern, but not these final-bus levels, mutes, Input mode, or Input pans. JACK assignments remain machine configuration. A fresh runtime always starts in stereo mode; dual-mono choices do not reinterpret raw multitrack recording.

Each source publishes one lightweight post-owner-gain stereo peak for the FT2 mixer before the graph performs Project processing and summing. The existing fader loop accumulates those peaks, so callback work remains one bounded pass: two absolute-value/maximum updates per frame and two atomic stores per owner per block, with no allocation, locking, formatting, or file access. Pages linked to the same owner reuse this snapshot instead of adding another meter. The opt-in callback cost measurement remains available with:

cargo test --locked source_meter_callback_cost_has_realtime_headroom -- --ignored --nocapture

Exact routing and availability#

The configured input is audio.graph.input=LABEL|LEFT|RIGHT. When that optional new key is blank, the first legacy capture.input pair is reused so older runtime configuration remains useful. Both exact names must exist and be distinct. A similar-looking or adjacent port is never substituted. MTR Input MON ON can activate the bus with only this input and the exact playback pair. It never starts a synth, WAV loop, or drum host. Missing optional sources stay OFFLINE; when Loop is present, its four active renderers sum to one pair before the graph, so the bus, limiter, final meter, and recorder receive the complete Loop sum once.

Before attachment, synth, drums, and Loop may have their ordinary direct stereo routes. The graph connects a present source to its fixed input and removes only that source's exact owned direct links as one rollback-capable transaction. Optional disappearance is silence, not bus failure; periodic owner-thread reconciliation reconnects only the remembered exact names when they return. Input loss while MON is on faults a final recording and reports the nearby recovery state. JACK loss deactivates the callback before restoring available owned direct routes. No path invents a replacement or alters an unrelated link.

audio.graph.input_direct_monitoring describes whether the interface's own zero/low-latency direct monitor is also audible. The final bus is software monitoring. Enabling both without audio.graph.confirm_doubled_monitoring=true refuses MON ON because the delayed software copy and direct copy can comb-filter or sound doubled. Confirmation is deliberately explicit; it does not change interface hardware.

MASTER STRIP and limiter#

The Project-owned strip follows the live master level in one fixed stereo order. Its optional INPUT, broad TONE, full-band linked GLUE, declared ADAA COLOR, and conservative M/S IMAGE stages default bypassed. LOUD is a 0..+6 dB push into an unbypassable stereo-linked true-peak limiter. The ceiling is -2.0..-0.5 dBTP and defaults to -1.0 dBTP.

The limiter uses fixed 8×, 24-tap-per-phase interpolation before its detector and again after limiting for the published true-peak result. The larger reconstructed channel peak controls one shared gain. Its 2.5 ms look-ahead has a shaped attack, 1 ms hold, 100 ms release, and a 0.25 dB internal guard. The supported post-limiter tolerance is +0.30 dBTP. The final numerical clamp is a counted safety boundary, not the normal limiting mechanism.

Complete fixed strip latency is 1 COLOR alignment sample, 12 interpolation delay samples, and round(rate * 0.0025) look-ahead samples: 133 samples (2.770833 ms) at 48 kHz and 123 samples (2.789116 ms) at 44.1 kHz. JACK and the interface add their own periods, safety buffers, and converter delays. SHR does not hide those in the software figure. For example, one 128-frame period is 2.667 ms at 48 kHz.

The final snapshot distinguishes input/output sample peak, output dBTP, GLUE/limiter gain reduction, correlation, and LUFS-M/S/I. Details, exact parameters, algorithms, provenance, exclusions, and repeatable measurements are in Fixed stereo MASTER STRIP.

Final recording#

MTR REC arms one final-mix recording. Start and stop are sampled only at whole callback boundaries. The callback gives the recorder the same final limited StereoFrame slice that is then copied to JACK playback. A bounded interleaved stereo ring transfers it to a non-real-time writer, which performs 24-bit conversion, file writes, flush, synchronization, and no-replace publication.

The result is one conventional little-endian PCM RIFF/WAVE file: two interleaved channels, 24 bits, and the active JACK sample rate. It includes every present unmuted optional source and the configured external input only while Input MON is on, plus managed-source aux returns, master rack, master level, and complete MASTER STRIP. It excludes raw recorder stems, unrelated JACK clients, interface direct monitoring, hardware mixer/insert processing after JACK playback, and any downstream speaker/headphone processing.

Classic RIFF has a 32-bit data size. Stereo 24-bit audio uses six bytes per frame, so SHR stops before 715,827,876 frames instead of wrapping. That is about 4:08:33 at 48 kHz or 4:30:32 at 44.1 kHz. A zero-frame take is not published. Overflow, writer failure, JACK shutdown/xrun, oversized callback, invalid buffer, or required-source loss stops/faults the take visibly. A faulted *.wav.part remains recoverable; it is never presented as a successful final WAV. Existing raw multitrack sessions and legacy stereo recovery remain unchanged.

Generic interface setup and future MR18 acceptance#

Use the setup wizard or edit private runtime configuration only after obtaining the exact JACK names from the current machine. Choose one stereo capture pair that already contains the desired external-gear mix. Keep interface direct monitoring off for the normal software-monitored workflow, set conservative hardware gains. Leave Input MON off until the hardware direct monitor is disabled, then use MTR MON ON; audio.graph.enabled is needed only for automatic final-bus startup, not for that explicit input-only action.

Optional sources reconcile automatically when they appear or return. MTR RESET remains a manual retry for a stopped or failed bus. Neither path rewrites the mapping or chooses another port.

No MR18 name is compiled into SHR. A future MR18 acceptance must follow the hardware plan: discover and record the actual names, confirm the intended two-channel external mix, decide direct-monitor behavior, then test full duplex at conservative level. It must verify channel identity, source unplug/reconnect faults, no doubled direct/software path, final playback versus WAV equality, xruns/dropouts, and teardown restoration. Synthetic tests and the current AudioBox-era configuration are not an MR18 pass.

Maintainers can exercise the production hardware-independent path with:

shr final-mix-stress DEST [SECONDS] [RATE] [CALLBACK]

It uses four distinguishable stereo sources, the production faders/strip, bounded callback handoff, stereo writer, and full PCM equality check without opening JACK, starting a synth, transmitting MIDI, or producing sound. See maintainer helpers.

Back to detailed guides

SHR-DAW's raw recorder records a deliberately configured collection of JACK audio source ports as one synchronized take. It is interface-neutral: an MR18, a two-input sound card, a virtual JACK source, or another multichannel USB interface uses the same recorder. It does not audibly monitor, mix, process, overdub, or edit these inputs; its Levels screen does meter the first 18 configured sources. It remains distinct from the owned performance bus and its one-file post-strip final stereo recording. Use the interface or mixer for safe low-latency audible raw-input monitoring.

This page owns source mapping, callback guarantees, take storage, recovery, and the hardware-free stress path. The menu manual owns the visible Recorder and Levels controls.

What one take guarantees#

All armed tracks enter and leave capture on the same JACK callback boundary. One callback copies every channel into one preallocated interleaved SPSC ring, or rejects the whole callback. The callback performs no file I/O, allocation, logging, sleep, mutex/condition wait, or collection growth. One ordinary worker thread drains the ring and writes the stems.

A successful take has one JACK sample rate, one frame count, stable track order, and one mono 24-bit PCM WAV per armed track. A mono file keeps physical input identity obvious and gives every channel its own RIFF data limit rather than sharing the short 4 GiB ceiling of one large interleaved file.

The configured global safety bound is 64 tracks. It is not an MR18 limit: it bounds callback work and preallocated memory on this small appliance while leaving ample room above the 18-channel acceptance target. capture.ring_frames is a per-timeline capacity shared by every channel; at 18 channels and 262144 frames the sample storage is about 18 MiB. capture.maximum_callback_frames must be at least the largest JACK period the machine will use.

Storage planning#

Raw stem storage grows independently of the callback-ring capacity. For 24-bit mono PCM without compression, the approximate payload rate is:

channels × sample_rate × 3 bytes per second

At 48 kHz, WAV headers and the session manifest are negligible beside the audio payload:

Armed mono channels	Approximate payload per hour
1	0.52 GB
18	9.33 GB
32	16.59 GB
64	33.18 GB

These are decimal drive-manufacturer gigabytes. A nominal empty 128 GB drive therefore holds less than 7.8 hours at 32 channels, and the real recording allowance is lower after the OS, builds, Projects, filesystem reserve, and a deliberate free-space safety margin. Choose capacity from channel count and retained hours rather than treating any drive size as universally excessive.

Configuration and exact routing#

New tracks use repeated lines in the private shsynth.conf:

capture.directory=~/.local/share/shsynth/recordings
capture.client=shs-recorder
capture.ring_frames=262144
capture.maximum_callback_frames=4096
capture.track=input-1|Input 1 · Vocal||mono|true|exact-client:exact-port
capture.track=input-2|Input 2 · Guitar||mono|true|exact-client:another-port
capture.track=line-l|Line L|line-pair|left|false|
capture.track=line-r|Line R|line-pair|right|false|

Fields are stable ID|musician label|optional group|role|armed|preferred source. Roles are mono, left, or right. Left/right roles with the same group describe a logical stereo pair in the manifest; the WAVs remain mono. IDs are safe, unique names and remain stable when the visible label changes.

The preferred source is an exact JACK name owned by this machine. Blank means unassigned. It never means port zero, silence, the first discovered port, or a nearby name. Runtime discovery distinguishes resolved from missing without rewriting the preference; the native list labels only the exceptional MISSING state. An armed missing track blocks start. Disarm it or deliberately assign the correct discovered source. REFRESH resolves the same remembered name again when the interface returns.

Old capture.input=NAME|LEFT|RIGHT configuration remains supported. When no new capture.track lines exist, the first legacy pair becomes one armed linked left/right pair in memory. Existing stereo recording configuration therefore continues to produce two synchronized mono stems in one take directory.

The 40×13 workflow#

Open AUDIO. The selection-following five-row list shows an arm dot, track number, and label. Healthy routing is silent; an unresolved remembered source adds MISSING. The selected track has one compact source-and-level row. The last two body rows are reserved for recording integrity/recovery and the final take basename, so drops, xruns, incomplete publication, and writer faults cannot be displaced by a long track list.

The body ends above the two controller rows. The final terminal row is the shared status row; its first cell is steady white ■ while stopped or a red ● pulsing only between normal and bright red while a take is active. Useful recorder state or faults may follow after one space.

• RECORD: RECORD starts/stops the synchronized take; ARM toggles the selected track.
• TRACK: select PREV/NEXT, cycle a deliberate SOURCE assignment, or edit the track NAME KB; custom text currently requires the computer keyboard.
• SETUP: ALL arms every resolved track, NONE disarms everything, and REFRESH discovers JACK sources without rewriting remembered assignments.
• SYS: PANIC safely stops owned activity, HELP explains the screen, and EXIT returns Home.

Keyboard equivalents are R, arrows or J/K, Space, A, X, S, N, and F. Track edits save to private runtime configuration. They are refused during a take.

The 18-channel Levels overview#

Audio Recorder LEVELS opens a separate overview whose purpose is level comparison, not track setup. At exactly 40×13, columns 1–20 hold all 18 meters as 6 + blank + 6 + blank + 6. Rows 2–10 are the nine circular LEDs and rows 11–12 hold compact channel labels. Columns 21–40 are a visible TAKE, CHANNEL, or SYS command page. The two normal controller rows are intentionally omitted, but row 13 remains owned only by the shared status renderer.

The ascending dBFS ladder is −48, −36, −30, −24, −18, −12, −6, −3, and −1. Smoothed RMS fills it. A brighter same-colour sample-peak LED holds for 900 ms, then decays at 24 dB per second. Green covers −48 through −18, yellow −12 through −3, and red −1. A two-second held C indicates an actual clipped or non-finite sample, while normal near-peak activity retains its ordinary meter colour. Dark-gray LEDs with a normal number are silence; M is an unresolved configured source and F is a meter/callback fault. The shared row reports the current useful fault or recovery rather than repeating 18 routes.

Encoder turn, keyboard Left/Right or j/k, and pointer clicks select one channel without changing the visible set. Encoder click, Enter, or Space toggles that channel's arm. TAKE offers SETUP, RECORD, STOP, and RESET; CHANNEL offers PREV, NEXT, ARM, and REFRESH; SYS offers STOP, PANIC, HELP, and EXIT. PageUp/PageDown changes the visible command page. Selection and page survive ordinary navigation and reset only when a new or loaded Project replaces the owning context.

Below native geometry the screen uses the ordinary compact layout and shared controller/status rows; it never crops or banks the 18-channel overview. Metering and recording use mutually exclusive recorder-owned JACK clients and the same exact configured sources, so opening Levels never duplicates a route beside an active take or changes unrelated connections. The meter callback publishes one fixed 18-channel atomic snapshot: bounded channel/frame loops, no allocation, locking, file access, logging, or formatting. Stop closes the owned take literally. Panic also closes the owned meter client and follows the global All Notes Off contract; clean shutdown closes either owned client.

Session directory and manifest#

The writer first owns a unique *.take.part directory. Complete publication uses a no-replace rename to *.take; a detected damaged take can only become *.incomplete.take. A successful directory resembles:

recording-…​.take/
  01-Input-1---Vocal.wav
  02-Input-2---Guitar.wav
  session.json

session.json is format version 1. It records the take name, rate, total frames and duration; stable IDs and labels; grouping/role; preferred and actual JACK source; WAV filenames and per-file frame/finalization state; completeness; drop, overflow, callback and xrun counts; writer high-water mark; and recovery notes. Unknown manifest versions are not rewritten.

Ring overflow, a dropped callback, JACK xrun/shutdown, oversized callback, null JACK buffer, source disconnect, unequal final frames, storage error, WAV limit, flush/fsync error, or publication failure prevents a complete result. The UI reports the reason and location instead of presenting damaged stems as successful.

On the next start, a recognized interrupted session is recovered without following symlinks. Each valid partial mono WAV is truncated to the shortest whole-frame count shared by all stems, finalized, and published only as recovered-incomplete; its manifest says that review is required. The old single stereo .wav.part recovery path is retained.

Hardware-free 18-channel soak#

This command does not open or start JACK and cannot make sound:

shr recorder-stress /explicit/temp/destination 60 18 48000 128

Arguments are destination, seconds, channel count, sample rate, and callback frames. Defaults after the required destination are 10 18 48000 128. It paces deterministic distinguishable channel data in real time through the production ring/writer, publishes a real take below only that destination, then verifies completion, equal frame counts, and channel identity. Its report includes elapsed time, write throughput, high-water frames, drops, overflows, and the exact session path. It never deletes the destination or unrelated files.

Platform references#

JACK explicitly forbids I/O, allocation, printf, mutex locking, sleeping, waiting, polling, joining, and condition waits in the process callback; its shutdown callback must be async-safe. See the official JACK callback contract. Linux exposes USB-audio stream capabilities and state in /proc/asound/card*/stream*, which the kernel documentation calls useful for debugging; see ALSA proc files and the snd-usb-audio driver parameters.

Back to detailed guides

This is the concrete checklist for the first full hardware test. The planned unit is a Midas M AIR MR18; the recorder itself remains generic JACK capture. The complete target is simultaneous independent 18-channel playback and 18-channel recording through the same 18×18 interface. Do not claim MR18 success or mark this experimental track checked until every applicable row below passes on the attached unit.

This physical pass is the later multichannel evidence boundary. Complete the platform/workflow foundation and the owner-defined FT2 work first; see the experimental roadmap.

Current status and next borrowing gate#

On 2026-07-22, the first borrowed MR18 was still packed in its bag. It was not unpacked, inspected, powered, connected, configured, or tested. No mixer scene, routing, firmware, clock, or other state was read or changed, so there is nothing from that loan to restore and no MR18 evidence to preserve as a pass or failure.

The current synchronized recorder supplies the 18-channel capture foundation and a fixed all-input Levels overview; neither is an MR18 hardware result. The current performance bus supplies stereo playback, not 18 independent playback channels. The 18-output path and its hardware-independent identity, failure, retry, and result collection must therefore be implemented and rehearsed before the next loan. Do not use borrowed-hardware time to invent that workflow.

Borrow the MR18 again for several days only after:

• the Raspberry Pi 5 clean installation and machine-setup path has completed;
• the unrelated working-flow blockers have been resolved and their recovery paths are usable;
• 18 distinguishable playback streams and 18 synchronized capture slots can be prepared without guessing hardware names; and
• the full-duplex checklist, measurements, storage, safe output state, and result capture are ready before the mixer is unpacked.

These are readiness gates, not calendar deadlines. Capture-only, playback-only, and synthetic results remain useful diagnostics but cannot substitute for the physical 18-in/18-out full-duplex pass.

Verified facts and unit-specific checks#

Verified from the current official MR18 product page, MR18/MR12 user manual, and current quick-start guide:

• The unit has 16 combo mic/line inputs with Midas PRO preamps plus balanced line inputs 17–18.
• Its computer connector is USB 2.0 Type-B. The interface is bidirectional 18×18 audio and 16×16 MIDI; up to 18 audio channels can be recorded at once.
• The specification lists Linux as supported, 44.1 and 48 kHz operation, and 24-bit A/D-D/A conversion at those rates. The current manual tells Windows users to obtain a driver; the official Downloads tab offers no Linux audio driver. This supports ordinary Linux USB-audio operation, but the current manual does not use the literal phrase “class compliant.” On the future borrowed unit, confirm it binds to Linux snd-usb-audio without a vendor driver before recording “class-compliant Linux” as the observed result.
• The mixer can use 18×18 or 2×2 USB mode. Input/USB routing is freely assignable, USB sends/inputs are selectable, and the block diagram shows input tap choices including pre-HP, pre/post gate, pre/post EQ, pre/post fader, and post-pan. Choose and record the intended dry or processed tap; do not assume the current scene is 1:1 or dry.
• The manual says to mute Main LR before changing between 44.1 and 48 kHz because pops can occur.
• As checked on 2026-07-19, the official Downloads tab lists MR18 firmware 1.25.0 for both Hardware V1 and Hardware V2 (release filenames dated 2025-11-18), older 1.22.0, M-AIR Edit Linux 1.8.1, Raspberry Pi 64-bit 1.8.2, and the current manuals. Record hardware revision and installed firmware first. Do not update merely because a newer package exists.

Still assumptions until observed on this exact mixer/Pi/cable:

• the USB descriptors, vendor/product IDs, ALSA card ID and device/subdevice;
• whether snd-usb-audio binds cleanly and exposes 18 capture channels;
• whether it also exposes 18 playback channels and remains stable with both directions active;
• the exact ALSA and JACK capture/playback names and their order;
• installed hardware revision, firmware, scene, clock, USB mode and send taps;
• stable operation at the chosen period count/buffer, storage target, and all 18 channels in both directions on this Raspberry Pi.

Safe step-by-step procedure#

Begin only after the readiness gates above pass. One person should call each change; another should watch outputs, JACK, storage, and the result sheet.

1. Read the front/rear label and control app identification. Confirm the unit is Midas M AIR MR18, not MR12, XR18, X18, or another mixer.

2. With power disconnected, inspect the case, IEC inlet/cable, USB Type-B socket, network socket, connectors, vents, liquid/impact damage, and any unsafe cabling. Confirm the official auto-ranging 100–240 V, 50/60 Hz power requirement from the unit/manual.

3. Leave microphones disconnected. Do not enable phantom power blindly. Note every already connected source and whether it can safely receive 48 V.

4. Connect mixer control by wired Ethernet where practical. Audio is USB, not Ethernet/Wi-Fi. Do not rely on the built-in 2.4 GHz access point for control during acceptance when a wired path is available.

5. Open M-AIR Edit without changing settings. Record hardware revision, installed firmware, clock rate, USB mode, and scene/show name. Compare the installed version with the official Downloads tab; do not update unless a specific verified defect requires it and a rollback/recovery plan exists.

6. Save/export the existing scene/show to the control computer before any routing change. Record the backup filename and verify it can be seen.

7. Mute Main LR and make every physical output safe. Confirm monitor wedges, headphones, amps and PA cannot surprise anyone. The manual specifically warns of pops on clock-rate changes.

8. Use a known-good, short USB 2.0 Type-B data cable. Connect the MR18 directly to a suitable Pi USB port for the baseline, avoiding an unverified hub. On Raspberry Pi 4, all USB 2.0 traffic shares the VL805 USB 2.0 hub; keep other USB traffic controlled and record the storage connection. See the official Raspberry Pi USB documentation.

9. Set the MR18 to 48 kHz while outputs remain safe. Configure ALSA/JACK for the same 48 kHz only through the normal owned setup procedure. Do not let two layers disagree or resample unnoticed.

10. Confirm the MR18 is in 18×18, not 2×2, USB mode. Save the observed setting in the results.

11. Inspect Linux read-only before changing SHR configuration:

    lsusb
    cat /proc/asound/cards
    arecord -l
    cat /proc/asound/card*/stream* 2>/dev/null
    jack_lsp -p -t
    

    Confirm the actual USB device, snd-usb-audio binding, supported 18-channel 48 kHz streams in both directions, and JACK capture sources and playback sinks. Do not infer names from this plan.

12. While SHR is stopped, prepare 18 private logical slots if they do not already exist. This is a portable label template, not a device route; every blank final field must remain missing until deliberately assigned:

    capture.track=input-1|Input 1||mono|false|
    capture.track=input-2|Input 2||mono|false|
    capture.track=input-3|Input 3||mono|false|
    capture.track=input-4|Input 4||mono|false|
    capture.track=input-5|Input 5||mono|false|
    capture.track=input-6|Input 6||mono|false|
    capture.track=input-7|Input 7||mono|false|
    capture.track=input-8|Input 8||mono|false|
    capture.track=input-9|Input 9||mono|false|
    capture.track=input-10|Input 10||mono|false|
    capture.track=input-11|Input 11||mono|false|
    capture.track=input-12|Input 12||mono|false|
    capture.track=input-13|Input 13||mono|false|
    capture.track=input-14|Input 14||mono|false|
    capture.track=input-15|Input 15||mono|false|
    capture.track=input-16|Input 16||mono|false|
    capture.track=input-17|Input 17 · Line L|line-17-18|left|false|
    capture.track=input-18|Input 18 · Line R|line-17-18|right|false|
    

    Then copy the exact observed JACK source names into those private mappings using the AUDIO screen. Never put observed names in Rust, tracked examples, or public Projects. Refresh and verify each assigned preference says ready; leave every unassigned slot disarmed.

13. In M-AIR Edit, inspect Inputs/USB routing and USB sends. Configure USB channels 1–18 to the intended individual input sources and explicitly record each tap. For a dry-stem baseline choose the suitable pre-processing tap only after confirming its label on the actual firmware. Keep the scene backup untouched.

14. With outputs safe, inject one distinctive safe signal into one input at a time. Use a line-level generator for 17–18 and source-appropriate levels for 1–16. Never create a loop from mixer output to input. Never apply phantom power without confirming the connected device and cable support it.

15. For each input, confirm only the intended selected-track meter responds and record its physical input → USB channel → observed JACK port → SHR track ID. Stop immediately on a swap, duplicate, bleed, unexpected processing, clip, or missing channel.

16. Run capture-only progressive takes at 2, 4, 8, 12, 16, then 18 armed channels. Re-run the single-input identity check when a larger group first fails.

17. For every capture take, inspect all mono WAV headers and session.json. Require one rate, identical non-zero frame counts, expected duration, complete state, zero drop/overflow/callback/xrun counts, correct source identity, and no unintended signal in other stems.

18. With every physical output still muted or disconnected, route one prepared, low-level, distinguishable playback stream at a time to each observed JACK playback sink. Verify the intended MR18 USB return meter and no other return responds. Record JACK sink to USB return identity; do not infer channel order or make this an audible test.

19. Run playback-only progressive tests at 2, 4, 8, 12, 16, then 18 concurrent streams. Require continuous output timelines, correct independent identity, and zero JACK xruns or source-loss events.

20. Run full-duplex progressive tests at 2-in/2-out, 4-in/4-out, 8-in/8-out, 12-in/12-out, 16-in/16-out, then 18-in/18-out. The final row must record 18 synchronized capture stems while all 18 independent playback streams remain active and correctly mapped.

21. During each run monitor JACK xruns, recorder drop/overflow and writer high-water, callback setting, CPU per core, temperature, memory, free space, playback continuity, and sustained storage throughput. Useful read-only views include jack_iodelay only when deliberately wired for it; do not alter this test's graph casually. Use ordinary system tools for CPU/thermal/storage.

22. Increase duration only after the previous channel count passes: 30 s map check, 5 min stability, then 30 min and a longer soak as time/storage allow.

23. Record sample rate, JACK frames/period and periods/buffer, storage target, filesystem/free space, cable/USB port, and all results. If latency changes, write the new value and rerun the lower-channel baseline.

24. Stop on corruption, channel swap/bleed, playback discontinuity, non-zero recorder drop/overflow, JACK xrun, source loss, thermal throttling/warning, power warning, low-space warning, write/finalization error, or unequal frames. Preserve failed take and logs; do not relabel it successful.

25. Restore the saved mixer scene and normal output safety state after testing. Confirm SHR has stopped recording and owns no stale JACK ports. Do not leave phantom power or routing changed without an explicit handoff.

Pass/fail thresholds#

A row passes only when:

• every armed source is exact and independently verified;
• session.json is complete, every WAV is mono 24-bit at the selected rate, and all frame counts equal the expected callback-bounded timeline;
• channel identity passes with no swap, duplicate, or measurable/visible unintended test signal in another digital stem;
• every active playback stream reaches exactly its intended USB return with no swap, duplicate, bleed, discontinuity, or silent substitution;
• JACK xruns, recorder dropped frames, overflow events, callback violations, source-loss events, and write/finalization errors are all zero;
• no power/undervoltage or thermal warning occurs, temperature stays below the machine's throttling threshold, free storage retains at least the agreed reserve, and observed throughput has margin over the recorded stem rate;
• CPU and writer high-water remain stable rather than growing without bound.

Any violated item fails the row. Higher latency may be a valid diagnosed fix, but only after recording the change and repeating the lower-channel baseline.

Printable results#

Mode	Capture × playback	Rate	JACK frames / periods	Duration	Xruns	Recorder drops	Playback faults	Writer high-water	Max CPU	Max temp	Frame counts agree	Channel identity	Pass/fail	Notes
Capture	2×0	48 kHz					n/a
Capture	4×0	48 kHz					n/a
Capture	8×0	48 kHz					n/a
Capture	12×0	48 kHz					n/a
Capture	16×0	48 kHz					n/a
Capture	18×0	48 kHz					n/a
Playback	0×2	48 kHz				n/a		n/a			n/a
Playback	0×4	48 kHz				n/a		n/a			n/a
Playback	0×8	48 kHz				n/a		n/a			n/a
Playback	0×12	48 kHz				n/a		n/a			n/a
Playback	0×16	48 kHz				n/a		n/a			n/a
Playback	0×18	48 kHz				n/a		n/a			n/a
Full duplex	2×2	48 kHz
Full duplex	4×4	48 kHz
Full duplex	8×8	48 kHz
Full duplex	12×12	48 kHz
Full duplex	16×16	48 kHz
Full duplex	18×18	48 kHz
Full duplex long	18×18	48 kHz

Observed identifiers and routing:

Physical input	Intended tap	USB channel	Observed ALSA/JACK source	SHR stable ID	Identity result / notes
1–16
17 L
18 R

Observed playback routing:

SHR stream	Observed JACK sink	MR18 USB return	Identity result / notes
1–16
17
18

Future final-bus acceptance (not yet run)#

After the raw 18×18 full-duplex matrix passes, obtain—not guess—the MR18 JACK capture names for the deliberately mixed external stereo pair and place them in the private audio.graph.input setting. With monitor/speaker level controlled, verify synth-only, loop-only, input-only, and all-three identity; confirm there is no parallel direct loop/synth path; and deliberately choose either interface direct monitoring or the software path. Exercise source disconnect/reconnect, transaction rollback, final-recording fault behavior, L/R identity, limiter latency, JACK xruns/timing, and playback/file equality. Record exact observed names, period count, converter latency, and results here. Synthetic tests do not count as this physical acceptance.

Back to detailed guides

Created: 2026-07-19

Status: presentation aid with a still-gated physical MR18 result

This script is truthful before and after the MR18 test. Replace the bracketed hardware result only when the signed test sheet supports it.

Script and shot list#

0:00–0:25 — old limitation. Show the previous stereo-recorder image or a two-channel legacy configuration. Say: “SHR-DAW used to capture one configured stereo pair into one 24-bit WAV. That was useful for a mix, but it could not preserve a whole band's independent inputs.” On screen: Before: 1 stereo WAV.

0:25–0:55 — generic architecture. Show the compact AUDIO track list. Say: “The recorder now accepts an arbitrary deliberately mapped set of JACK audio sources. Every callback transfers all armed channels together into one bounded, preallocated ring. Disk writing happens off the audio thread.” On screen: Generic JACK capture · 1–64 configured tracks · no software monitoring and One shared start/stop callback boundary.

0:55–1:25 — musician workflow. Select several tracks named Input 1 · Vocal, Input 5 · Bass mic, and Line L/R. Show arm dots, source assignment, NAME, ALL/NONE, then open Levels. All 18 nine-segment columns remain visible; show one quiet group, nominal green, yellow/red peaks, and a missing M. Say: “I name and route inputs in setup, then compare every recording level at once. Selection never hides a channel. A missing source stays missing and blocks start; SHR never substitutes a nearby port.”

1:25–1:55 — result. Stop. Show one .take directory, its separate mono WAV files, and session.json. Highlight sample_rate, total_frames, each track's stable ID/label/preferred and actual source, filename, equal frame count, completeness: complete, and zero error counters. Say: “Each physical input is directly importable as a mono stem. The shared manifest proves the common timeline and records exactly what was connected.”

1:55–2:20 — failure honesty. Temporarily show a configured preferred source with the interface absent. Do not remap it. Say: “Portable labels may be blank, but a remembered machine route remains exact. Offline hardware is visible and cannot silently become another input. Overflow, xrun, disconnect, JACK loss, write failure, or unequal finalization marks the take incomplete.” On screen: missing ≠ fallback and damaged takes never appear complete.

2:20–3:00 — MR18 target and evidence. Say: “This is not an MR18-specific recorder. The Midas M AIR MR18 is tomorrow's first full acceptance target: 18×18 USB audio, 16 mic/line inputs plus stereo line inputs 17–18, 24-bit conversion, and 44.1/48 kHz support. We will test all 18 at 48 kHz progressively and record xruns, drops, high-water, CPU, temperature, storage, frame agreement, and identity.”

Before hardware acceptance, finish with: “Today the production buffering and file path have passed synthetic 18-channel 48 kHz validation. That is not an MR18 hardware result.” On screen: SYNTHETIC · 18 ch · 48,000 Hz · [period] · [duration] · 0 dropped · identity verified.

After a real pass only, replace that line with the exact signed result: MR18 HARDWARE PASS · 18 ch · 48,000 Hz · [frames × periods] · [duration] · 0 xruns · 0 dropped · identity verified, plus the date, storage target, maximum CPU/temperature, and test-sheet link. Never use the hardware-pass card for a partial, failed, or synthetic run.

Required close-ups#

1. Old stereo limitation.
2. 40×13 Levels overview with all 18 meters in three groups of six.
3. Quiet, nominal, yellow/red, clipped, missing, and faulted meter examples.
4. Several arm dots, elapsed time, active count, drop/xrun/high-water summary.
5. Separate mono 24-bit WAV filenames.
6. Manifest with equal frames, complete state, and zero counters.
7. Generic JACK statement before naming MR18.
8. MR18 acceptance card clearly labelled PLANNED or a dated measured PASS.
9. Synthetic fallback card containing the word SYNTHETIC throughout.

Keep the Audio setup list and Levels overview visibly separate. Levels uses −48, −36, −30, −24, −18, −12, −6, −3, and −1 dBFS, with RMS fill and a brighter same-colour held peak. Do not add selected-channel numeric/route detail or imply that visual metering is audible software monitoring.

Back to detailed guides

SHR-DAW source code, Velvet Tines.synthv1, the 20 newly authored presets, and the bundled original drum-pattern data are released under the MIT license in LICENSE. MIT permits commercial and non-commercial use, modification, and redistribution, but the copyright and license notice must be kept. No MIT/Apache/GPL license is literally obligation-free.

Rust dependencies#

The direct Rust crates are permissive:

• anyhow, libc, serde, serde_json, signal-hook: MIT or Apache-2.0;
• hound: Apache-2.0;
• crossterm, midir, quick-xml, ratatui: MIT.

Their transitive dependencies reported by cargo metadata --locked are also permissive (MIT, Apache-2.0, ISC-style combinations, Unicode-3.0, or Unlicense). Before publishing binary releases, generate and ship the exact notices for the locked target dependency set with a tool such as cargo-about or cargo-deny.

External system software#

SHR-DAW launches these separately installed programs; it does not copy or link their source into this project:

• synthv1: GPL-2.0-or-later;
• Yoshimi: GPL-2.0-or-later overall, with some source under compatible LGPL/CC/ISC terms as documented by its package;
• FluidSynth: LGPL-2.1-or-later;
• JACK2 tools/libraries: primarily LGPL-2.1-or-later;
• aconnect from alsa-utils: GPL-2.0;
• ALSA library used by the Rust MIDI backend: LGPL-2.1-or-later.

SHR-DAW indexes Yoshimi .xiz banks and FluidSynth .sf2/.sf3 files at their configured system/user paths; it does not copy them into this project. The Debian yoshimi-data package is GPL-2.0-or-later overall (with a few bank files under GPL-3), and the packaged TimGM6mb SoundFont is GPL-2-only. Their copyright files remain the authority for redistribution of an appliance image.

Using system-installed executables/data does not force SHR-DAW itself to use GPL. Anyone distributing an appliance image or bundling those binaries must comply with each package separately and provide their notices/source offers as required. This is a practical audit, not legal advice.

Controller mapping references#

SHR-DAW can update its own MIT-licensed, hardware-verified controller catalog. It does not redistribute or execute mappings from Ardour, Mixxx, or Zynthian. Those copyleft-licensed projects are documented as useful research sources in docs/CONTROLLER_PROFILES.md; application-specific bindings are not copied into this repository. Pencil Research's CC BY-SA 4.0 MIDI dataset documents external instruments rather than USB controller surfaces and is likewise not included.

Documentation rendering tools#

The deterministic TUI screenshots are generated from SHR-DAW's own seeded screen data by scripts/render-readme-screenshots.py. That maintainer helper uses Pillow as a PNG container/writer and reads the host's Uni2-TerminusBold24x12.psf.gz Linux console font; it does not bundle Pillow or the PSF font into the installed product-data directory. The helper accepts the repository-local fallback only when its decompressed bytes match the approved host font's pinned SHA-256. Anyone redistributing the generated documentation or a fallback copy of that font should retain and review the copyright/licence information supplied by the corresponding Pillow and console-font packages. The images are presentation fixtures, not evidence that JACK, MIDI hardware, playback, or recording was active.

Preset bank boundary#

The tracked presets/synthv1/ directory and public installation contain only the 21 MIT-cleared presets identified by presets/synthv1/cleared-presets.txt and described in this file. That manifest is the single packaging and schema-test allowlist. Legacy or downloaded presets without verified authorship and redistribution terms belong only in the ignored private $SHSYNTH_USER_DIR/presets/synthv1/ tree. They must not be committed, packaged, mirrored, or relabelled as MIT merely because a copy exists locally.

The 392 Synthv1 Presets archive published by LinuxSynths was inspected on 2026-07-13. It contains 392 .synthv1 files but no README, license, author notice, or redistribution grant. Twenty-eight filenames overlapped the legacy local bank, although those local files were modified rather than byte-identical, so the collection is a likely source for part of that private bank. A private extraction described in docs/WORKSPACE_HANDOFF.md remains below the ignored $SHSYNTH_USER_DIR/ tree; none of it was imported into the tracked or installed public collection. Source: https://linuxsynths.com/Synthv1PatchesDemos/synthv1.html.

Newly authored cleared synthv1 presets#

The following complete synthv1 0.9.29 presets were authored for SHR-DAW on 2026-07-13 from the MIT-cleared Velvet Tines schema/template, with new parameter designs. They contain no imported samples or third-party preset content and are released under this repository's MIT license:

• basses: Deep Sub, Liquid Acid, Rubber Circuit, Compact Bass;
• leads: Mono Pulse Lead, PWM Horizon, Glass Saw Lead;
• pads: Warm Cloud, Dark Canopy, Shimmer Veil;
• plucks/bells: Copper Pluck, Reed Pluck, Silver Bell, Soft Chime;
• organs: Drawbar Glow, Hollow Organ;
• drones/effects: Low Orbit Drone, Frozen Drone, Dust Delay, Restrained Sweep.

scripts/generate_cleared_presets.sh records the exact authored parameter choices. Add a newly cleared file to presets/synthv1/cleared-presets.txt only after its provenance is recorded here. Static tests verify the manifest, all 145 indices and names, and mapped values against the current schema. Sound quality still requires authorized listening tests; none were run while adding this set.

Original drum patterns#

The 60 compact catalog entries and 12 standalone .shdrum files in drum-patterns/ were authored as editable SHR-DAW MIDI data and are released under MIT. They use conventional General MIDI-style drum-note assignments, but they do not copy or transcribe third-party MIDI files or protected recordings. Genre names are creative navigation hints rather than claims of an authoritative cultural transcription. The structural and naming audit is in docs/DRUM_PATTERN_AUDIT.md; groove, feel, and final curation still require human listening.

SHR Drums engine and kit sources#

The in-process drum engine is the separate MIT-licensed SHR Drums repository. Version 0.2 keeps the strict format 1 package boundary and adds an optional advanced modeled-voice graph. The public format contract defines validation and compatibility. Its source record owns sample provenance. kits/cleared-kits.txt is this repository's single public kit allowlist.

SHR-DAW pins the public SHR Drums 0.2.0 source revision in both Cargo.toml and install/compatibility.json. Cargo compiles it into shr; the installer does not create a separate executable, service, or runtime source checkout.

The bundled Acid package is an original fully modeled 27-voice kit. Electronic House has its original 27 modeled voices plus deterministic House Impact and Long Pressure synthetic one-shot exports authored by the CC0 Moj Sint project; they occupy notes 27 and 28 without replacing its existing note-33 through note-36 kicks. Neither package contains recordings or downloaded audio. Their manifests release the package content under CC0 1.0.

The bundled Big Rock (Muldjord) and Experimental Noise (Muldjord) packages use selected recordings from MuldjordKit SFZ+WAV 2020-10-18 under Creative Commons Attribution 4.0 International. Lars Muldjord made the original recordings; roberto@zenvoid.org assembled the stereo SFZ/WAV release for FreePats. Each package retains the upstream licence and README, while its manifest records the source release, selected-file hashes, modifications, and required attribution. Upstream sources are the FreePats release, FreePats kit page, and DrumGizmo kit page.

No other compiled .shrkit, source archive, or private review render is bundled. A local package's presence does not grant redistribution rights; add one to cleared-kits.txt only after reviewing its complete contents, manifest, source record, asset licence, and required notices.

Moj Sint and SHR Sampler#

The whole-system installer fetches the exact public Moj Sint 0.2.3 and SHR Sampler 0.1.2 revisions recorded in install/compatibility.json. Each repository's THIRD_PARTY.md owns its dependency and content provenance. Only Moj Sint files named by presets/cleared-presets.txt and SHR Sampler packages named by instruments/cleared-instruments.txt enter the payload. The initial SHR Sampler package is a project-authored deterministic waveform released as CC0-1.0; no private or third-party sample library is copied or converted.

Public-domain demo compositions#

The ten demo arrangements in demos/ are newly programmed for SHR-DAW and are released under MIT. The underlying compositions are traditional or old enough to be public domain; no MIDI file, harmony, production, or orchestration was copied from a modern recording. demos/cleared-demos.json is the explicit packaging manifest and records separate public-domain reasoning, institutional source links, musical metadata, filenames, and SHA-256 hashes for House of the Rising Sun, Whiskey in the Jar, Cotton-Eyed Joe, Scarborough Fair, Greensleeves, Amazing Grace, Drunken Sailor, Wellerman, Auld Lang Syne, and Danny Boy.

scripts/generate_demo_songs.py is the deterministic authorship recipe. Its normal mode validates every byte and refuses extra files; the Makefile installs only its manifest-derived output after that check. Adding a composition requires source-backed clearance in the manifest, an original arrangement, both MIDI and current native Project forms, and matching structural tests.

Bundled and private-download WAV loops#

The four WAVs named in loops/cleared-loops.txt are redistributable under CC0 1.0 rather than MIT. Their authors, source pages, conversions, exact tempo and hashes are recorded in loops/SOURCES.md. The three starter-100-step-*.wav files come from obscure music's CC0 Music loop variations pack; the war-drums-130.wav file is William Hector's CC0 Horde War Drums loop. Packaging must continue to use the manifest allowlist.

shr-setup can also download four tempo-labelled WAVs from MusicRadar's SampleRadar: 183 free 80s pop drums samples directly into the user's loop inbox. MusicRadar permits use in music but says not to redistribute the raw samples, so neither the 78 MB archive nor extracted WAVs may be committed, packaged, mirrored, or copied into a public release. Setup asks first, stores a source/terms note beside the private files, and downloads from: https://www.musicradar.com/news/sampleradar-free-80s-pop-drums-samples.

Back to detailed guides

Add a patch#

Put a descriptively named .synthv1 file in presets/synthv1/. The filename is the browser name, so use readable title case and avoid numbered experiments. For a new sound, copy a complete current preset such as Velvet Tines.synthv1 as a structural template, then change the sound parameters and root name.

Use synthv1's current 0.9.29 layout: 145 parameters indexed 0–144. Keep every index unique and consecutive, but treat the name attribute as authoritative; SHR-DAW deliberately reads values by name so old presets still work.

Design notes#

synthv1 contains two independent synth sections, each with two oscillators, filter/LFO/amplifier envelopes, output, velocity, and controller settings. Their combined signal passes through chorus, flanger, phaser, delay, reverb, and dynamics. Use the second section for a transient, interval, sub layer, or stereo counterpart instead of only duplicating the first.

The 12 panel values come from these parameters:

Index	Name	Range
17	DCF1_CUTOFF	0–1
18	DCF1_RESO	0–1
21	DCF1_ENVELOPE	−1–1
30	LFO1_RATE	0–1
44	DCA1_VOLUME	0–1
45–48	DCA1_ATTACK through DCA1_RELEASE	0–1
132–134	DEL1_WET, DEL1_DELAY, DEL1_FEEDB	0–1

Choose their initial values carefully: they are the relative-turn baselines, the Playback-screen encoder reset values, and neutral reference for the colored indicators. Keep output levels conservative and leave the limiter enabled unless there is a reason not to.

Validate#

Do not overwrite an existing patch while experimenting. Check that the new sound is discoverable and that the project still passes:

./scripts/local.sh list
cargo test --locked

If xmllint is installed, also run:

xmllint --noout "presets/synthv1/New Sound.synthv1"

Static validation cannot judge tone. Audition through the normal interface only when authorized, compare soft and hard velocities across several octaves, test chords for clipping, and confirm the in-place parameter reset plus all twelve relative controls afterward.

For imported patches, record their origin and license in this document or a nearby note. Do not assume a preset found online is redistributable. Once a patch is cleared for public packaging, add its exact filename to presets/synthv1/cleared-presets.txt; unlisted files are deliberately not installed and make the repository schema test fail.

Cleared SHR-DAW collection#

Velvet Tines and the 20 category-focused presets listed in THIRD_PARTY.md are newly authored/cleared under MIT. Their exact parameter recipes are retained in scripts/generate_cleared_presets.sh; that generator refuses to overwrite an existing file. System Yoshimi instruments and SoundFonts must be configured and indexed in place, not copied here or relabeled as MIT content.

Back to detailed guides

MIT License

Copyright (c) 2026 SHR-DAW contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Back to detailed guides