# Xoradora keyboard shortcuts

This reference covers Xoradora's own desktop-editor shortcuts and the keyboard
controls in the browser-based Phone Link sequencer. It does not list ordinary
JUCE/host conventions for every focused button, menu, slider, or text field.

Shortcuts work when the relevant Xoradora surface has keyboard focus. A plug-in
host may reserve keys before they reach Xoradora. The desktop Standalone claims
focus when its window opens; hosted plug-ins may need one click first.
Letter shortcuts are case-insensitive. Unless a modifier is shown, use them
without Command, Control, or Alt/Option.

## Navigation map

```mermaid
flowchart LR
    pads["Pads"]
    seq["Sequencer"]
    trig["Triggering"]
    detail["Pad Detail"]
    guided["Guided"]
    evolution["Evolution"]

    pads -->|P| seq
    seq -->|"P / Esc / Return"| pads
    pads -->|T| trig
    trig -->|"T / Esc / Return"| pads
    pads -->|"E / Return / Page Down"| detail
    trig -->|E| detail
    detail -->|"E / Return / Esc / Page Up"| pads
    detail -->|"H / Tab"| guided
    guided -->|"H / Tab / Esc"| detail
    detail -->|"M / V"| evolution
    guided -->|V| evolution
    evolution -->|Esc| detail
```

Pad Detail returns to the screen that opened it. The diagram shows its usual
Pads parent; when Detail is opened from Triggering, `E`, `Return`, or the final
`Escape` returns to Triggering instead. In Guided view, the first `Escape`
closes Guided and leaves Detail open. `Tab` also toggles between the two detail
surfaces; on the top-level screens it keeps its separate screen-cycling
behavior. Returning through the Pads grid and entering Detail again keeps the
last Compact or Guided surface choice.

## Common shortcuts

| Key | Action | Availability |
| --- | --- | --- |
| `Space` | Play or stop the sequencer | Wherever the desktop sequencer is available, unless an overlay or focused control consumes it |
| `Command-Z` | Undo the last Xoradora edit | Desktop editor; a host may intercept it |
| `Command-Shift-Z` | Redo the last Xoradora edit | Desktop editor; a host may intercept it |

On non-macOS platforms, JUCE maps the platform's primary command modifier to
the equivalent command shortcut.

## Pads screen

```text
                       P  Sequencer      T  Triggering
                       K  Keyboard Play  W  Display mode

                              Up
                               ↑
                  previous  ← pad →  next
                               ↓
                              Down

                  A  Audition   M  Mute   S  Solo
                  E / Return  Open selected pad Detail
```

| Key | Action |
| --- | --- |
| Arrow keys | Move the selected pad around the 4x4 grid without vertical wrap; Up at the top row stops, while Down from the bottom row opens Detail for the top-row pad in the same column |
| `Return` or `E` | Open the selected pad's Detail screen |
| `Page Down` | Open the selected pad's Detail screen; this is directional and does not wrap |
| `A` | Audition the selected pad |
| `M` | Toggle mute for the selected pad |
| `S` | Toggle solo for the selected pad |
| `P` | Open Sequencer |
| `T` | Open Triggering |
| `K` | Toggle Keyboard Play in the desktop Standalone |
| `W` | Cycle waveform, spectrogram, and cochleagram display |
| `Space` | Play or stop the sequencer |

### Keyboard Play

Keyboard Play maps the physical four-by-four key positions to the pad grid:

```text
Pad 01  Pad 02  Pad 03  Pad 04       1  2  3  4
Pad 05  Pad 06  Pad 07  Pad 08       Q  W  E  R
Pad 09  Pad 10  Pad 11  Pad 12       A  S  D  F
Pad 13  Pad 14  Pad 15  Pad 16       Z  X  C  V
```

The physical positions are fixed, but the labels shown on pads follow the
current keyboard layout. For example, the physical `Z` position may display
`Y` on a Swiss-German layout.

While Keyboard Play is active, its mapped performance keys take priority over
the ordinary `A`, `S`, `E`, and `W` commands. `P`, `T`, `K`, arrow navigation,
`M`, and `Space` keep their normal meanings. Key repeat does not retrigger a
held pad.

## Sequencer screen

```text
                   Up / Down       choose pad row
                   Left / Right    choose step
                   H               toggle hit

         Space  Play/Stop    R  Restart    C  Clear pattern
         P / Esc / Return    return to Pads
```

| Key | Action |
| --- | --- |
| `Left` / `Right` | Move the cursor through steps; continue across banks and wrap across the active pattern length |
| `Up` / `Down` | Move the cursor through pad rows, wrapping top-to-bottom |
| `H` | Toggle the hit at the cursor when that pad has a sound |
| `Space` | Play or stop the pattern |
| `R` | Restart transport from step 1 |
| `C` | Clear the entire pattern, undoably |
| `P`, `Escape`, or `Return` | Return to Pads |
| `Command-Z` / `Command-Shift-Z` | Undo / redo sequencer edits |

Arrow-key navigation turns Follow off so the playhead cannot switch banks away
from the keyboard cursor.

## Triggering screen

```text
                             Up
                              ↑
             previous pad  ← pad →  next pad
                              ↓
                             Down

              E  Edit pad       A  Audition
              M  Mute           S  Solo
              W  Display mode   Space  Play/Stop
              T / Esc / Return  return to Pads
```

| Key | Action |
| --- | --- |
| Arrow keys | Select a pad in the 4x4 Triggering grid; selection stops at the edges |
| `E` | Open Detail for the selected pad |
| `A` | Audition the selected pad |
| `M` | Toggle mute for the selected pad |
| `S` | Toggle solo for the selected pad |
| `W` | Cycle waveform, spectrogram, and cochleagram thumbnails |
| `Space` | Play or stop the sequencer |
| `T`, `Escape`, or `Return` | Return to Pads |
| `Command-Z` / `Command-Shift-Z` | Undo / redo |

When Detail is opened with `E` here, closing Detail returns to Triggering.

## Pad Detail and Guided screens

```text
        Left / Right    previous / next loaded pad
        Up / Down       nearest loaded pad in another populated row

        A  Audition              O  Source / resynthesis A-B
        M  Evolve (Compact)      S  Solo
        M  Mute (Guided)
        K  Next mode             J  Previous mode
        H / Tab  Compact / Guided V  Open Evolution
        W  Display mode          Space  Play/Stop

        Page Up          return to Pads
        E / Return        return to parent screen
        Escape            close Guided first, then return to parent
```

| Key | Action |
| --- | --- |
| `Left` / `Right` | Move to the previous or next loaded pad, wrapping through pad numbers |
| `Up` / `Down` | Move to the closest-column loaded pad in the previous or next populated grid row without vertical wrap; Up from the top row returns to Main with the bottom-row pad in the same column selected, while Down at the bottom row stops |
| `A` | Audition the selected pad |
| `O` | Toggle source versus resynthesis audition |
| `M` | Open Evolution from Compact; toggle mute from Guided |
| `S` | Toggle solo for the selected pad |
| `K` | Rotate the mode knob clockwise to the next mode |
| `J` | Rotate the mode knob counter-clockwise to the previous mode |
| `H` or `Tab` | Toggle Compact and Guided surfaces |
| `V` | Open Evolution for the selected pad |
| `W` | Cycle waveform, spectrogram, and cochleagram display |
| `E` or `Return` | Return to the parent Pads or Triggering screen |
| `Page Up` | Return to Pads from Detail; it does not wrap or change the selected pad |
| `Escape` | Close Guided if open; otherwise return to the parent screen |
| `Space` | Play or stop the sequencer |
| `Command-Z` / `Command-Shift-Z` | Undo / redo |

## Evolution screen

The 16 candidates use two keyboard rows:

```text
Candidate 01  02  03  04  05  06  07  08      1  2  3  4  5  6  7  8
Candidate 09  10  11  12  13  14  15  16      Q  W  E  R  T  Y  U  I

Arrow keys  navigate      A  audition current      F  favourite
Shift + candidate key     audition and favourite   G  advance
Enter                     accept current candidate
Escape                    cancel Evolution
```

| Key | Action |
| --- | --- |
| `1`-`8` | Audition candidate 1-8 |
| `Q`-`I` | Audition candidate 9-16 |
| `Shift` + candidate key | Audition that candidate and toggle its favourite star |
| `Left` / `Right` | Move through all candidates, wrapping across row edges |
| `Up` / `Down` | Switch between candidate rows in the same column |
| `A` | Audition the current candidate |
| `F` | Toggle the current candidate's favourite star |
| `G` | Generate/advance the evolution session; during an automated search, finish it early |
| `Enter` | Accept the current candidate and end Evolution |
| `Escape` | Cancel Evolution and return to Detail |
| `Space` | Play or stop the sequencer when available; it is never a candidate key |
| `Command-Z` / `Command-Shift-Z` | Undo / redo |

The Standalone enables candidate keyboard control immediately. In a hosted
plug-in, click the Evolution gallery before using candidate keys.

## Phone Link pairing overlay

```text
Command-C        copy pairing link
Escape / Return  close the overlay
Tab              move focus normally
```

When Copy or Close has focus, `Return` or `Space` activates that button rather
than the overlay-level shortcut.

## Hybrid Kit window

Hybrid Kit has no Xoradora-specific letter-key commands. Use its visible
controls and the platform's normal focus navigation and button activation.

## Phone Link browser screens

The Phone Link Pads screen has no dedicated hardware-keyboard shortcuts. On
the Phone Link Sequencer screen, shortcuts work while a form control is not
focused:

```text
                 Up / Down       choose pad row
                 Left / Right    choose step and bank
                 H               toggle hit
```

| Key | Action |
| --- | --- |
| Arrow keys | Move the cursor through pad rows and steps; steps cross banks and wrap across the active pattern |
| `H` | Toggle the hit at the cursor |

Browser and operating-system shortcuts still take precedence.

## Shortcut priority

When keys overlap, the active screen owns them in this order:

1. Phone Link overlay controls.
2. Sequencer cursor and Sequencer screen commands.
3. Triggering screen commands.
4. Pads navigation shortcuts and transport.
5. Keyboard Play performance keys, when enabled.
6. Pad/Detail commands.
7. Evolution candidate commands, while Evolution has keyboard control.

Focused menus, text fields, sliders, and host-level commands may consume a key
before this list applies.

## Source of truth

The desktop handlers live in
`source/Source/Editor/PluginEditor.cpp`. Localized physical pad-key labels live
in `source/Source/XoradoraComputerKeyboard_mac.mm` and the platform fallback.
Phone Link browser keys live in
`source/Source/XoradoraRemotePadServer.cpp`.
