beatstep-pro-handler

Read and write every configuration parameter of the Arturia BeatStep Pro over USB SysEx — global settings and per-control (knob / pad / step) assignments — headless, from Python or the command line. No MIDI Control Center, no GUI.

bsp read 41 06            # read global param 0x41/0x06 (User Channel)
bsp write 41 06 9         # set it to channel 10 (0-based)
bsp globals               # dump every global setting, with names

from beatstep_handler import BeatStepPro, PARAM_GLOBAL
with BeatStepPro() as bsp:
    print(bsp.read(PARAM_GLOBAL, 0x06))       # -> current User Channel
    bsp.write(PARAM_GLOBAL, 0x06, 9, verify=True)

The protocol (the whole thing)

One uniform SysEx frame reads or writes any parameter:

WRITE:  F0 00 20 6B 7F 42 02 00 <paramId> <itemId> <value> F7
READ:   F0 00 20 6B 7F 42 01 00 <paramId> <itemId>         F7
  reply:F0 00 20 6B 7F 42 02 00 <paramId> <itemId> <value> F7   (+ ack 1C)

• 00 20 6B = Arturia, 7F 42 = BeatStep Pro, 02/01 = write/read.
• paramId 0x41 = the global bank; itemId = the global's id.
• paramId 0x01–0x08 = per-control fields (Mode / Channel / Data / Min / Max / Option / Acceleration / Ports); which field a shared id means depends on the control's Mode.
• Control itemIds: knobs 32–47, pads 112–127, steps 48–63.
• Channel specials: User 0x41, All 0x7E, Drum 0x42.
• LIST values are non-contiguous (a knob's Mode uses 0,1,4,12,13,14,15) — send the value the device expects, not an index.

See beatstep_handler/protocol.py — pure, dependency-free, and unit-tested byte for byte.

Install

From GitHub (works today, any OS):

pip install git+https://github.com/jamisonx-dev/beatstep-pro-handler.git

Runtime needs only python-rtmidi (installed automatically).

A PyPI release (pip install beatstep-pro-handler) is planned but not yet published — use the GitHub install above for now.

Platform: Windows, macOS, and Linux. MIDI goes through python-rtmidi, which runs on all three. Connect the BSP by USB — its configuration SysEx is ignored over DIN (real-time MIDI over DIN works fine, that's just not what this tool does).

How it talks to the device

• Send and capture via python-rtmidi on the BSP's USB config port. The device answers a read with the parameter's current live value.
• The device drops large request bursts, so reads are paced in small chunks with a bounded retry.
• All verified against real hardware, cross-checked byte-for-byte against a reference instrument, and covered by tests.

Running alongside another app that owns the BSP? (e.g. a host program that holds the sequencer port.) Pass BeatStepPro(backend="amidi") on Linux — it sends through ALSA rawmidi (amidi, from alsa-utils) while still capturing replies via rtmidi. Not needed for normal standalone use.

Friendly names (optional)

bsp globals and the library can show human-readable parameter names. A name table is bundled, so it works out of the box. The table is parameter numbers and value enums (interoperability facts) plus generic, industry-standard labels and a sensible grouping.

To refresh it from a newer firmware/MCC than the bundled one, regenerate it from your own Arturia MIDI Control Center install:

python tools/gen_tables.py "/path/to/your/BeatStepPro.json" -o beatstep_handler/data/beatstep_tables.json

This project does not redistribute Arturia's MIDI Control Center device dictionary, templates, or firmware. The generator reads the copy you already have from installing MCC.

Scope

• Globals (95 settable) and per-control assignments — full read/write.
• Project-scope sequencer scalars are reachable by the same frame.
• Per-sequencer / per-step pattern data is out of scope — the device addresses it per-pattern in a bulk frame this uniform frame can't carry, so writes to it don't take. This tool never pretends to set something it can't.

Tests

python -m pytest        # or: python tests/test_protocol.py

License

MIT — see LICENSE. "BeatStep Pro" and "Arturia" are trademarks of Arturia; this project is independent and not affiliated with or endorsed by them.