# dsh-rail-equalizer

Make DSH's **turn navigator rail** — the tick strip on the right side of the chat — move to whatever your computer is currently playing.

> Music, video, games: if the sound comes out of the default playback device, the rail reacts to it.
> **No permission prompt, no popup, no microphone, no screen recording** — and it still works with headphones on.

![The turn navigator rail reacting to system audio](assets/screenshot-1.png)

![The "律动" toggle row in the sidebar](assets/screenshot-2.png)

**Windows only** — the capture layer is WASAPI. 中文说明见 [README.md](README.md).

---

## How it gets the audio

This is the only heavy part of the plugin, and it is worth explaining.

The browser's `getDisplayMedia` **cannot be "authorized once"**. That is a deliberate Chrome/Edge security decision: every call has to pick a share target again, the grant is never persisted, and no API gets around it. Capturing the microphone, on the other hand, is completely useless when you are wearing headphones.

So this plugin uses **host-side WASAPI loopback** instead: the DSH host process (Node) calls Windows Core Audio COM interfaces directly through `koffi` and reads the PCM that the default render device is already mixing.

```
IMMDeviceEnumerator.GetDefaultAudioEndpoint(eRender)
  → IMMDevice.Activate(IAudioClient)
  → IAudioClient.Initialize(AUDCLNT_STREAMFLAGS_LOOPBACK)
  → IAudioClient.GetService(IAudioCaptureClient)
  → poll GetBuffer / ReleaseBuffer
```

This is **the same mechanism OBS uses to capture desktop audio**. It is not "recording" — it reads the buffer the system mixer has already handed to the sound card, therefore:

- there is no permission concept to ask anyone for
- headphones / speakers / HDMI / virtual devices all resolve to the **default render device** (switch the output in Windows and this follows)
- read-only: it never writes, never changes volume, never disturbs whatever is playing
- audio is reduced to levels **in memory only** — it never leaves the machine and is never written to disk

`koffi` ships **prebuilt binaries** through `optionalDependencies` (`@koromix/koffi-win32-x64`), so it works on install with no Visual Studio, no node-gyp, and no toolchain. (koffi's own `install` script is not required at runtime — the native binary resolves from the optional platform package either way.)

## How it avoids touching the official component

The rail is rendered by `@deepseek-ai/dsh-client-ui-chat`. This plugin does **not** patch it, fork it, or replace any of its code or components.

The browser half does exactly four things:

| What | Detail |
|---|---|
| Tag it | add a `data-dsh-eq` attribute to the rail's `<nav>` |
| Inject one stylesheet | a single `<style>` tag; everything is a CSS override (both known rail builds are covered) |
| Write some variables | `--dsh-eq-*` custom properties on `document.documentElement` |
| Draw one control row | pure DOM (`insertBefore`) for the sidebar row; the expanded settings panel uses the official `shell.overlay` slot |

**Why this cannot break anything:**

1. The animation only ever applies to **the visible bar**, and only stacks `scale` / `filter` / `box-shadow` on it.
   Official builds draw the bar differently, and both are covered:
   - **Newer build**: the bar is a real `<span class="…_tick">` whose size and opacity come from **React inline styles**. Inline styles win on specificity, so the four obvious properties must not be touched — the plugin stacks the **standalone `scale` property** instead. `scale` and `transform` do not override each other (the final matrix is translate × rotate × scale × transform), so the element's inline geometry and its four visual states are left pixel-identical.
   - **Older build**: the bar is a `button::before` pseudo-element, where `transform: … scaleX() scaleY()` is stacked.
   Each selector only matches its own build, so they never interfere.
2. Either way it **never touches `width` / `height` / `opacity` / `background-color`** — none of the official four states (current / hover / not-yet-loaded / generating) changes size or color.
3. Deformation starts at 1 (identity at rest) and `filter` starts at `brightness(1)`, with no `box-shadow` when there is no glow — when the level is silent, the visual result is the untouched original. Neither pseudo-elements nor `scale` participate in layout or show up in `getBoundingClientRect()`, so rail scrolling, coordinate mapping and click-to-jump are geometrically unaffected.
4. Only `filter: brightness()` and `box-shadow` are stacked; `background` / `color` are left alone, so theme tokens still apply.
5. The turn currently generating carries `aria-busy="true"`, and the stylesheet **explicitly excludes it** from the wave animation — its own "breathing" indicator is not overridden at all.
6. Per-tick wave phase is **static CSS generated with `nth-child`** (set on the row container and inherited downward). Nothing is ever written into the DOM, so there is no fight with React's rendering.
7. **Turning it off removes the attribute, the stylesheet and the variables** — all three. After that the rail looks exactly like a rail that never met this plugin.

## Install

**Windows only.** The capture layer needs WASAPI, and `package.json` declares `os: ["win32"]`, so on macOS / Linux the package manager refuses the install outright rather than letting it crash later.

```sh
dsh plugin --profile desktop add github:yuanyiHY/dsh-rail-equalizer
```

Then **restart DSH Desktop** — the host process has to reload the bundle to register the routes.

### From source / local directory (edits take effect immediately)

```sh
git clone https://github.com/yuanyiHY/dsh-rail-equalizer
dsh plugin --profile desktop add link:<absolute path you cloned to>
```

> ⚠️ The install path **must not contain spaces** — `dsh plugin` forwards arguments to pnpm, which shreds a spaced path into several package names. Keep local development in something like `~/.dsh/local-plugins/`.

> **No build toolchain needed.** `koffi` carries an `install` script, but its native binary is packaged inside an optional dependency (`@koromix/koffi-win32-x64`) and loads fine even when that script never runs. If pnpm asks you to approve build scripts, skipping it does not affect this plugin.

### Uninstall

```sh
dsh plugin --profile desktop remove dsh-rail-equalizer
```

After a restart the host-side capture and routes are gone entirely, and with the plugin no longer loaded the browser side injects nothing. You can also just flip the switch in the sidebar row — same result, effective immediately.

## Usage

A row appears in the sidebar, **directly above the official workspaces section**:

```
┌──────────────────────┐
│ ♪  律动        [ ⬤ ] │   ← click the row (outside the switch) to open/close settings
└──────────────────────┘      click the switch on the right to toggle it directly
```

**The row is inserted into the sidebar's document flow** (`insertBefore` the `[class*="_regionArea"]` element), the same approach other sidebar plugins such as the skill explorer use, with self-healing: if a React re-render displaces it, it is put back.

> **Why not register it in an official slot?** The only suitable sidebar position, `sidebar.workspaces`, is **`kind: "single"`** — registering into it would **replace the official workspaces section**. The other sidebar slots (`sidebar.settings` / `sidebar.brand.*`) are single as well. Hence DOM insertion, which is what other sidebar plugins do too.

> **Why not a `position: fixed` overlay?** Tried it — it **covered** other plugins inserted in the same area (that is how the skill explorer row got hidden). In the document flow each row has its own place and nothing overlaps.

There is no separate gear button either, so it cannot be confused with DSH's own settings gear. The settings panel only exists while expanded, anchored to the right of that row (`--dsh-eq-pill-x/y` are measured and written by JS).

Inside the panel:

| Item | Description |
|---|---|
| **Master switch** | turning it off restores the rail completely (the stylesheet is removed, not "zeroed") |
| **Motion mode** | one of four, applied immediately — see below |
| **Wave** | only meaningful in "wave" mode: off means the wave does not travel and ticks rise and fall in place |
| **Speed** | wave period, 0.46×–2.4× (slider value 2600–500 ms) |
| **Sensitivity** | 0.4–3.0. Raise it when system volume or the music itself is quiet |
| **Strength** | 0.2–2.0. Overall deformation amplitude |
| **Bass punch** | 0–2.0. How far kicks slam the ticks vertically |

### The four motion modes

Using the existing N ticks as material, four completely different motion models:

| Mode | Look | Driven by |
|---|---|---|
| **Spectrum** (default) | each tick's length is the frequency range it owns, low to high across the rail — like a music player's spectrum bars | `--dsh-eq-v` (the band assigned to that tick) |
| **Pulse** | all ticks in phase, the row expands and contracts together; the most "unified" | `--dsh-eq-lvl` + a global animation phase |
| **Sway** | ticks do not deform; the whole rail sways left and right | `--dsh-eq-sw` × level |
| **Wave** | ticks offset in phase, a wave travels along the rail | `--dsh-eq-lvl` + per-tick phase |

**Spectrum is the only true spectrum mode.** The host runs a 2048-point FFT with a Hann window and slices 40 Hz → 16 kHz into **16 logarithmically spaced bands** (matching how hearing works); the client then spreads those 16 bands evenly across however many ticks actually exist — so 5 ticks still show the full low-to-high distribution, and 50 ticks give you a continuous spectrum.

> The client hot-reloads and the host does not, so "new client / old host" is possible. With no band data available, **spectrum mode automatically degrades to moving the whole row together** rather than not moving at all. The `bandsAvailable` field in the self-report tells you which case you are in.

The bottom of the panel shows a live level meter and backend status (device format / connection state / error reason). Settings live in browser `localStorage` (key `dsh-rail-eq:settings:v1`).

## CPU and power

- Capture is **on demand**: it starts when a browser connects to the SSE stream and stops 8 seconds after the last one disconnects. **With no page open this plugin uses no CPU at all.**
- Measured decode cost is about **2 ms of CPU per second** (48 kHz stereo float32) — negligible.
- Levels are pushed at ~30 Hz over same-origin SSE; the browser side then smooths to the display refresh rate with `requestAnimationFrame`.
- The system's **"reduce motion"** preference (`prefers-reduced-motion`) is respected: only a gentle brightness variation remains, with no deformation or travelling wave.

## Troubleshooting

**The rail does not move at all**

1. Click the sidebar row to open the panel and read the status at the bottom:
   - `采集失败：...` (capture failed) → see "common errors" below
   - `已连接，等待音频…` (connected, waiting for audio) → the chain works, the system simply is not playing anything
   - `连接中…` (connecting) → the host routes are not up; most likely **DSH was not restarted**
   - `当前平台不支持（仅 Windows）` (unsupported platform) → expected; this implementation is Windows-only
2. Confirm the sound really comes from the **default render device**. Some players can target a separate output device; if they bypass the default, nothing is captured.
3. Confirm the rail is still on the page. The turn navigator is an official component; if it is renamed or removed upstream, this plugin silently does nothing and breaks nothing else.
4. **Still nothing → check the browser half's self-report.** The host cannot see the DOM, so the browser half posts its own state back, readable in the `clientReport` field of `GET /rail-eq/status`:
   `railFound` (was the rail found), `matched` (did the CSS selectors hit), `mode` / `tickCount` (current mode, how many ticks were counted),
   `bandsAvailable` (is the host sending band data), `vars` (how many level variables were written),
   `tick.scale` / `tickRect` (how far the bar was stretched), `uiRendered` (did the control row actually render).
   For "installed but no effect" problems this field usually pinpoints it immediately.

**`Initialize(LOOPBACK) failed 0x88890008`** — this device does not support loopback (rare; some exclusive modes and virtual devices). Switch to another default output and retry.

**`不支持的混音格式 tag=...` (unsupported mix format)** — the device's mix format is neither IEEE float32 nor PCM16. Setting the default playback device to 16-bit/24-bit at 44100/48000 Hz usually fixes it.

**Restart capture manually** (after switching playback devices):

```sh
curl -X POST http://127.0.0.1:<DSH port>/rail-eq/restart
```

Normally unnecessary — capture retries on its own after an error.

**Debug routes**

| Route | Purpose |
|---|---|
| `GET /rail-eq/status` | full state: capturing or not, audio format, packet count, client count, current level |
| `GET /rail-eq/level` | emit the current level once, **without** starting capture |
| `GET /rail-eq/stream` | SSE level stream (what the browser half consumes) |
| `POST /rail-eq/restart` | restart capture |
| `POST /rail-eq/report` | browser-half self-report (for "no effect" debugging; the result shows up in `/status` as `clientReport`) |

## Development

```
lib/
  index.js     host half: SSE routes + capture lifecycle (a Cordis plugin)
  wasapi.js    WASAPI loopback capture (Core Audio COM via koffi)
  analyzer.js  PCM → 4 time-domain levels + 16 log bands (2048-pt radix-2 FFT + Hann window, fast-attack/slow-release envelopes)
  client.js    browser half: rail binding + CSS variables + control UI
test/
  host-integration.mjs  host-side integration test (no DSH restart needed)
  band-probe.mjs        single-frequency band probe (which band does a tone land in)
  make-tone.mjs         generate a test tone
```

The host half is plain ESM and the browser half is a static `window.__ModuleLoader__.load({ id, factory })` bundle — **neither needs a build step**. Edit `lib/*.js` and restart DSH.

Running the tests (most meaningful while something is playing):

```sh
node test/make-tone.mjs 30
# play test/tone.wav in another window, then:
node test/host-integration.mjs
```

The tests cover: route dispatch, 404s, on-demand capture (a one-shot probe must not start capture), SSE headers and streaming, status replay, level sanity, independence of the four bands, spectrum structure (the strongest band clearly above the median), automatic shutdown after disconnect, and dispose cleanup.

### Two koffi gotchas

1. **Output parameters are not a returned array.** In koffi an `_Out_` parameter takes a container (`[null]`) that the native code writes into; the function's return value is the C return value (here an HRESULT).
2. **COM vtables must be dereferenced by hand.** `koffi.decode(obj, 'void *')` gives the vtable pointer, then `koffi.decode(vtable, index * ptrSize, 'void *')` gives the method pointer, and finally `koffi.call(fn, proto, obj, ...)`. The first entry of `proto` is `this`.

## Known limitations

- **Windows only.** The capture layer depends on WASAPI. On macOS, `ScreenCaptureKit` or a virtual audio device could do it; not implemented.
- **It captures the default render device.** If a player targets a separate output device, nothing is captured.
- **The rail is located through semantic anchors** (`nav` + `button[class*="_mark"]`, preferring `aria-label`), so it depends on neither Chinese/English copy nor hashed class names. If the official rail's DOM changes substantially, `findRail()` is the single function to fix.
- The DSH locale namespace is not used; UI copy is mixed Chinese and English.

## License

MIT — see [LICENSE](LICENSE).