Skip to content
jdesfossezPublic

About

Library to interact with BOSS GT-1000/GT-1000CORE guitar effects processors

Resources

Stars

11 stars

Watchers

1 watching

Forks

Latest commit

 

History

56 Commits

Folders and files

Repository files navigation

pygt1000

pygt1000 is a Python library for driving a BOSS GT-1000 / GT-1000CORE guitar & bass effects processor over MIDI (SysEx). Instead of hand-crafting hexadecimal messages, you address the unit's memory map by human-readable option names — set the "comp" block's "SUSTAIN" to 80, toggle "fx1" ON, read the current effect chain — and the library composes the correct address bytes, frames the SysEx message, computes the checksum, and (optionally) tracks the device's state for you.

It is a library, not an application: it exposes one facade class, GT1000, and a set of small, individually-usable seams underneath it. A reference application built on top of it — a live web editor — lives in a separate project (GT-1000PILOT).

Using this repo as a protocol reference? If you are re-implementing the GT-1000 protocol on another platform (an embedded target, another language), the two sections you want are The data pipeline (how the memory map is stored as data) and Crafting raw messages (how an address + value becomes a SysEx frame). The pygt1000/specs/*.json files are a complete, machine-readable transcription of the BOSS MIDI implementation and are usable on their own.

Features

  • Named access to the whole memory map — set/get any block parameter by option name (SUSTAIN, DRIVE, TYPE, …) instead of raw addresses.
  • Bidirectional — encode outbound messages and decode inbound ones (an address + value byte from the device back to (block, parameter, value name)).
  • Effect-chain read/write — read the signal chain (including parallel branches) as a word list or as an object model, and write a new one back.
  • Live parameter control with slider metadata — ask a block for the two parameters a UI should surface as sliders, each with its current value and its min/max range, and push changes back to the device as they move.
  • Device-state tracking — a background worker keeps a local snapshot of the unit's state in sync (handles patch changes, echoes, keep-alive).
  • Data-driven — the entire MIDI implementation lives as paired *.txt (transcribed from the BOSS PDF) / *.json (loaded at runtime) files, regenerated by the scripts in scripts/.
  • Testable without hardware — every seam takes its device dependency by injection, so the whole library runs against a fake transport with no MIDI wire (the test suite never loads the compiled rtmidi binding).

Installation

pip install pygt1000

Or for local development (the project uses Poetry):

git clone https://github.com/jdesfossez/pygt1000.git
cd pygt1000
poetry install
poetry run pytest -q      # ~270 tests, fast, no hardware needed

Quick start

from pygt1000 import GT1000

gt = GT1000()

# Open the MIDI ports. With no arguments it looks for a port whose name starts
# with "GT-1000"; pass in_portname / out_portname to override. Returns falsy on
# failure.
gt.open_ports()

# Pull the current device state and keep it refreshed in the background.
gt.refresh_state()
gt.start_refresh_thread()

# --- Change things by name (no hex) ---
gt.toggle_fx_state("comp", "1", "ON")      # turn the compressor block on
gt.set_fx_value("comp", "1", "SUSTAIN", 80)  # set a parameter (0-100 here)
gt.set_fx_type_type("fx", "1", "DISTORTION") # switch fx1 to a different effect

# --- Read things back ---
state = gt.get_state()                       # {fx_type: [FxBlock, ...], ...}
print(gt.lookup([0x10, 0x00, 0x24, 0x00], 0x1))  # decode a raw address+value

gt.stop_refresh_thread()
gt.close_ports()

The eleven addressable block types are: comp, dist, preamp, ns, eq, delay, mstDelay, chorus, fx, pedalFx, reverb. fx_id selects the instance ("1"–"4" for fx, "A"/"B" for preamp, "1" for single-instance blocks).

Reading device state

get_state() returns a snapshot: a dict keyed by block type (plus a "last_sync_ts" entry), where each block is a typed FxBlock (pygt1000.patch_state). Read its fields as attributes:

state = gt.get_state()
for block in state["comp"]:
    block.fx_id      # instance id
    block.state      # "ON" / "OFF"
    block.name       # resolved effect name (e.g. the current fx TYPE)
    block.slider1    # SliderValue or None
    block.slider2    # SliderValue or None

get_all_fx_type_states(fx_type) and get_one_fx_state(fx_type, fx_id) read a block's full presented state directly from the device on demand.

Live sliders (the UI workflow)

The slider feature exists to drive a UI: each block surfaces two parameters worth exposing as horizontal sliders, and moving a slider changes that parameter on the device in real time. get_state() (and the per-block reads) attach that metadata to every block as slider1 / slider2, each a SliderValue with the data a slider widget needs:

block = gt.get_state()["comp"][0]

for s in (block.slider1, block.slider2):
    if s is None:
        continue          # this block exposes fewer than two sliders
    s.label   # which parameter it controls, e.g. "SUSTAIN"
    s.value   # current value read from the device
    s.min     # range minimum  }-- drive the slider widget's bounds
    s.max     # range maximum  }

# When the user drags a slider, push the new value straight to the device
# (the slider's label is the parameter name):
gt.set_fx_value("comp", block.fx_id, block.slider1.label, 42)

Which two parameters a block exposes is policy encoded in the library (for fx blocks it depends on the currently-loaded effect; eq is a special case). This is exactly how GT-1000PILOT renders two live sliders per effect in its web UI.

Reading & writing the effect chain

The signal chain can be read and written in two equivalent representations — a flat word list, or an object model that makes parallel branches explicit:

from pygt1000.chain import EffectBlock, DividerBlock

txt_chain = gt.read_chain()               # ['PEDALFX', 'COMPRESSOR', 'FX1', ...]
obj_chain = gt.parse_chain(txt_chain)     # [EffectBlock(...), DividerBlock(...), ...]

gt.write_chain_from_txt(txt_chain)        # write from the word list
gt.write_chain_from_obj(obj_chain)        # or from the object model

A DividerBlock carries branch_a / branch_b lists and a mixer, so a split in the chain is represented structurally rather than as flat words. See examples/chain.py for a full round-trip example.

The data pipeline: BOSS PDF → JSON → addresses

The core of the library is not code, it's data: the GT-1000 MIDI implementation transcribed into structured tables. This is what makes the whole thing re-implementable on any platform.

 BOSS PDF spec  ──(transcribe by hand)──▶  pygt1000/specs/*.txt
        │                                          │
        │                              scripts/spec-to-json.py
        │                              scripts/options-to-json.py
        │                              scripts/chain-elements.py
        ▼                                          ▼
   human-readable                        pygt1000/specs/*.json  ──▶ loaded at
   tables                                (machine-readable)         runtime by
                                                                    AddressMap

1. The text tables (pygt1000/specs/*.txt) are the BOSS MIDI-implementation tables copied out of the PDF, one file per table, kept in the PDF's own | offset | bitmask | NAME (range) | layout. For example, PatchComp.txt:

| 00 00 | 0000 000a | SW (0 - 1) |
| | | OFF, ON |
| 00 02 | 0aaa aaaa | SUSTAIN (0 - 100) |
| 00 04 | 0aaa aaaa | LEVEL (0 - 100) |

2. The scripts (scripts/) parse those tables into JSON, applying the consistency fixes the raw transcription needs (normalising table names, expanding value lists, etc.):

  • spec-to-json.py / options-to-json.py — the parameter tables.
  • chain-elements.py — the chain-element name ↔ code map.

3. The JSON tables (pygt1000/specs/*.json) are what the library loads. Each parameter becomes an entry with its offset, numeric range, and named values. PatchComp.json:

"SUSTAIN": { "offset": [0, 2], "value_range": [0, 100], "values": {} },
"TYPE":    { "offset": [0, 1], "value_range": [0, 5],
             "values": { "BOSS COMP": 0, "X-COMP": 1, "D-COMP": 2, "...": 3 } }

4. At runtime, AddressMap composes a full 4-byte address from three layers of tables — base address, block offset, parameter offset — so no absolute address is ever hard-coded:

base-addresses.json   "temporary patch"  ─▶  base    = 10 00 00 00
Patch.json            "fx1"              ─▶  + offset =    00 23 00
PatchFx.json          "SW"              ─▶  + offset =       00 00
                                            ───────────────────────
                                            address  = 10 00 23 00
                      "SW" value "ON"    ─▶  value    = 01

The reverse direction (an inbound address + value → a decoded (block, parameter, value name)) uses the same tables, so decoding device messages is just the encode path run backwards.

Known gap: parameters whose range is wide enough to need more than one value byte are not fully handled yet — the address composition currently assumes a single value byte, which covers the large majority of parameters.

Crafting raw messages

For a lower-level view — or to reproduce the wire format elsewhere — the address composition and the SysEx framing are separately accessible. AddressMap produces the address (+ value) byte list; SysExCodec wraps it in a DT1 (set) or RQ1 (request) frame with the Roland manufacturer/model header and the checksum (128 - (sum(payload) % 128)):

from pygt1000 import GT1000
from pygt1000.sysex_codec import SysExCodec

gt = GT1000()
codec = SysExCodec()

# Compose "set fx1 SW = ON" as address + value bytes, straight from the JSON:
payload = gt._address_map.address_for_block("fx", "1", "SW", "ON")
# -> [0x10, 0x00, 0x23, 0x00, 0x01]

# Frame it as a DT1 (data set) SysEx message for device id 0x10:
codec.encode_dt1(device_id=0x10, payload=payload)
# -> [0xF0, 0x41, 0x10, 0x00,0x00,0x00,0x4F, 0x12,  0x10,0x00,0x23,0x00, 0x01,  0x4C, 0xF7]
#     F0  |  Roland | dev  | model id       | DT1 | address       | val | csum | F7

# Frame an RQ1 (data request) to read one byte at an address:
codec.encode_rq1(0x10, [0x10, 0x00, 0x24, 0x00], length=[0, 0, 0, 1])

Value-name ↔ byte lookups (e.g. for the TYPE selector of a block) are exposed too: gt.get_all_fx_types("comp") lists the type names, and gt.get_fx_value_from_value_name("comp", "TYPE", "D-COMP") returns the byte.

API overview

Method What it does
open_ports(in_portname=…, out_portname=…) / close_ports() Open / close the MIDI ports (port bring-up + editor-mode handshake).
refresh_state() Read the whole device state once into the local snapshot.
start_refresh_thread() / stop_refresh_thread() Start / stop the background sync + keep-alive workers.
get_state() Snapshot of the tracked state ({fx_type: [FxBlock, …]}).
get_all_fx_type_states(fx_type) / get_one_fx_state(fx_type, fx_id) Read a block's full presented state (state + name + sliders) on demand.
toggle_fx_state(fx_type, fx_id, "ON"/"OFF") Turn a block on/off.
set_fx_value(fx_type, fx_id, option, value) Set a parameter by name.
set_fx_type_type(fx_type, fx_id, new_type) Change a block's effect type.
lookup(address, value) Decode an inbound address+value into a DecodedValue.
read_chain() / parse_chain() / serialize_chain() Read / convert the effect chain.
write_chain_from_txt() / write_chain_from_obj() Write a new effect chain.
get_all_fx_types(fx_type) / get_fx_value_from_value_name(...) Enumerate effect types / resolve a value name to its byte.

Architecture

GT1000 is a thin facade that wires together a set of narrow, single-responsibility collaborators and owns almost no state itself: Transport (the MIDI wire), SysExCodec (wire format), DeviceLink (request/response), AddressMap (spec tables + encode/decode), PatchState (state model), BlockReader / BlockSnapshot (reads), ChainCodec (the chain round-trip), and the refresh/keep-alive workers. Each seam takes its device dependency by injection, so all of them are testable without the wire. The full construction and wiring narrative is in docs/architecture.md, and contributor guidance is in CLAUDE.md.

About

Library to interact with BOSS GT-1000/GT-1000CORE guitar effects processors

Resources

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages