# Getting Started

## Install

The [Download page](/download/) has the right file for every OS, with instructions: a drag-to-Applications app for macOS, zips for Windows, archives and AUR packages for Linux. `stompchain` is the CLI, `stompchain-gui` is the editor.

Or build from source, which also installs desktop integration:

```sh
git clone https://github.com/crmne/stompchain
cd stompchain
./install.sh
```

That builds everything, puts `stompchain` on your PATH, and installs the editor: a double-clickable app on macOS, a desktop entry with an icon on Linux. `./install.sh --cli-only` skips the GUI, and `--uninstall` removes it all again.

Building needs [Rust](https://rustup.rs). On Linux the GUI additionally needs the X11/Wayland development packages any egui application does. On Debian or Ubuntu:

```sh
sudo apt install libxkbcommon-dev libwayland-dev libgl1-mesa-dev
```

### USB access on Linux

A normal user cannot open a USB device on Linux without being granted access. `install.sh` installs a udev rule for Line 6 devices and asks for sudo once; without it, every connection fails with a permission error that looks like a bug in this program. Replug the device after installing. To do it by hand:

```sh
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0e41", MODE="0666", TAG+="uaccess"' \
  | sudo tee /etc/udev/rules.d/70-line6-hx.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```

### Model names and pictures

Names, parameter ranges, value formatting, and artwork come from HX Edit's own data files, which are Line 6's and are **not** redistributed here. The installer finds an installed HX Edit automatically. Without one, point the extractor at the installer you download from [line6.com/software](https://line6.com/software/):

```sh
tools/hxresources/extract.sh HX_Edit_3.82.dmg   # or the .exe
```

Everything degrades gracefully without this: the device still works, you just see model numbers instead of names and no pictures.

## Connect

**Quit HX Edit first.** It claims the vendor USB interface exclusively, and so does stompchain; only one editor can talk to the device at a time.

Plug in the pedal and start the editor:

```sh
stompchain-gui
```

It connects on launch. The signal chain runs across the top, presets down the left, and the selected block's knobs fill the middle, with the model browser on the right.

A few things worth knowing on day one:

- **Edits are live but not saved.** The device edits a scratch copy: a changed parameter is audible immediately but vanishes on reload unless you press Save. The amber dot next to Save tells you when there is something to save.
- **Add a block** by clicking any gap in the wire, then picking a pedal. Type to search; the picker opens ready for it.
- **Make a parallel branch** by dragging a block onto the dashed branch below the line, or by clicking the + on it.
- **Move the fork and merge** by dragging their dots along the line.
- **Undo, redo, save** are Ctrl+Z, Ctrl+Shift+Z, and Ctrl+S (Cmd on macOS).

## Handle with care

These devices can lock up hard enough to need their 9V adapter pulled; a USB replug is not enough, because the unit is externally powered and keeps its session across re-enumeration. Every lock-up during development traced back to the client, not the hardware, and each cause is now understood, avoided, and pinned by a regression test. The full post-mortem is in [PROTOCOL.md](https://github.com/crmne/stompchain/blob/main/PROTOCOL.md).