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/*.jsonfiles are a complete, machine-readable transcription of the BOSS MIDI implementation and are usable on their own.
- 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 inscripts/. - 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
rtmidibinding).
pip install pygt1000Or 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 neededfrom 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).
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 Noneget_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.
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.
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 modelA 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 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.
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.
| 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. |
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.