GroovixBox Manual

Tutorials

Three sittings that build one track between them, using nothing but the first page of tracks, steps and patterns. Everything about paging comes after.

• 1 Your first beatSteps, tracks, the tempo and where the loop ends.
• 2 A melody over the beatThe key, the keyboard, chords, velocity and gate.
• 3 Patterns, mutes and scenesVariations, silencing tracks, scenes and the song.

Controls

The pads change meaning with the mode. The buttons around them are fixed.

While a page gesture is held, the buttons it uses stop doing their usual job and show the pages instead. B1 won’t pick a track while SHIFT is held, for example — it goes to track page 1.

Page panel

The second surface, and not optional: a grid of pads that shows which page of each kind is open and switches to another — one row a kind, one pad a page — and carries the mode buttons, the transport, the roll arrows, the preset windows and SHIFT. It is an indicator and a switcher, never a second sequencer grid: it plays no notes and edits nothing. An Akai APC mini mk2 is this panel in hardware, which it becomes when a Launchpad X takes the grid and frees it; a Launchpad Mini mk3 can play it instead — see which device plays which role.

Everywhere else, page position is something you hold a modifier to see — SHIFT, or R2 in Preset mode. The panel shows every kind of page at once, all the time, which is the whole reason it exists.

Four rows for the steps, because eight pads could only ever have reached a quarter of them. That is why the panel went without a step row until there were four to give it: a row that landed you roughly near a page is not what this surface is for. The grid keeps its own map of the same 32 pages under SHIFT — the panel is for seeing where you are without holding anything, the grid’s map for when your hand is already on the pads. Where the rows are labelled — in the simulator, which draws the panel with a word beside each row — only the first of the four says STEP PAGES and the three below it continue it: a name on each would have to spell step ranges, and those go wrong on a build configured for fewer steps, where the later rows are simply dark.

Rows 7 and 8 are a pair. A window holds exactly eight preset pages, so window over pages reads like a row of tabs over what the open tab shows: pick a window on one row, a page of it on the next.

Each row lights the way the slot maps do: green for the page on screen, blue for a page holding something, grey for an empty one, dark for a page that doesn’t exist in this build. Tapping a pad goes to that page of that kind.

The panel’s buttons

• The transport is only here. Eight buttons beside the grid are exactly its eight functions, so REC and PLAY have no chip there to sit on — on hardware they are this panel’s, and nowhere else. In the simulator Space is Play and the drawn panel’s buttons click, so a desk with no panel on it still plays.
• The panel is where the modifier is, which is why the rig is always a grid and a panel rather than one device: a Launchpad X has no button to spare for SHIFT, and an APC that is not sequencing has one free.

The screen

A 1024×600 panel beside the instrument — on the built rig a Pi drives it directly, with no desktop behind it. It is a readout and nothing else: there is nothing on it to press. In the simulator, --display opens it as a second window (in a build configured with -DGX_BUILD_DISPLAY=ON); displayfont in the config names a font file when the usual places have none.

Three bands, and they never swap places:

• A mode is explained by its rows, not by a key. The screen draws the grid in the same 64 colours the pads are showing, then merges each block of rows into one block and writes what it does inside it — so the band sits on the rows it is about and never has to print a row number. A row whose pads do several unrelated jobs gets a band per job, across its own pads.
• A pad that names itself keeps its name. Where a row is a set of named pads — the settings, a drum kit’s BD and SD, the pattern bank’s FOUR FLOOR — the screen writes those names on the pads instead of a sentence listing them, and they are the same labels the simulator prints, from one place, so the two surfaces cannot name a pad differently.
• The header says where you are, to the step: the mode, the button that opens it, and TRACK 3 · PAT 2 · STEPS 193-224 — which is how the step page is read exactly, without holding anything.
• Below the bands come the gestures worth naming — hold NOTE + B1-B8 step page, SHIFT + NOTE scenes, REC on: a knob move is written in — and a line or two on why you would be in this mode at all. Every one of them names the function, never a row of the column: CLEAR + step, not R7 + step. A row number in a legend is a lie waiting for the next rearrangement, and the buttons have already moved once.

Which device plays which role

A control surface is bound to a job, not to a model, and which device takes which job falls out of what is plugged in. There are three roles, and the rig is always a grid and a panel.

• A Launchpad X and an APC mini together need no configuring. The Launchpad takes the grid, the APC falls through to the panel, and that is where SHIFT has to live.
• One device, one role. Whatever takes the grid is not also the panel.
• The two panels are not the same deal. An APC mini brings nine faders, and in the panel role they are the only faders the rig has; a Launchpad Mini mk3 has none. If you own both a Mini and an APC, put the APC on the grid — the Mini then takes the panel by itself and the faders keep working.
• To say so outright, name the role in controls.conf. A role you name beats one that is only choosing for itself, which is how you tell an APC to be the panel while something else sequences:

  surface.grid  = launchpadx      # or apcmini, or auto
  surface.panel = apcmini         # or launchpadmini
  surface.mixer = midimix

  Leave a line out, or say auto, and the rig picks whatever is plugged in. A device named here that is not plugged in leaves that role empty rather than quietly taking another: asking for one grid and silently getting a different one is worse than being told there is no grid. A typo costs you a warning, not your grid — the role goes back to choosing for itself.
• They come back by themselves. Unplug a surface and plug it in again and it is picked up without your touching anything; see the devices page.
• Plug a Launchpad X in by its MIDI port, not its DAW port — on that device every pad and button arrives on LPX MIDI, and the DAW port answers nothing.

MIDI CC from the faders and knobs

Every fader and knob can send a MIDI CC, on the channel and port of the track it belongs to: the strip’s track on the current track page, or the selected track for the two master faders.

• Moving a control sends it. The positions a surface reports when it starts are only recorded, so nothing is sent until you move something.
• A CC is sent only when its value changes, so a slow move sends at most 128 messages over the whole travel.
• Defaults: the mixer’s faders send Volume (CC 7), its knob rows Cutoff (74), Resonance (71) and Pan (10, centred), and the faders under the pads send Expression (CC 11). The two master faders send nothing.
• The tempo is set with pads, not a fader — +10 and −10 beside +1 and −1 on the bottom row of Global settings — so every fader sends its CC in every mode.
• With REC on and the transport running, a move is also written into the pattern and played back on every pass: see automation. The controller it records is the one the control is assigned here, so the config file decides what a knob automates as much as what it sends.

The config file

Assignments are read from a text file, controls.conf. Without one the defaults above apply. The same file also says which MIDI device the ports go out of, which surface plays which role, which keyboard to listen to (midiin), and, per port, whether it is sent the transport and the clock (p3.transport = off, p3.clock = off — for a groovebox that would start its own sequence on a Start) or sent to a UDP server instead of a cable (p8.socket = 192.168.1.50:5000). A rig is described in one place.

Where it is read from. The config directory, /mnt/usb1/config unless you say otherwise — the USB stick in a built rig. Projects go beside it in /mnt/usb1/data. The two are separate so a rig's settings can sit in /etc, beside your dotfiles or on read-only media while projects churn somewhere writable.

Naming a place and finding nothing there is reported as an error, since you asked for it; a rig that names no place and has no file has simply never made one.

midiout     = MIDI4x4     # which interface P1..P8 go out of
p3          = Digitone MIDI 1   # or give one port a device of its own
mixfaderrow = 7           # all eight mixer faders: Volume
knobrow3    = 10, center  # the third knob row: Pan, centred
knob3.1     = 91          # just strip 1's third knob: reverb send
fader2      = 11          # a fader under the pads: Expression
master      = off         # sends nothing

Where the ports go. With nothing said, the first MIDI interface found is wired up in order, which is right for most rigs. midiout names the interface when there is more than one. p1–p8 go further and give a port a device port of its own — the way to put a USB synth on a port by itself. Write the name a port listing prints, copied as it stands:

Everything matches on part of the name and ignores case, so digitone finds “Elektron Digitone”. The first form is the one to reach for: it is a line off the screen, and it needs no counting. The two with a colon are for when a port's own name isn't enough — a cheap interface that calls its sockets MIDI 1 and MIDI 2 with no maker's name in them, where Digitone:MIDI 1 says which device's MIDI 1 you meant.

Once any p line is there, those ports are wired to exactly what they name and the rest are left alone for aconnect — the devices page shows which found something.

Finding the names

aconnect -o lists everything you can send MIDI to. The quoted name after client is what midiout and the p lines match, and the indented lines under it are that device's inputs:

$ aconnect -o
client 14: 'Midi Through' [type=kernel]
    0 'Midi Through Port-0'
client 32: 'MIDI Mix' [type=kernel,card=4]
    0 'MIDI Mix MIDI 1 '
client 36: 'APC mini mk2' [type=kernel,card=5]
    0 'APC mini mk2 Control'
    1 'APC mini mk2 Notes'
client 38: 'Launchpad X' [type=kernel,card=6]
    0 'Launchpad X LPX DAW'
    1 'Launchpad X LPX MIDI'       <- the one the pads speak on
client 40: 'MIDI4x4' [type=kernel,card=7]      <- the name to match
    0 'MIDI4x4 Midi Out 1'                     <- its 1st input
    1 'MIDI4x4 Midi Out 2'                     <- its 2nd
    2 'MIDI4x4 Midi Out 3'
    3 'MIDI4x4 Midi Out 4'

Copy the quoted name. Everything between the quotes is what to write, and nothing else on the line matters:

aconnect -l shows the same list with what is wired to what, including the sequencer's own GroovixBox ports while it is running — the way to check a patch from outside the instrument. amidi -l lists the hardware instead, by card, which is useful when a device is plugged in but no ALSA client appeared for it.

The value is a CC number 0–127, or off. After it, full (the default) sweeps 0–127 across the travel and center holds CC 64 in a small detent in the middle, for pan-like controls. # or ; starts a comment. A bad line is reported with its line number, and the lines before it still apply.

Voice lists

A preset pad sends a voice, not a number. Which voice is a row of that device’s own list, read at startup from a CSV — the maker publishes one in its Data List.

Two files, in the config directory. voices.conf says which list belongs to which device:

sx920.device = PSR-SX920            # part of the name, matched as midiout and p1-p8 are
sx920.file   = voices/psr-sx-920.csv

Both are values, so a device name can carry spaces, slashes and punctuation without having to survive being a filename or a config key. The id on the left is yours and only pairs the two lines.

The CSV is the maker’s file, pasted in whole. It needs a header row and nothing else: the reader finds MSB, LSB, PC and Name by name, in any order, among any other columns, so another maker’s layout needs no configuring.

MSB#,LSB#,PC#,Name,,,,Type
104,21,1,CFX ConcertGrand,,,,S.Art
104,10,1,CFX StageGrand,,,,S.Art

Those two rows are why this exists: same bank, same program, different LSB. A PSR-SX920’s 1,650 voices put seven grand pianos on one MSB and one PC, told apart by the LSB alone.

• Programs count from 1, the way every printed list prints them. A 0 in that column refuses the file rather than putting every voice in it one place out.
• A row that isn’t a voice is skipped — MSB, LSB and PC must all be numbers — which is how a heading or the copyright line at the foot of a list looks after itself. The count is reported.
• A bad list is refused whole, unlike controls.conf where a bad line can be stepped over. A voice list is positional: one dropped row shifts every slot after it and quietly changes what saved projects play.
• Paths stay inside the config directory. The file says which list to read, not where on the disk to read from.
• No list, no problem. A device nothing is said about gets a walk of bank and program: slot n is bank LSB n/128, program n%128, 4096 of them and none of them named. That assumes nothing about the gear — a synth with 300 patches answers the first 300 slots and ignores the rest, where a 128-voice General MIDI list would have put its whole bank 1 out of reach.
• A port that really is General MIDI says so, and then it is 128 named voices: p4.voices = gm (or generalmidi) in controls.conf. A pad or a preset window past the end of whatever list a port has is dark and deaf to a tap, so the grid shows how far the device reaches.

Which list a port plays from follows what is on that port, resolved as the ports are wired, so a REFRESH that moves a synth to another port takes its voices with it. Startup says what each one ended up with, and --midi-log names the voice as it goes out:

voices: P1 Yamaha PSR-SX920 - 1650 from voices/psr-sx-920.csv (2 rows skipped)
voices: P3 UM-ONE - no list: 4096 by bank and program, unnamed
voices: P4 TD-17 - 128 General MIDI, declared
MIDI P1 ch1  bank MSB (CC  0) 104
MIDI P1 ch1  bank LSB (CC 32)  21
MIDI P1 ch1  program   0  bank 104:21  preset 1.01  CFX ConcertGrand

LED colours

Slots and pages

Project, pattern and preset pads, and the page maps on the buttons, share one colour code.

• Selected / shown
• Has data
• Empty
• Off: doesn’t exist
• Built in: read-only

Amber is the one that behaves differently. It marks the built-in pattern bank — patterns 33–64 of tracks 1 to 5, the bottom half of Pattern mode’s grid: those patterns ship with the instrument, play as soon as you tap them, and cannot be edited or cleared. On tracks 6 to 64 the same rows are patterns of your own, and light blue like any other. DUPLICATE copies one up to rows 1–4 to make it yours.

While DUPLICATE is held, the picked source pad turns white. Red belongs to markers rather than to tracks: the pattern's last step in Note mode, the panel's REC button, and the playhead while recording. No track is red, so none of those can be mistaken for one.

Track colours

Tracks use eight colours, repeated on every track page: tracks 9–16 use the same colours as 1–8, and so on to 64.

• B1 peach
• B2 orange
• B3 yellow
• B4 green
• B5 cyan
• B6 blue
• B7 purple
• B8 pink

Modes

Each mode has its own page, with the buttons and pads it uses. The chip is the grid’s gesture, and all six of the modes it takes SHIFT or a second button to reach have a button of their own on the panel.

The four you work in carry the four you arrange with. R1–R4 are the modes that edit the selected track, and each holds one session mode on its Shift layer: notes carry the scenes, the step parameters carry the song, probability carries the projects, and patterns carry the settings. R5 and R6 — Preset and Scale — have bare buttons instead and no layer at all, and R7 and R8 are modifiers that SHIFT leaves alone. So a button either is a mode or hides exactly one, and nothing you reach for with a thumb on the modifier does two things.

• R1 NoteSteps and the scale keyboard, chords, keyboard octave.
• R6 ScaleRoot note and scale for the Note mode keyboard, and what the keyboard is.
• R2 Step parametersPer-step velocity and gate, 16 levels each.
• R5 PresetChoose the voice the selected track’s gear plays.
• R3 ProbabilityThe chance each step plays, 6% to 100%.
• SHIFT + R4 Global settingsThe tempo, and each track’s MIDI channel. SETTINGS on the panel.
• R4 PatternWhich pattern each track plays, the built-in bank and the library.
• SHIFT + R1 ScenesWhich tracks are silent in each section, on 32 pads.
• SHIFT + R3 ProjectOpen, save and page through project slots.
• SHIFT + R2 SongThe scenes in the order they play, four bars a step.

Clear, Duplicate, Record, Play

The first two are the grid’s last two buttons; the transport is the panel’s.

CLEAR R7

Hold it and tap pads. What gets cleared depends on the mode: a step in Note mode, a pattern in Pattern mode, a project in Project mode. Preset mode has nothing to clear — a preset is a number, not something the sequencer keeps — and neither has the built-in pattern bank, which is read-only.

DUPLICATE R8

1. Hold DUPLICATE.
2. Tap the source pad; it turns white.
3. Tap one or more destination pads. You can change page in between.
4. Release DUPLICATE.

Copying an empty slot onto a full one empties it.

REC

Turns recording on or off, whether or not the sequencer is playing. It only has an effect while playing, when pressing note pads in Note mode — or playing a MIDI keyboard, or moving a knob — writes into the selected track. While it is on the playhead runs red instead of white, so the grid itself shows that it is listening. See what recording looks like. Held in Scene mode it captures a scene onto the pad you tap.

PLAY

Starts playback from step 1, or stops it. Stopping releases every sounding note and resets the playhead. Pressed in Song mode it plays the arrangement, which SHIFT + R2 opens. Space is this button in the simulator.

Pages

The grid shows 8, 32 or 64 of something at a time; pages reach the rest. Patterns need none: a track has 64 and the grid is 64 pads, so Pattern mode shows the whole of a track’s choice at once and its bottom buttons are free to be the tracks, as they are everywhere else.

• Flipping the track page keeps your position. If track 4 is selected and you press SHIFT + B2, track 12 becomes selected.
• To see which page you’re on, hold the gesture’s modifier — SHIFT in Note, Step parameters and Probability turns the four rows of steps into the map of all 32 step pages, and SHIFT in Project or Preset mode (or a held R2 there) shows their page maps on the buttons. A page panel shows every kind at once, always.
• A Duplicate source stays picked when you change page, so you can copy between pages — and in Pattern mode when you change track, so you can copy a pattern to another track. In Note mode, flipping the track page drops it, because a step of the old track means nothing on the new one.

Simulator

The simulator draws the device in a window. Every button has a key, and the mouse presses pads and moves faders.

All keys, combinations and mouse actions are on the Keyboard shortcuts page, with the device button each key presses.

Status line

The line above the pads shows what the device has no display for:

PRJ 3.08 NOTE    TRK 12 PAT 10 PRE 1.01 104:21:0 CFX ConcertGrand PG 1/32 STEP 05/32 120 BPM C MAJOR OCT 2 PLAY REC

Open project, mode, selected track, the pattern it plays, its preset and the voice that names, the step page out of all 32, the playhead and the track’s length, tempo, the key, the keyboard’s octave, and the transport state.

MIDI

The sequencer's output is eight ALSA sequencer ports named P1–P8, one per MIDI port, under the client GroovixBox. Every port also carries MIDI clock, 24 per quarter note, with Start when playback begins and Stop when it ends, so external gear follows the tempo. They are wired up at startup: the sequencer looks for a MIDI interface and connects P1 to its first socket, P2 to the second, and so on, which puts a 4×4 interface on P1–P4. It only ever picks a real interface — never the kernel's loopback, never one of its own control surfaces, and it prefers the device with the most inputs, so a 4×4 wins over a keyboard that happens to be plugged in first — and it leaves the ports alone if something has already patched them, so a patch made by hand with aconnect or a patchbay survives. Global settings shows which ports found something, and its refresh pad looks again for anything plugged in since. To see the same thing from outside, aconnect -l lists every port and what it is wired to; finding the names has more. The control surfaces are picked up automatically, on their own client GroovixBox Surface, and the window answers them as well as the mouse — a press on the hardware and a click on the drawing are the same press.

The panel in the window

The simulator draws the page panel beside the grid, with its pad rows, its button column, its four arrows and its SHIFT, all clickable. That is where REC and PLAY are, since no button of the grid carries them; Space is Play as well.

Only one at a time

A second simulator refuses to start while one is already running: both would answer every press of the same surfaces, and both would write to the same projects.

How to…

Give steps different notes

1. In Note mode, hold a step pad.
2. Tap a note pad on the keyboard. Repeat with other steps.

In the simulator, right-click each key to latch it down, then left-click the step. Right-click the keys again to let go. The same trick works for any combination that needs more than one pad at once.

Work on tracks 9–16

1. In Note mode, hold SHIFT and press B2 (Shift + 2).
2. Release SHIFT. B1–B8 now select tracks 9–16.

Copy a pattern to another track

1. Press R4 for Pattern mode, then B1–B8 for the track the pattern is on.
2. Hold DUPLICATE and tap the source pattern.
3. Still holding it, press the B button of the other track and tap the destination pad.
4. Release DUPLICATE, then tap the destination to make that track play it.

Save the current project as a new copy

1. Hold SHIFT and press R3 — or press PROJECT on the panel. The open project is green.
2. Hold DUPLICATE, tap the green slot, then tap an empty slot. Press SHIFT + a B button in between to use another page.
3. Release DUPLICATE and tap the new slot to continue working in the copy.

Give each track its own MIDI channel

1. Hold SHIFT and press R4, then tap pad 2 of the top row.
2. Tap a channel on rows 3–4 for the selected track.
3. Press the next track’s B button — you stay in the mode — and tap its channel. Repeat along the row.
4. SHIFT + B1–B8 moves on to tracks 9–16 and beyond, as far as 57–64.

Choose a preset for track 5

1. Press B5, then R5 for Preset mode.
2. Tap a pad, or hold SHIFT (or R2) and press a B button to change page first.

Play a built-in pattern

1. Press B1 for track 1, then R4 for Pattern mode.
2. Tap any amber pad in rows 5–8: the track plays that drum pattern at once. Track 2 is bass, 3 chords, 4 arp, 5 fills.
3. To edit it, hold DUPLICATE, tap the amber pad, then tap a pad in rows 1–4 — the copy is yours.

Reference

Capacity

The Pi and the simulator use as much as the surfaces can reach: 8 pages of tracks on SHIFT + B1–B8, 32 pages of steps on SHIFT + the four rows the steps sit on — and on the panel’s own top four rows, all at once — and 64 patterns a track, a pad each, so they need no pages at all. The small build in the right-hand column is what the freestanding dependency checks compile; a project file carries its own capacity either way.

MIDI output

Default track notes

General MIDI drum notes, repeated from track 17 on.

Saving

• The open project is saved when you open another project and when the simulator quits.
• On start, the last open project opens again.
• Files in the data folder: project_NN.gxb, preset_NN.gxb and session.gxb (which project was open).
• A save can't corrupt what was there. Every write goes to a temporary file and is renamed over the old one only once it is complete, so a power cut during a save leaves the previous version intact.
• Clearing doesn't delete the file. CLEAR + a project or preset pad moves it into trash/<date>_<time>/ inside the data folder — trash/2026-09-22_23-32-31/project_07.gxb — so a mistaken Clear can be undone by copying the file back. Clears in the same second share a folder and never overwrite each other. Copying an empty slot over a full one empties it, and that is kept too. Nothing empties the trash, so it is worth a look now and again.

Current limitations

What the simulator build doesn’t do yet.

• Rolls and arpeggios are even. A ratchet repeats a step up to eight times at equal spacing, and the arpeggiator plays a chord at one rate; neither can accent, swing or vary within itself.
• Swing is one setting for the whole project, in Global settings, not per track or per pattern — though a track at another speed swings by the same share of its own longer or shorter step. Per-step micro-timing is what moves a single hit.
• Automation has no lane to look at. A knob move is recorded and played back, and the panel says how many controllers a pattern has, but there is nothing on the grid that draws the values or lets you draw them in by hand: a move is re-recorded, or taken off with CLEAR + the step.
• MIDI in is notes, the transport and the clock. A keyboard plays and records into the selected track, Start and Stop work, and the box can follow an outside clock. What still doesn't come in: CC, and any way to send what arrives to more than the selected track.
• No Song Position Pointer, in or out. Playback always starts at step 1, so Continue is treated as Start when following, and gear following us starts from its own beginning.
• A preset holds nothing of the sequencer’s own. It names a voice in the gear and sends Bank Select and Program Change for it, which is what external gear wants, but there is no patch to save until there is a sound engine with parameters to put in one.
• Chords are capped at 4 notes per step. It is one constant in the engine, but raising it grows every project file.
• The faders have no mixing function of their own. They send CC, which a synth may map to level; the sequencer itself has no volume.
• Part of the mixer has no function yet. The mute row mutes and solos tracks and the knobs and faders send MIDI CCs, but the A2 row and M1–M3 have nothing on them.
• CC is send-only. Nothing reads CC in; the last pad of Global settings sends every position out again.
• Mutes are not saved. They belong to the session, so opening another project clears them.
• No undo. Clear acts immediately, including on projects — though on a project or preset the file is moved to the trash folder rather than deleted, so it can be fetched back by hand. Clearing a step or a pattern is gone for good.
• On the grid, page position is only shown while holding SHIFT (or R2 in Preset mode). The page panel shows every kind at once and never needs a modifier — the step pages included, on its top four rows.
• Projects only partly move to smaller builds. A project with more tracks than the build opens with its first tracks (64 on the Pi and in the simulator, 16 in the small build the dependency checks use) and drops the rest when it next saves. A project with more patterns, steps or automation lanes than the build still won’t open — losing a pattern without a word would be worse.
• The project format was relaid out when automation and per-track speed arrived. There is one version and one layout, with nothing optional in it, so a project file saved before that is refused and its slot opens empty rather than half read.
• A built-in pattern does not set the track’s preset. The bank on patterns 33–64 of tracks 1–5 plays notes out of whatever channel, port and voice the track already has, so a drum pattern only sounds like drums once you have put a kit on that track yourself. Which voice each role should call up is device-specific, and waits on a preset document.