Skip to content

Performance Controls

This page covers two things that are especially useful during a live show: the trackpad performance surface, and the notes system for keeping reminders attached to your presets and parameters.

Watch: FX chains — open the guided tour

Building a chain
Order and bypass
Metaknobs and the Super Knob
Focus mode
Saved chains
Master FX

Watch: Mixing — open the guided tour

Deck levels
The crossfader
Transitions
AUTO and fade time
The clock

Trackpad Performance Surface

If you're performing on a laptop, you can turn your trackpad into a hardware-style performance controller — a bit like the classic Stanton SCS.3m DJ mixer. Hold CapsLock to activate it.

While CapsLock is held: - The trackpad stops moving the mouse cursor - It becomes an absolute-position performance surface with three faders and a crossfader

Release CapsLock to return to normal mouse control.

Surface layout

┌────────────────────────────────────────────────────┐
│  [Deck A Level]  [Deck BG Level]  [Deck B Level]   │  ← Top 55% of trackpad
│                                                    │
├────────────────────────────────────────────────────┤
│                   (dead zone)                      │  ← Middle buffer zone
├────────────────────────────────────────────────────┤
│              Crossfader  (A ←——→ B)                │  ← Bottom 28%
└────────────────────────────────────────────────────┘

Bottom zone (crossfader): Drag left for Deck A, right for Deck B. The full width maps to the crossfader range. Touch the centre and it snaps to 50/50.

Top zone (level faders): Three vertical strips — left third controls Deck A level, middle controls Deck BG, right controls Deck B. Touch anywhere in a strip to jump the level to that position instantly.

Dead zone (middle): A buffer between the two zones that prevents accidental switches when you're moving fast.

Multi-finger stutters

The real power comes from using two fingers at once. Each zone tracks fingers independently, using a last-in-first-out stack:

Crossfader cut stutters: 1. Hold one finger down on the Deck A side. 2. Tap repeatedly with a second finger on the Deck B side. 3. Each tap snaps the crossfader to B; lifting the tap snaps it back to A.

This gives you machine-gun visual cuts synchronized to your tapping rhythm.

Video strobes: 1. Hold a finger at the bottom of a deck's level strip (level = 0%, blackout). 2. Tap with a second finger at the top of the same strip (level = 100%, full brightness). 3. Releasing the tap drops the deck back to blackout.

This creates rhythmic video flashes and stroboscopic accents.

When all fingers lift from a strip, the level stays frozen where you left it.

Setup on Linux

On Linux, the trackpad surface reads raw multi-touch input directly. This requires read/write permission on the input device.

If the permission isn't set up, you'll see a Touchpad Status: Read/Write Permission Required message in Preferences → General, next to the Enable CapsLock Trackpad Console checkbox, with an Install Permissions (Polkit) button. Clicking it installs the necessary udev rule using pkexec — no reboot required. If you ran the desktop installer script (./install-desktop.sh) when you first unzipped the app, this was done automatically.

On macOS, native trackpad support works without any extra setup.

Focus safety: If Liquid LSD loses window focus (e.g. via Alt+Tab), the trackpad grab releases immediately, so you're never locked out of your mouse.

Notes & Tooltips

Hover tooltips

Hovering over almost any parameter in the app shows a tooltip with: 1. The parameter name, valid range, and factory default value. 2. A plain-English description of what the parameter does. 3. Any personal note you've attached to the parameter (in amber text).

Macro knob tooltips show the value in the target parameter's real units, with the knob position as a percentage: ZOOM: 5.00 (100%). The same real value is shown on the knob face (always while a row is in Edit, otherwise on hover).

Tooltips appear after a short delay (~250ms) so they don't flash annoyingly as you move the mouse.

The three-tier notes system

You can attach notes at three different scopes:

Scope What it's for Where it's stored When it appears
Source Note Notes about a visual generator (e.g. "Gyroid works best with low gain feedback") ~/.liquid-lsd/source-notes.json Stays with you globally, across all presets
Preset Note Notes about a specific preset Inside the .lsd file Shows when hovering the preset name label on the deck monitor
Parameter Note A reminder about a specific parameter in a preset Inside the .lsd file Shows in the parameter's hover tooltip

Source Notes are global and persist no matter which preset you load — good for tips about generators that are always true. Preset and Parameter Notes travel with the preset file when you share it.

Adding and editing notes

Parameter notes: Hover over any parameter row in Edit's parameter grid and click ⋮ (or right-click the parameter name), then choose Add/Edit Parameter Note...

Preset notes: Right-click the preset name label below the deck monitor preview and choose Add/Edit Preset Note...

Source notes: Open the Deck Menu popup and choose Add/Edit Source Note...

All three open the same note editor: a multi-line text box up to 2048 characters. Press Ctrl+Enter to save, or Escape to cancel.

The preset name label

Below each deck's monitor preview you'll see the name of the currently loaded preset. Hovering it shows the full file path, the last save time, and the preset note if one exists. A * next to the name means there are unsaved changes.

If no preset is loaded yet (the deck is in an unsaved state), the label shows Untitled in grey. You can't attach a preset note until the preset has been saved at least once.

FX Chain & Slot Management

Every deck and the master bus each own one FX chain of 3 serial ISF filter slots: a deck's chain is its FX sub-tab, and Master FX (the Mixer's FX sub-tab in Edit) is applied to the final output after the crossfader. All five chains work the same way. Each chain has a Chain Super Knob and each slot its own Metaknob — see Macro Controls & the Perform View for the FX Rack view that exposes these.

  • Deck row layout: the deck badge (A, B, BG, PV) carries a caption, slate SRC or cyan FX, naming the half the row shows. Line 1 is the long name box (click to Browse) and the Edit gear; line 2 holds ⋮, Save, queue ◀ ▶ and the slot pills on an FX row, or ⋮, Save, ◀ ▶ and a right-aligned Eject on a source row (same button sizes on both).
  • Chain Header Kebab (⋮):
  • Save Chain As...: Saves that chain's 3 slots (and its Super Knob state) into an .lsdfxchain file in library/fx_chains/.
  • Copy Chain / Paste Chain: Copies or pastes one chain's 3 slots between any decks and Master FX.
  • Clear Chain Slots: Disposes and empties that chain's 3 slots.
  • Per-Slot Kebab (⋮):
  • Save Slot Preset As...: Saves the slot's filter ID, dry/wet, Metaknob position/target, and parameters into an .lsdfx file in library/fx/.
  • Copy Slot / Paste Slot: Copies or pastes individual slot configurations across slots or chains.
  • Clear Slot: Clears the slot filter and resets parameters.
  • Drag-and-Drop Targets: Drag .lsdfxchain onto a chain header, or .lsdfx onto a slot, to instantly load/swap effects.
  • Library Browser: The [ FX ] Library view's right-click menus can load stock filters, saved singles, and saved chains into any deck or Master FX.
  • FX is separate from presets: Loading or saving a deck preset (.lsd) never touches that deck's FX chain. FX chains are saved with your session and restored on the next launch.
  • Performance Matrix FX Controls:
  • Shared Chain Header ([◀] Name • [▶] [Save] [⋮] ... [BYPASS]):
    • ◀ / ▶ (Decks A, B, BG): On Decks A, B, and BG, steps through the respective live FX queue (A/B or BG) directly on that deck, advancing the queue while targeting the clicked deck. Rendered disabled when the FX queue is empty. Omitted on Deck PV and Master FX, allowing the chain name button to expand while keeping row width perfectly aligned.
    • Chain Name Button: Displays current chain name with • dirty indicator when modified from baseline. Clicking binds the Library dock below to this chain (the Chain list: no row is expanded, and the name gets a coloured outline; ✕ or Esc lets go), with live text search over saved .lsdfxchain files. Accepts .lsdfxchain drag-and-drop.
    • [Save]: Overwrites the loaded chain file with current state, or triggers Save As if untitled.
    • [⋮] Menu: Save As..., New Chain, Revert to Saved (undoes tweaks back to clean loaded state), Clear All Slots, and Copy/Paste Chain.
    • [BYPASS]: Top-level kill switch to immediately bypass or re-enable the entire FX chain.
  • FX Slot Cells (Effect Name):
    • Drawn under each of knobs 2–4 on Deck rows in [FX] mode and the Master row in [FX] mode. The cell is just the effect name, so names get the full cell width.
    • ◀ / ▶ (on hover), Mouse Wheel, or Right-Click → Previous/Next in Shortlist: Steps to previous/next effect in the FX Shortlist (favorited ★ effects, or the current effect's category alphabetically). The arrows only appear at the cell's edges while the mouse is over it.
  • Slot Side Buttons (left of each slot knob): two stacked buttons.
    • Link (top): links/unlinks that slot's Metaknob to the Super Knob.
  • Chain Link (left of the Super Knob, knob 1): links or unlinks all three slots at once. Click links all unless they are all linked already, in which case it unlinks all; the icon shows a chain when every filled slot is linked, a dimmer chain when only some are, and a broken chain when none are. The Macro Strip has the same toggle by the CHAIN MACRO title. Where a new chain starts (linked or unlinked) is the Default FX chain linking preference.
    • Bypass (bottom, power icon): turns just that effect on or off. Row-coloured when on, red when bypassed, dim when the slot is empty. In Focus Mode, only the focused slot's bypass is shown, next to knob 1.
    • Effect Name: Truncated caption showing loaded filter. Click opens the pair view with Browse on that slot (Stock filters, ★ Favorites, and Saved .lsdfx presets). Browse opens a moment after you release the click, so a double-click (Focus Mode) or a drag doesn't open it.
    • Drag & Drop: Drag an effect name onto another slot's name to swap/reorder (hold Ctrl while dropping to duplicate). Accepts stock ISF filters and .lsdfx single presets from Library.
    • Right-Click Context Menu: Focus Mode, Previous/Next in Shortlist, Replace..., Save as FX Preset..., Copy/Paste Slot, Reset Parameters, Clear Slot, Add/Remove from FX Shortlist (★), and Edit in Edit.
  • Swap Gain Dip:
    • Replacing an effect or loading a chain applies a smooth audio/visual gain dip (fade out -> swap -> fade in) instead of a hard cut.
    • Duration is customizable in Preferences (FX Swap Fade (ms), 0–1000 ms, default 150 ms; 0 = immediate hard cut).
  • Knob Labeling:
    • Knob 1 controls the chain's SUPER knob.
    • Knobs 2–4 display META (or the target parameter name when custom-routed), while the effect name itself is clearly displayed in the slot cell below.
  • Focus Mode (Traktor / Mixxx style):
    • Entering Focus Mode:
    • Click any slot pill ([1], [2], or [3]) in the FX row header.
    • Or double-click any slot cell's effect name.
    • Or right-click a slot cell and select Focus Mode (Edit Parameters).
    • Header Controls in Focus Mode:
    • [⋮]: Chain kebab menu remains accessible for Save As, Clear, etc.
    • [Focused Effect Name ▾]: Displays the name of the focused effect; clicking opens the pair view's FX Browse directly for that slot to audition or swap shaders.
    • [◀ P1/N ▶]: Parameter page stepper; appears automatically whenever the focused shader exposes more than 3 parameters.
    • [1] [2] [3]: Slot focus pills with clean styling. The active slot pill is highlighted in blue accent. Click another slot pill to switch focus instantly, or click the active focused slot pill a second time (or press Escape) to exit Focus Mode back to the 3-slot chain view.
    • 4 Knobs in Focus Mode:
    • Knob 1 (META): The focused slot's Metaknob ($chainLabel/FX/FX<slot>/Meta). Its Dry/Wet is the Wet slider in the chain header. The focused slot's FxSlotCell is drawn underneath so shortlist stepping (hover ◀ ▶ or mouse wheel) and picker access remain directly below the knob, with the slot's bypass button to its left.
    • Knobs 2–4 (Top Parameters): Dynamically retargeted to the focused shader's parameters on the active page, in the slot's knob order (set in the Edit bay's Knobs list; the effect's own order by default) (e.g. SPEED, INTENSITY, COLOR).
    • Parameter Cells (FxParamCell): Drawn under Knobs 2–4 with the parameter's name and a modulation indicator dot. The current value is shown inside the knob face, and a [⟲] reset button (restores the authored default) sits to the left of the knob.
  • Stable Layout: Knobs stay the same size and in the same place whichever mode a row is in (source, FX group, or Focus Mode), and switching one row never resizes the others. Knob names and effect/parameter names share the same line under each knob. Names too long for it end in …; hover the knob for the full name.
    • Seamless Hardware MIDI Retargeting:
    • Physical MIDI controllers mapped to the row's standard macro paths (Macro/<bankId>/knob_1..4) immediately control the focused slot's Metaknob and parameters without requiring any MIDI remapping or controller mode switching.
    • Exiting Focus Mode restores Knob 1 to SUPER and Knobs 2–4 to META.
  • Performance Matrix Tabs:
    • Deck FX chains are on each deck's FX row; Master FX is on the Master FX row, on the MIXER tab.
    • The Transitions row includes a [DICES] die button to randomize transition parameters with undo support.

MIDI Hardware & Control Mappings

Liquid LSD includes an intelligent, multi-type MIDI subsystem for connecting hardware controllers (DJ controllers, fader banks, rotary knobs, pads, foot switches, and keyboards).

Quick Setup

  1. Connect your USB or DIN MIDI interface.
  2. Open Preferences → MIDI Controls (or press Ctrl+,).
  3. Ensure Enable MIDI Subsystem is checked. The background watchdog automatically detects newly connected controllers without restarting the application.
  4. Check the Live MIDI Monitor (Sniffer) at the top of the panel: moving any knob or pressing any pad on your controller will immediately stream incoming packets (Channel, Message Type, Index, and Values).

MIDI Learn & Modulator Variables

You can map any parameter, internal modulator variable, matrix CV modulator, or global performance action:

  1. In-Situ Right-Click Learn (Fastest):
  2. Right-click any slider or variable label in the UI — including an LFO's Speed / Subdivision, Depth, Min/Max bounds, Asymmetry (Slope), Morph, Hold, or a parameter's Initial Range (Base Value).
  3. Select Learn MIDI Mapping (...) from the context menu. This is a controller mapping: it sets the value itself and is saved in your controller profile, not in the preset. The slider will pulse in cyan/blue while awaiting hardware input.
  4. Move a knob, fader, or press a pad on your MIDI controller. Liquid LSD immediately maps the control, preserves your configured min/max limits, and saves the mapping to the active profile.
  5. If a macro knob currently drives that value (its slider shows the cyan lock and a [K#] badge), Learn MIDI is greyed out as "locked by K#": the knob rewrites the value every frame, so a mapping would do nothing. Release the target first (uncheck it in the macro editor), or map a different value.

  6. Right-click again and select Cancel MIDI Learn if needed.

  7. Modulation Matrix Cells:

  8. Click any cell in the MIDI column of the Parameters matrix, then click Learn MIDI Modulator (or Re-Learn MIDI Modulator) in Modulation. This adds a MIDI modulator that is saved in the preset and adds on top of the parameter's value; Clear MIDI Modulator removes it.

  9. Global Performance Actions:

  10. In Preferences → MIDI Controls, click Learn next to Queue Advance A/B Next, Queue Step Back A/B Prev, BG Shader Advance, BG Step Back, or Tap Tempo.

  11. Modulator Variable Paths:

  12. Modulator variables use unified path syntax: <parameterPath>:mod/<modulatorId>/<propertyName>. Learn writes the modulator's stable id, so the mapping keeps following that modulator when others are added, removed or reordered. Older numeric paths such as Deck A/geometry/zoom:mod/0/subdivision (LFO 1 Speed), :mod/0/depth or :mod/1/morph still work and resolve by list position. Modulator mappings resolve dynamically each frame and display user-friendly labels (e.g. Deck A/geometry/zoom [LFO 1 Speed]) in the MIDI Preferences mapping table.

Intelligent Signal Classification

When you turn a knob or tap a pad during Learn mode, Liquid LSD inspects the incoming stream and classifies it automatically: - Note On / Off: Identified as a discrete button (pads/keys), defaulting to Momentary mode. - Continuous CC: Identified as an absolute continuous pot or slider ($0 \dots 127$). - Relative Rotary Encoders: Endless rotaries sending delta step packets ($63/65$ or $1/127$) are auto-classified into relative decoding mode. - Pitch Bend: 14-bit bipolar inputs are mapped with center-spring return.

You can override any auto-detected mode at any time using the dropdowns in Preferences → MIDI Controls.

Fine-Tuning Continuous Controls

In the Parameter Mappings table of the MIDI tab: - Min / Max Bounds: Clamp physical travel to a specific sub-range of the parameter. - Invert: Flips the physical direction ($0 \leftrightarrow 127$). - Slew (Smoothing): Configurable smoothing filter ($0 \dots 250\,\text{ms}$) that eliminates 7-bit "zipper noise" or stepped visual jumps on sensitive shader uniforms. - Soft Takeover (Pickup): Toggle between Immediate jump and Soft Takeover. With Soft Takeover active, parameter values will not jump upon loading a new preset until your physical knob/fader crosses the stored software value. The UI indicates Awaiting Pickup along with physical knob telemetry until synced.

Discrete Controls (Buttons & Pads)

Hardware buttons and pads support four distinct trigger behaviors: - Momentary: Active only while held; snaps back to minimum/default on release (ideal for video strobes, momentary feedback bursts, and glitch triggers). - Toggle (Latched): Flips state on each press. - Step Increment: Each press increments the parameter value by a configurable step size. - Step Decrement: Each press decrements the parameter value by a configurable step size.

Relative Rotary Encoders

Liquid LSD supports the three industry-standard relative encoding formats used by hardware like the DJ TechTools MIDI Fighter Twister, Behringer X-Touch, and Arturia controllers: - Binary Offset (64-centric): $65 = +1, 63 = -1$. - Signed Bit (1-centric): $1 = +1, 65 = -1$. - Two's Complement (1-centric): $1 = +1, 127 = -1$. Each rotary mapping includes an editable Step multiplier to dial in coarse or fine rotational sensitivity.

Profiles

All assignments are stored in JSON profiles under library/midi/<profile_name>.json. You can create, save, switch, and delete mapping profiles in the MIDI tab, allowing you to quickly switch between different hardware setups (e.g. home studio controller vs live gig setup).

Controller Profiles: Midi Fighter Twister

Some controllers are recognised automatically. When a device whose name contains Twister connects, the app loads the built-in Midi Fighter Twister profile and its 16 encoders drive the Performance Matrix with no learning at all. (The log line Controller profile 'midi-fighter-twister' matches MIDI device: ... confirms the match.)

This section is in the order you will need it: one-time setup, what the knobs control, gestures, a first walkthrough, the side buttons, lights, troubleshooting, the optional XT firmware mode, and your own profiles.

One-time setup in the Midi Fighter Utility

Do this once, in DJ TechTools' Midi Fighter Utility. The app ships a ready-made settings file for it, midi-fighter-twister.mfs:

  1. In Preferences → MIDI Controls → Controller Profiles, press Save Utility Settings... on the Midi Fighter Twister profile and pick a folder (the app remembers it for next time). Open Folder then shows the saved file.
  2. In the Utility, load that file, then send the settings to the Twister.
  3. That is all. The file sets every encoder on all four banks to Relative (ENC 3FH/41H) (binary offset: clockwise sends 65, counter-clockwise 63; relative mode has no end stops, so a knob never gets stuck at 0 or 127), every knob switch and all six side buttons to CC Hold, and every LED black in both its on and off state, so a knob the app is not using stays dark instead of showing the factory blue.

Then start Liquid LSD with the Twister plugged in and check Preferences → MIDI Controls → Controller Profiles: the Twister profile should be listed with your device. The log reports Controller feedback on for ... when the output port is opened; if it says No MIDI output port found, the app can read the Twister but cannot light it. While the app runs it overrides the ring and LED colours set in the Utility.

The app owns the banks. The top and middle side buttons on the right are plain CC Hold buttons, not the firmware's Previous/Next Bank. Right-top steps to the next bank (wrapping), Shift + right-top goes back; the app shows the bank's page and sends the bank change to the Twister, so the screen and the hardware agree. Right-middle opens the Library (Shift + right-middle opens it on the FX tab). Left-middle toggles Chain Link on the FX chain of the row you touched last (Shift + left-middle taps tempo). Don't set the side buttons to Previous/Next Bank in the Utility: the side buttons send six CC numbers per bank and would misfire.

If you set the Twister up by hand instead, use those same settings in the Utility.

To use the factory absolute mode instead, copy the profile to library/controllers/ and set "mode": "ABSOLUTE" on the knob input (the app then tracks each change, and a knob can hit the end of its 0-127 range).

What the knobs control

The 16 knobs are the 16 knobs on screen. Knobs 1-4 are the first visible row, 5-8 the second, and so on, so the Twister's 4×4 grid mirrors the matrix. Whatever a row is showing is what its encoders control: a deck's source knobs, its FX chain's Super Knob and Metaknobs, or the focused effect's parameters. Focus an FX slot, with the mouse or the Twister, and the same encoders follow. In Edit the Twister follows the open module: knobs 1-4 control that module's 4 macro knobs (reflecting its active sub-tab, e.g. SRC or FX), while knobs 5-16 are inert. Edit itself (the full 3-column parameter matrix) is opened and edited with the mouse; the controller only opens the pair view's pickers.

The Twister's hardware banks pick the page shown on screen (three pages: A/B, BG/PV, MIXER; the fourth bank leaves the page as it is). Press right-top (Shift + right-top goes back) and the matrix changes with it; clicking a tab on screen moves the encoders to that page too, so screen and hardware always agree.

Bank Page Knobs 1-4 Knobs 5-8 Knobs 9-12 Knobs 13-16
1 A/B Deck A source Deck A FX Deck B source Deck B FX
2 BG/PV Deck BG source Deck BG FX Deck PV source Deck PV FX
3 MIXER Master MIX Master FX Transitions Clock (knob 13)

Each row shows one half (source or FX), so no SRC/FX switching is needed on the hardware. Which page each bank shows is the profile's banks.pages; you can point a bank at your own page (see Perform Pages).

An FX row has the chain's Super Knob on its first knob and the three slots' Metaknobs on the other three. Focusing a slot (shift + tap) hands the whole row to that effect: knob 1 becomes the slot's Metaknob and knobs 2-4 its parameters (more than three parameters make extra pages).

Gestures

Gesture On a source / mix knob On an FX slot knob On a focused parameter
Turn moves the knob moves the slot's Metaknob moves the parameter
Tap the switch reset to centre bypass or un-bypass that slot reset to the parameter's default
Hold the switch and turn fine adjustment (10× slower) same same
Shift + tap - focus that slot next parameter page
Shift + tap on knob 1 of a focused row - leave focus -
Shift + tap on knob 1 (Super Knob) of an FX row - Chain Link: link or unlink all three slots -
  • Shift is the bottom button on the Twister's left side (the same physical button on every bank).
  • Fast turns accelerate up to 4×; slow turns stay exact.
  • Your own mappings win. If you have learned a mapping on a specific Twister channel/CC, that mapping still runs and the profile ignores that input.

Walkthrough: load an effect onto Deck A with only the Twister

  1. Go to bank 1 (A/B). Deck A's FX row is knobs 5-8 (the second row of the grid): knob 5 is the chain's Super Knob, knobs 6-8 are slots 1-3.
  2. Touch the slot you want. Give knob 6 (slot 1) a small turn. The picker opens for the last knob you touched, so this step chooses the target. Don't tap it: a tap bypasses the slot.
  3. Press the right-bottom side button. The picker for that slot opens on screen (stock filters, favourites and saved effects).
  4. Browse. Turn knob 16 (the last knob of the grid, bottom right) to move the highlight. Nothing is applied while you move. Press right-top to step to the next category (hold Shift for the previous one).
  5. Tap knob 16 to apply the highlighted effect to the slot. The item currently loaded is marked in the list (stock items only).
  6. Close the picker with left-top. The effect is now in slot 1; turn knob 6 for its Metaknob and knob 5 for the Super Knob.
  7. Tune it. Hold Shift and tap knob 6 to focus the slot: its parameters spread over knobs 6-8 and knob 5 becomes the Metaknob. Shift + tap knob 5 leaves focus.

Variations:

  • Replace an effect: repeat steps 2-5 on the same slot. Clear a slot: with the picker open, Shift + right-bottom.
  • Load a saved chain into all three slots: touch knob 5 (the Super Knob) before step 3. The picker then lists your saved chains, and Shift + right-bottom clears the whole chain.
  • Change Deck A's source instead: touch any knob in the source row (knobs 1-4) and press right-bottom for the source list.
  • Switching decks or targets: The picker stays scoped to the deck and row that opened it. Because knobs 5-15 are inert while browsing and knobs 1-4 follow the row being filled, close the picker first with left-top, touch a knob on the other deck or row (switching Twister banks if needed), and press right-bottom to open its picker.
  • Master FX or a transition: use bank 3 and touch a knob in Master FX (knobs 5-8) or Transitions (knobs 9-12).
  • If nothing happens when you press right-bottom, you haven't touched a knob since the app started: turn one first.
  • Picking from the Library view instead is described below.

Side buttons

The side buttons change meaning with the view:

View Left-top Left-middle Right-top Right-middle Right-bottom Knob 16
Perform back (Esc); Shift + toggles Edit mode toggle Chain Link; Shift + tap tempo next bank / page (Shift + prev) open the Library; Shift + opens it on the FX tab open the picker; Shift + toggles Pair view normal knob
Pair view back to Perform toggle Chain Link; Shift + tap tempo next bank / page (Shift + prev) step the pane (Shift + back) nothing; Shift + clears the slot or chain cursor: turn to move; tap applies
Library leave Library toggle Chain Link; Shift + tap tempo next bank / page (Shift + prev) step the tab (Shift + prev) step pane (Shift + prev) cursor: turn to move, tap to load
  • Send-knob rings: a send knob that can receive the highlighted item shows a full ring at half brightness in the target's colour; the others stay dark. Set the encoders' indicator to Bar in the Midi Fighter Utility to get a full ring (a Dot ring shows a single LED).
  • Knob 16 ring: in the Pair view and the Library the ring shows the cursor's place in its list (empty at the first row, full at the last); it is full when the list has no cursor yet or one row.
  • Left-middle button: Toggles Chain Link on the FX chain of the row you touched last. Shift + left-middle taps the BPM tempo (clock.tap_tempo).
  • Right-top button: Steps through hardware banks / Perform pages (Shift + right-top steps backward).
  • Unsaved-changes prompt: when loading would discard edits on a deck, the prompt takes over the controller: left-top = Cancel, right-middle or knob 16 tap = Save, right-bottom or Shift + tap = Discard. Nothing else navigates until you answer.
  • Picker: moving never applies anything; only a tap does. Touch a knob of the row first; with none touched yet the button does nothing. Knob 16 is the cursor. Knobs 9-15 do nothing (apart from the sends) while a picker is active (in the Library and picker, knobs 9-13 send the highlighted item, see below); knobs 1-8 keep controlling the two rows of the pair view (they light in their rows' colours), so you can tweak a freshly loaded source or chain without leaving it. Touching a knob of the other row points the browser at that half. To pick for another deck, send the item there with knobs 9-12 or go back with left-top first.
  • Edit: Left-top closes Edit (collapsing the module bay back to the Faceplate, same as Esc); Shift + left-top toggles Edit mode for the touched row. Right-bottom opens the pair view for the last-touched knob's row.
  • Banks in the pair view: pressing a bank button walks the pairs instead of changing the page: a higher bank is the next pair (Deck A, B, BG, PV, Master, Transitions/Clock, wrapping), a lower bank the previous one, so you can reach any deck's pair from the Twister alone.
  • Quick switch: in the pair view, Shift + tap on knob 9-12 (A, B, BG, PV) or 13 (Master) goes to that pair without sending anything.
  • Send knobs (Library and picker): tap a knob in row three to send the highlighted item to a deck: knob 9 = Deck A, knob 10 = Deck B, knob 11 = Deck BG, knob 12 = Deck PV; in the FX tab knob 13 = Master FX. A source or preset replaces the deck's content (with the usual unsaved-changes prompt), an FX chain replaces all three slots, and a single FX goes into the first empty slot (the last slot if all are full). From the Library the send only loads (you stay in the Library with your place kept, so you can send the next item straight away, and an FX send shows a toast with where it landed); Ctrl+Z undoes it. From the pair view the target's pair also takes over the screen, so knobs 1-8 play what you just loaded while knob 16 keeps browsing; send again to move to another deck. A knob glows in its target's colour while the highlighted item can go there. They work on the Sources and FX lists only. Back returns to Perform.
  • Library: a preset or generator loads onto the deck the crossfader is moving away from, a BG queue item onto Deck BG, a transition onto the mixer. In the FX tab, a tap applies the item to the live deck (a single effect goes into the first empty slot, the last slot if all are full; a chain replaces the deck's chain) and Shift + tap adds it to the FX queue. Holding Shift, the side buttons add to the BG queue and step the tab and list backwards.
  • Unified browser: a fresh tab starts in the list. Right-bottom moves on to the queues and Shift + it goes back to the folder tree. In the tree, turning moves a cursor (an outline) over the visible folders and playlists without changing the list; a tap selects the folder or playlist under it, which fills the list and clears the list's selection. A playlist is just a tree entry, so there is no separate playlist pane.
  • The FX queue transport commands (fx.queue_next/prev, fx.bg_queue_next/prev) have no free button in the built-in profile; map them in your own profile.

Rings and LEDs

The Twister mirrors the screen. Each encoder's ring shows its knob's value, and its LED takes the colour of the row it controls. A knob with nothing to control goes dark: an empty or bypassed FX slot, or a blank position on a focused effect's parameter page (its ring still shows the value).

  • LEDs can't show greys, so on the MIXER page the Master row is red (the screen keeps its greys) and Transitions stay cyan.
  • The clock knob (knob 13, the first knob of the Clock row on the MIXER page) is the beat light: its LED sits dim plum and flashes light plum on every beat and orange on beat 1 of the bar, and its ring shows the tempo across the beat tracker's BPM search range (Preferences → Tempo & Sync). Push it to tap tempo (the same as the TAP button); turning it does nothing. On the stock firmware the ring brightness pulses instead of the colour. While a Library or picker is browsing, the knob does its browse job instead.
  • On pages with a pinned FX row (A/B, BG/PV, MIXER) the FX row's LED is a shifted hue of its source row's, so the four LEDs of a bank differ.

Troubleshooting

  • Nothing responds: check Enable MIDI Subsystem in Preferences → MIDI Controls, and that the log shows the matches MIDI device line. Watch the Live MIDI Monitor to confirm the Twister's messages arrive.
  • Knobs jump to the ends or stick: the encoders are not in Relative (ENC 3FH/41H) mode on every bank (see setup).
  • Wrong page, or rings and LEDs from the wrong bank, or a side button doing the wrong thing: the middle side buttons must be CC Hold (save and load the settings file, see setup); on the factory Previous/Next Bank setting the side buttons send different CC numbers.
  • Unused knobs glow blue: the LEDs' off colour in the Utility is not black. Save and load the settings file (see setup), or set every knob's on and off colours to black on all four banks.
  • No lights at all: the log says No MIDI output port found. Reconnect the device, or close other software holding the Twister's port.
  • Rings lag or drop: the app writes lights to the showing bank a few messages at a time (the Twister drops bursts), rewrites the whole bank just after you switch to it, and re-sends it shortly after you stop turning, because the Twister redraws its own stored colours after bank changes. If rings still lag, raise output.minIntervalMs (default 2) in a copy of the profile.
  • See exactly what is sent: set "trace": true in the profile's output section (or start the app with LSD_MIDI_TRACE=1). Every message sent to the device, every bank change and every encoder message is then logged.
  • A Twister knob drives something else, or the browse cursor won't move: a learned mapping on that knob's channel/CC wins over the controller profile in the Perform view (while browsing, the profile wins). Clear the learned binding in the Learned Mappings list.
  • The Twister profile isn't in the Learned Mappings bar: that bar holds your learned mappings. The controller profile is chosen automatically from the device name and is listed under Controller Profiles in MIDI Controls.

Optional: XT firmware and native mode

If you have flashed your Twister with the custom XT firmware (the nativeMode build from the Midi Fighter Twister Open Source project; flashing is done with DJ TechTools' tools and is entirely your choice), Liquid LSD can drive it in native mode:

  • Each ring follows its parameter: a bar, a bar with a centre detent for -100..100 parameters, and a dot for endless and stepped parameters. The style changes live as you change pages, effects and sources.
  • The switch LEDs show the exact row colour.
  • There are no hardware banks. Right-top steps through the Perform pages (Shift + right-top goes back); the other side buttons work as before. No Utility settings file is needed.
  • The Library and Pair view send knobs (9-13) leave the ring off and show the target in the switch LED colour, because native mode has no half-brightness.

To use it: open Preferences → MIDI Controls → Controller Profiles, and in Use profile under the Twister choose Midi Fighter Twister (XT firmware, native mode). Choose the stock profile again to go back. Both profiles fit the same device name, so the app never switches by itself, and a Twister on the stock firmware must keep using the stock profile.

When the app quits, unplugs the Twister or you change the profile, the app turns the switch LEDs black and returns the device to normal. If the app crashes the Twister stays in native mode until you unplug and replug it.

Your own profiles

Profiles are JSON files: built-ins ship inside the app, and yours go in library/controllers/*.json. A file with the same id as a built-in replaces it, so copy a built-in's JSON and edit it. A file with a mistake is skipped; the reason is logged and shown in the Controller Profiles section of Preferences > MIDI Controls. That section lists each profile and the device using it, and has Copy to User File (for built-ins), Delete User File (reverts to the built-in) and Reload Profiles (after you edit a file by hand).

Each user profile also has a Mappings list:

  • Click a command to choose another (the list is filterable and dimmed where the command can't be driven by that input).
  • Use the trash button to remove a mapping, or add one with the row at the bottom (modifier, input, command). Invalid edits are not saved; the problems are listed.
  • To map by touch, choose a command and a modifier in the add row, press Learn and move the control on the device. A control the profile doesn't know becomes a new input. Modifier and bank buttons can't be learned.
  • Only global mappings can be edited there; per-bank mappings are still edited in the JSON.

See docs/developer/unified_control_mapping.md for the format.

OSC / TouchOSC Control Surfaces

Liquid LSD includes a native, zero-dependency OSC 1.0 server for wireless control from TouchOSC and other OSC-capable apps on phones and tablets — no external bridge software required.

Quick Setup

  1. Open Preferences → OSC Controls (or press Ctrl+,).
  2. Check Enable OSC Server. By default it listens on UDP port 8000 and sends feedback out on port 9000 — both are editable, with a Restart Server button to apply port changes.
  3. Point your TouchOSC layout at your computer's IP address, using the same inbound/outbound ports. Move any control on the layout — Liquid LSD automatically learns the client's IP from the first packet it receives, so there's nothing to configure on the desktop side beyond the ports.
  4. The Live Packet Sniffer in the OSC Controls tab streams recent inbound and outbound traffic (address, arguments, and remote host) so you can confirm packets are arriving.

OSC Learn & Modulator Variables

You can map OSC controls either in-situ from the UI or manually from Preferences:

  1. In-Situ Right-Click Learn (Fastest):
  2. Right-click any slider or variable label in the UI — including an LFO's Speed / Subdivision, Depth, Min/Max bounds, Asymmetry, a parameter's Initial Range (Base Value), the crossfader, fade speed, or a deck/transition queue's </> buttons.
  3. Select Learn OSC (...) from the context menu. The control will pulse in amber while awaiting input.
  4. Move a fader, knob, or XY pad on your TouchOSC surface. Liquid LSD ignores the first packet from a new address (guarding against a controller's connect-time sync burst) and maps once a later packet actually moves the value, preserving your configured min/max limits and saving the mapping to the active profile.
  5. As with MIDI, Learn OSC is greyed out as "locked by K#" while an enabled macro knob target drives that value.

  6. Right-click again and select Cancel OSC Learn (or cancel from Preferences) if needed. Once mapped, the same context menu offers Clear OSC Mapping to remove it without leaving the performance view.

  7. Manual Learn from Preferences:

  8. Open Preferences → OSC Controls.
  9. Type or paste the target parameter or modulator path into the Learn OSC field:
    • Base parameters: Mixer/crossfade, Deck A/geometry/zoom, Master/FX1/speed.
    • Modulator variables: Deck A/geometry/zoom:mod/<modulatorId>/subdivision (a numeric :mod/0/... is a legacy list position and still works).

  10. Click Start Learn, then move the control on your OSC surface.

  11. TouchOSC XY Pads & Multi-Argument Vectors:

  12. Multi-argument messages (e.g. /2/xy) are automatically unpacked into per-axis sub-addresses (/2/xy/0 for X, /2/xy/1 for Y). Learning from an XY pad maps the active axis.

Fine-Tuning & Shaping

The Address Mappings table in the OSC Controls tab offers comprehensive per-control shaping: - Min / Max Clamping: Scales the incoming controller range $[0.0, 1.0]$ to custom parameter boundaries (e.g., $0.1\,\text{s} \dots 8.0\,\text{s}$ for an LFO period). - Invert: Inverts incoming values ($1.0 - x$). - Slew Rate Smoothing: Exponential filter ($0 \dots 250\,\text{ms}$) to smooth out coarse touch faders or packet jitter without visual stepping. - Soft Takeover (Pickup): Prevents value jumping by waiting until the physical controller crosses the current software value before taking over control.

Macro Knobs also respond directly to /macro/<bankId>/knob/1–/macro/<bankId>/knob/8 (no manual mapping needed), and broadcast their values back out over OSC whenever they change — keeping tablet layouts in bidirectional sync. See Macro Controls & the Perform View.

Profiles

Like MIDI, OSC address mappings are stored in JSON profiles under library/osc/<profile_name>.json. Create, save, switch, and delete profiles from the OSC Controls tab to switch between different tablet layouts or venues.

Perform Pages

You manage pages in Preferences > MIDI Controls > Perform Pages (it is there even with MIDI turned off).

The tab strip above the matrix (A/B, BG/PV, MIXER) lists pages: each is four rows. Clicking a tab closes Edit and the Pair view and shows that page's rows, including when you click the tab you are already on. You can add your own by putting a JSON file in library/perform_pages/ (press Reload Pages in Preferences > MIDI Controls, or restart the app, to pick it up):

{
  "id": "mine",
  "name": "MINE",
  "tooltip": "Deck A source, Deck A FX, Transitions and Clock & Global",
  "rows": [
    { "row": "deck.A.src" }, { "row": "deck.A.fx" }, { "row": "trans" }, { "row": "global" }
  ]
}

A page needs exactly 4 rows. Row names: deck.A.src and deck.A.fx (likewise B, BG, PV) for a deck's source row and FX row, master.mix and master.fx for Master's levels and Master FX, trans, global. A page of deck.A.src, deck.A.fx, deck.B.src, deck.B.fx shows both halves of both decks at once. A file whose id is ab, bgpv, mixer or master replaces that built-in page. Pages saved by an earlier version that name deck.<tag>.srcfx or master are skipped (the log says why): replace those rows with the split ones above. You can also manage pages in Preferences > MIDI Controls > Perform Pages: copy a built-in page to edit it, create a new page, rename it and pick each of its four rows from a list, or delete it again. Edits are saved at once. Each page shows its controller name (perform.<id>), the name a controller profile uses; it does not change when you rename the page. To get a different name, type one into Name for a copy and press Copy As New Page, then hide the original if you like. Untick Show in tab strip to hide a page's tab (a Twister bank that selects it still shows it, with a temporary tab while it is active); with more than five tabs they narrow to fit. Files with mistakes are skipped; the log says why. A controller profile can select your page with perform.mine.