README.md (4946B)
1 # Valentine 2 3 A terminal control panel for the **Focusrite Scarlett 18i20 (3rd Gen)** on macOS — 4 a from-scratch replacement for Focusrite Control, in the terminal. 5 6 Valentine speaks the device's proprietary "scarlett2" USB control protocol directly 7 (the same one Focusrite Control uses), so you get the mixer, routing, preamp 8 options, monitor section, metering, and clock status without the GUI — while Core 9 Audio keeps streaming audio normally. 10 11 > Status: works on the author's 18i20 3rd Gen; the protocol layer is 12 > hardware-validated. See **Limitations**. 13 14 ## Features 15 16 - **Inputs** — Air, Pad, Inst/Line, and 48 V phantom per channel, with live 17 per-channel meters and a stereo-pair view 18 - **Monitor** — hardware-knob readout, Mute, Dim 19 - **Mixer** — the full crosspoint matrix, gain in dB 20 - **Routing** — editable: set what feeds each output (stereo-pair aware) 21 - **Meters** — live input/output/mixer levels 22 - **Clock** — sync-lock status 23 - **Presets** — save/load a full configuration (incl. routing) to disk 24 - **Standalone** — write the current config to the device's NVRAM 25 - **Themes** — swappable TOML palettes (format shared with 26 [Hydra](https://ganten.neocities.org/projects.html)); 10 built in + a live 27 transparency toggle 28 29 ## Install 30 31 Requires a Rust toolchain ([rustup.rs](https://rustup.rs)). No system libraries — 32 `libusb` is vendored and built from source. No driver, no admin, no daemon. 33 34 ```sh 35 ./install.sh # builds + installs `valentine` to ~/.local/bin and themes to ~/.config/valentine/ 36 valentine # run it (quit Focusrite Control first) 37 ``` 38 39 Or run straight from the repo without installing: 40 41 ```sh 42 cargo run --release -p valentine 43 ``` 44 45 Uninstall with `./uninstall.sh` (add `--purge` to also remove your config). 46 Valentine must be run in a real interactive terminal, and only one app can own 47 the device at a time — quit Focusrite Control first. 48 49 ## Keys 50 51 ``` 52 Tab / Shift-Tab switch panels 53 ↑ ↓ ← → / hjkl move within a panel 54 Space / Enter toggle the focused control 55 + - 0 m mixer: ±1 dB, unity, mute 56 S save preset to ~/.config/valentine/presets/preset.json 57 L load preset and apply 58 W write current config to device NVRAM (standalone) 59 r reconnect ? help q quit 60 ``` 61 62 ## Theming 63 64 The palette is a TOML file. The bundled default is **Ember** 65 (`themes/default.toml`). To use your own, copy it to 66 `~/.config/valentine/theme.toml` and edit the hex values — it's loaded on startup 67 if present. 68 69 ## Project layout 70 71 ``` 72 valentine/ 73 ├── scarlett-core/ protocol engine (no UI, fully unit-tested) 74 │ └── src/ 75 │ ├── packet.rs 16-byte scarlett2 wire codec 76 │ ├── transport.rs USB EP0 transport (rusb) + test mock 77 │ ├── protocol.rs init / get / set / activate / sync 78 │ ├── model.rs 18i20 g3 config-offset map + topology 79 │ ├── controls.rs named controls (air, pad, 48V, monitor…) 80 │ ├── matrix.rs mixer / mux / meter ops + dB conversion 81 │ ├── ports.rs hardware port-ID → name decoding 82 │ └── preset.rs save/apply a configuration snapshot 83 ├── valentine/ the ratatui TUI 84 │ └── src/ 85 │ ├── main.rs app loop, key handling, layout 86 │ ├── theme.rs palette loading 87 │ └── panels/ one module per tab 88 └── themes/ 89 └── default.toml the bundled "Ember" palette 90 ``` 91 92 ## How it works 93 94 Focusrite interfaces are USB-Audio class compliant, so audio streaming needs no 95 driver. Everything else — mixer, routing, preamp, monitor, clock — is driven by 96 vendor control transfers on endpoint 0 of a vendor-specific interface. Valentine 97 implements that wire protocol in `scarlett-core`. The protocol facts (opcodes, 98 packet layout, config offsets, port IDs) are interoperability data derived from 99 the GPL Linux kernel driver `sound/usb/mixer_scarlett2.c` and the work of the 100 [alsa-scarlett-gui](https://github.com/geoffreybennett/alsa-scarlett-gui) project; 101 no GPL source is copied. 102 103 ## Limitations 104 105 - **Scarlett 18i20 3rd Gen only.** The protocol generalizes (the core carries a 106 per-model descriptor), but only this model is wired up and tested. 107 - **Routing is read-only.** Editing requires the device's per-sample-rate mux-table 108 write semantics, which aren't implemented/verified yet. 109 - **Firmware version** may read as 0 (its reply arrives on an interrupt endpoint 110 macOS won't let us claim while the Focusrite daemon is present). 111 - **Meter scaling** is approximate pending a proper dB calibration. 112 113 ## Credits 114 115 Built on the reverse-engineering of the scarlett2 protocol by Geoffrey D. Bennett 116 and contributors (Linux kernel driver + alsa-scarlett-gui). Valentine is an 117 independent macOS reimplementation of the control protocol.