Reverse-engineered, byte-level specification of the proprietary TSL (Tone Studio Liveset) file format used by the BOSS GX-10 guitar multi-effect processor.
No official documentation exists — this is the only publicly available reference for the GX-10 TSL format.
The BOSS GX-10 uses .tsl.json files to store guitar effect patches (presets) via the BOSS Tone Studio software. This project provides:
- Complete JSON structure mapping with exact byte-level layouts
- Hex encoding conventions for all parameter values
- Effect chain routing logic — how 20 effect slots are ordered in the signal path
- Control assignment mappings — expression pedal and footswitch → parameter routing
- Working Python code examples for reading, modifying, generating, and validating TSL files
- AI Generation Guidelines — specifically designed for LLMs and automated tools to programmatically generate valid patches
| File | Description |
|---|---|
specification.md |
The full 1,500+ line specification (v2.0) |
README.md |
This file |
| Finding | Detail |
|---|---|
| All values are hex-encoded strings | "08", "0F", "1E" |
| Fixed array sizes | Each param category has a strict byte count |
| Patch name = ASCII in bytes 0–15 | First 16 bytes of common parameters |
| Effect chain routing is separate | From effect parameters |
| 3-byte parameter encoding | In fxItem blocks (working hypothesis) |
The specification includes 6 practical examples and a complete TSLFile Python class (~250 lines) in Appendix C:
# Load and inspect a TSL file
import json
with open("my_patch.tsl.json", "r") as f:
tsl = json.load(f)
print(f"Name: {tsl['name']}")
print(f"Device: {tsl['device']}")
print(f"Patches: {len(tsl['data'])}")More examples in the spec:
- Setting patch names
- Enabling/disabling effects
- Building effect chains
- Copying patches between slots
- Validating TSL file integrity
This spec is explicitly written with AI generation in mind:
- Template-based patch generation — start from a known-good template, modify parameters
- Validation pipeline — verify generated files before loading
- ML feature extraction — scikit-learn pipeline sketch for learning from existing patches
GX10Patchhelper class — programmatic access to all parameters
├── Top-level JSON structure (name, formatRev, device, data)
├── ParamSet structure — 43 keys per patch (4,699 bytes)
│ ├── Common parameters (129 bytes) — patch name, global config
│ ├── LED parameters (28 bytes) — display/color settings
│ ├── Assign parameters (45 bytes × 20) — control routing
│ ├── Effect chain (62 bytes) — routing map
│ └── FxItem parameters (179 bytes × 20) — per-effect params
├── Complete Python library (TSLFile class)
└── Research notes & known unknowns (Appendix B)
- 🎸 Guitarists — programmatically create, modify, or batch-process GX-10 patches
- 👩💻 Developers — build patch editors, sharing platforms, preset managers
- 🤖 AI/ML engineers — generate valid TSL files with LLMs or ML models
- 🔧 Reverse engineers — reference for hardware protocol documentation
- Read the spec:
specification.md - Export a TSL file from BOSS Tone Studio
- Use the Python examples from the spec to load and modify it
- Load it back into your GX-10
Contributions welcome! Especially:
- 🔍 Validation of byte mappings against real GX-10 hardware
- 📝 Documentation improvements
- 🐛 Bug reports for incorrect parameter mappings
- 💡 New examples — share your use cases
- 🧪 Testing the 3-byte encoding hypothesis
See Appendix B for known unknowns and recommended testing methodology.
- BOSS Tone Studio — Official editor
- VGuitarForums — Active GX-10 community
- r/GuitarPedals — Reddit pedal community
MIT — see LICENSE for details.
Built with ❤️ by reverse engineering • Not affiliated with BOSS/Roland