Metadata-Version: 2.4
Name: beatstep-pro-handler
Version: 0.1.0
Summary: Read and write every Arturia BeatStep Pro configuration parameter over USB SysEx — headless, from Python or the command line.
Author: jamisonx-dev
License: MIT License
        
        Copyright (c) 2026 Jamison
        
        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.
        
Project-URL: Homepage, https://github.com/jamisonx-dev/beatstep-pro-handler
Project-URL: Repository, https://github.com/jamisonx-dev/beatstep-pro-handler
Keywords: arturia,beatstep,beatstep pro,midi,sysex,controller,hardware
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-rtmidi>=1.4
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# 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.

```bash
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
```

```python
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`](beatstep_handler/protocol.py) — pure, dependency-free, and
unit-tested byte for byte.

## Install

From GitHub (works today, any OS):

```bash
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:

```bash
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

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

## License

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