From d331128e88a99f2379e5110108ba0dd788371c76 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=B3=96=E7=B3=96?= <tangtang@collaplex.local>
Date: Thu, 24 Sep 2026 09:36:36 +0800
Subject: [PATCH] =?UTF-8?q?=E8=BE=93=E5=87=BA=E8=AE=BE=E5=A4=87=E4=B8=8D?=
 =?UTF-8?q?=E5=86=99=E6=AD=BB:=20=E9=9D=A2=E6=9D=BF=E8=AE=BE=E5=A4=87?=
 =?UTF-8?q?=E9=80=89=E6=8B=A9=20+=20=E8=87=AA=E5=8A=A8=E6=8C=82=E8=BD=BD?=
 =?UTF-8?q?=E5=AE=88=E6=8A=A4(=E6=B2=BB=E5=BC=80=E6=9C=BA=E5=90=8E"?=
 =?UTF-8?q?=E5=8F=8C=E9=87=8D=E6=B7=B7=E5=93=8D")?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 问题: 30-collaplex-eq.conf 的 node.target 是安装时探测一次写死的。开机时设备若还没枚举
  (USB 耳机晚到很常见: 09-24 实测开机 08:57、耳机 09:19:43 才出现; 09-23 是 21:01 → 21:03),
  建链时目标不存在 → 末段连到别处或干脆不连, 设备出现后不会自己改回来 → 听感"双重混响",
  只能 stop + start
- 新增 web/output_route.py: 设备清单(pw-dump) + 选择落盘(output.json) + 守护线程(每 3 秒核对
  collaplex_eq_out 只连选中设备, 不对就拆错的、按声道补对的) → 设备一出现自动挂上
- web/server.py: GET /api/devices, POST /api/device(落盘 + 立刻挂载), 快照带 output 段,
  main() 起守护线程
- web/index.html: 「输出设备」卡片(下拉 + 应用 + 状态 + 守护备注; 设备表变化才重建选项, 免得
  60 Hz 重建打断点击)
- 脚本/安装.sh: 优先用记住的设备(不在位也照样按它建链), 不再"猜第一个 digital"
- 实测: 面板真点应用切走再切回 ✓ / 连错 2 秒自动纠回 ✓ / 全拆 3 秒自动挂回 ✓ / start 自检
  打印 [在位] ✓ / 面板像素验收 ✓; pyright strict 0 errors 0 warnings
- 坑: pw-dump 的 Link 键名是 output-port-id / input-port-id(写 output-port 一条连线都读不到);
  面板服务 enable --now 不会重启已在运行的实例(改 web/*.py 必须 restart)
---
 .gitignore                    |   3 +
 README.md                     |  45 +++++
 pipewire/30-collaplex-eq.conf |   5 +
 web/index.html                |  51 ++++++
 web/output_route.py           | 299 ++++++++++++++++++++++++++++++++++
 web/server.py                 |  23 ++-
 测试/包络示波器.py            | 134 +++++++++++++++
 测试/面板截图.py              |  57 +++++++
 脚本/安装.sh                  |  55 +++++--
 9 files changed, 657 insertions(+), 15 deletions(-)
 create mode 100644 web/output_route.py
 create mode 100644 测试/包络示波器.py
 create mode 100644 测试/面板截图.py

diff --git a/.gitignore b/.gitignore
index be6f7e0..a4b0e6d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,3 +14,6 @@ dist/
 
 # 本地状态与日志
 *.log
+
+# 测试截图
+测试/*.png
diff --git a/README.md b/README.md
index 1f5b0d9..ff33bc3 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,7 @@ collaplex-audio stop                                          # 连链路一起
 | **电平归一化** | 响度目标滑块 + **输入电平条** + **动态增益推子**(0 dB 在 60% 刻度线上, 量程 −18~+12 dB) |
 | **混响湿度** | 0 ~ 1, 实时生效 |
 | **总音量** | ±12 dB, 实时生效 |
+| **输出设备** | 下拉选输出到哪台硬件设备(HDMI / 内建模拟 / USB 耳机 …) + 「应用」; 右侧显示是否已挂载 |
 | **32 段 EQ** | 1/3 倍频程(20 Hz ~ 25 kHz), 每段 ±15 dB,**10 个预设** |
 
 - 所有滑块: **滚轮调节 · Shift+滚轮微调 · 双击归零**
@@ -270,6 +271,49 @@ collaplex-audio stop                                          # 连链路一起
 **注意**: 落盘是"最后一次改动的快照", 不是"出厂默认"。要回到出厂默认就删掉 `params.json`
 并清掉共享内存(`rm /dev/shm/collaplex-eq*`), 再重启链路。
 
+## 输出设备选择与自动挂载(2026-09-24)
+
+**问题**: 链路末段的输出设备原来**写死**在 `30-collaplex-eq.conf` 的 `node.target`(安装时探测
+"第一个 iec958/digital")。开机时那台设备要是还没枚举出来, 会话管理器建链时目标不存在,
+末段就连到别处或者干脆不连; 设备出现了也**不会**自己改回来。听感上就是"双重混响 / 声音
+不对", 只有 `collaplex-audio stop` + `start` 才恢复。
+
+**实测的时序证据**(两次都是同一个模式 —— 链路先建好、设备后到):
+
+| 日期 | 开机 | 输出设备(EDIFIER USB)枚举 | 备注 |
+|---|---|---|---|
+| 2026-09-23 | 21:01:17 | **21:03:01**(+1 分 44 秒) | 那次 DSP 进程号也对得上: 归一化/湿量在 3997~4034, EQ 到 8924 才起 |
+| 2026-09-24 | 08:57:07 | **09:19:43**(+22 分 36 秒) | `dmesg`: `usb 3-2.2: Product: EDIFIER Fit900NB` |
+
+**现在两件事一起做**:
+
+| 机制 | 说明 |
+|---|---|
+| **面板按钮** | 「输出设备」卡片: 下拉选硬件输出 + 「应用」→ 立刻重挂 + 落盘 |
+| **选择落盘** | `~/.local/state/cinema-spatial/output.json`: `{"node_name": "...", "description": "..."}`; `脚本/安装.sh` 优先用它, 不再"猜第一个数字输出" |
+| **自动挂载守护** | 面板进程里的守护线程(`web/output_route.py`), 每 3 秒核对"选中的设备在位 且 `collaplex_eq_out` **只**连到它"; 不对就拆掉错的、补上对的 —— **设备一插上就自动挂上, 不用重启链路** |
+
+**为什么设备名可以记住、挂载不能写死**: ALSA 节点名带 USB 序列号
+(`alsa_output.usb-EDIFIER_..._4250315939393214-00.iec958-stereo`), 跨重插/重开机稳定,
+所以"选哪台"能记住; 不稳定的是**建链那一刻设备在不在**, 那正是守护要兜的事。
+
+**实测**(2026-09-24, 全部真跑):
+
+| 场景 | 结果 |
+|---|---|
+| 面板真点「应用」切到内建模拟输出 | `routed` 立刻变成模拟输出 ✓ |
+| 再选回耳机点「应用」 | `routed` 变回 EDIFIER, 提示行 `已挂到 EDIFIER Fit900NB 数字立体声(IEC958)` ✓ |
+| 手动把末段连到错的设备, 等守护 | **2 秒**自动纠回 ✓ |
+| 把末段连线全拆掉, 等守护 | **3 秒**自动挂回 ✓ |
+| `collaplex-audio start` 自检 | 打印 `输出设备: … (EDIFIER Fit900NB 数字立体声(IEC958)) [在位]` ✓ |
+
+**接口**: `GET /api/devices`(设备清单 + 当前挂载 + 守护备注)、
+`POST /api/device {"name": "alsa_output.xxx"}`(落盘 + 立刻挂载)。
+
+**注意**: 面板服务单元是 `enable --now` —— 已经在跑时 `--now` **不会**重启, 所以改完
+`web/*.py` 必须 `systemctl --user restart collaplex-audio-panel.service`(否则新代码只落在
+磁盘上, 内存里还是旧的: 实测 `GET /api/devices` 会 404)。
+
 ## 实测(2026-09-19)
 
 | 指标 | 数据 |
@@ -435,6 +479,7 @@ uv run --with websocket-client python 测试/cdp_拖动验证.py    # CDP 真鼠
 | `pipewire/10,20,30-*.conf` | 虚拟声卡+归一化 / HRTF+混响+湿量级 / EQ |
 | `pipewire/91-collaplex-clock.conf` | 强制 96 kHz(不然 IR 会被按 48k 降采样) |
 | `web/server.py` `web/index.html` | 控制面板(纯标准库 + 单页, SSE 推送) |
+| `web/output_route.py` | 输出设备选择(落盘)+ 自动挂载守护(设备晚到时把末段挂上去) |
 | `hrir/` `reverb/` | HRIR(12 条)与房间 IR |
 | `脚本/安装.sh` `脚本/面板.sh` | 部署 / 起面板 |
 | `打包deb.sh` | 打 deb 到 `发布/` |
diff --git a/pipewire/30-collaplex-eq.conf b/pipewire/30-collaplex-eq.conf
index b86dd69..45ad1b2 100644
--- a/pipewire/30-collaplex-eq.conf
+++ b/pipewire/30-collaplex-eq.conf
@@ -1,5 +1,10 @@
 # Collaplex 32 段 EQ + 总音量 —— 本文件由 脚本/安装.sh 生成(占位符 __EQ_WRAPPER__ / __TARGET__)
 # 链路: ... -> HRTF 核心 -> [本图] 32 段 EQ + 总音量(pipe DSP) -> 数字输出
+#
+# ★ __TARGET__ 是**用户选定的输出设备**(落盘在 ~/.local/state/cinema-spatial/output.json,
+#   面板「输出设备」卡片可改; 没选过则由安装脚本探测第一个数字输出)。
+#   设备名跨重插是稳定的(含 USB 序列号), 所以设备晚到也不改这一行 —— 由面板守护
+#   (web/output_route.py)在设备出现后自动把它挂上去。
 context.modules = [
     {   name = libpipewire-module-filter-chain
         flags = [ nofail ]
diff --git a/web/index.html b/web/index.html
index fbf2667..eaa90d7 100644
--- a/web/index.html
+++ b/web/index.html
@@ -80,6 +80,9 @@ input[type=range]::-moz-range-thumb{width:14px;height:14px;border:none;border-ra
 button{background:var(--card-hi);color:var(--fg);border:1px solid var(--bd-hi);border-radius:6px;
        padding:5px 12px;font:inherit;font-size:11px;cursor:pointer}
 button:hover{border-color:var(--ok);color:var(--ok)}
+select{background:var(--card-hi);color:var(--fg);border:1px solid var(--bd-hi);border-radius:6px;
+       padding:5px 8px;font:inherit;font-size:11px;flex:1;min-width:0;cursor:pointer}
+select:hover{border-color:var(--ok)}
 </style>
 </head>
 <body>
@@ -128,6 +131,17 @@ button:hover{border-color:var(--ok);color:var(--ok)}
   </div>
 </div>
 
+<div class="card">
+  <h2>输出设备</h2>
+  <div class="row">
+    <span class="name">输出到</span>
+    <select id="outdev"></select>
+    <button id="outapply">应用</button>
+    <span class="num" id="outstate">—</span>
+  </div>
+  <div class="hint" id="outhint">换设备: 选一下再点「应用」。开机时设备晚到(USB 耳机常见)会由守护自动挂上, 不用重启链路。</div>
+</div>
+
 <div class="card">
   <h2>32 段 EQ（1/3 倍频程 · ±15 dB）</h2>
   <div class="presets" id="presets"></div>
@@ -437,8 +451,45 @@ function applyState(d) {
   if (!isBusy("loud") && d.loudness) { loud.value = d.loudness.target_db; el("loud-num").textContent = (+d.loudness.target_db).toFixed(1) + " dB"; }
   updateMeters(d.levels);
   updateLoud(d.loudness_levels);
+  updateOutput(d.output);
   state = d;
 }
+
+/* ---------- 输出设备 ---------- */
+/* 设备表只在变化时重建选项: SSE 是 60 Hz, 每帧重建 <select> 会把正在点的下拉打断。 */
+let outSig = "";
+function updateOutput(o) {
+  if (!o) return;
+  const sel = el("outdev");
+  const devs = o.devices || [];
+  const sig = JSON.stringify(devs.map((d) => [d.name, d.present]));
+  if (sig !== outSig) {
+    outSig = sig;
+    const keep = sel.dataset.touched ? sel.value : (o.device || "");
+    sel.innerHTML = "";
+    for (const d of devs) {
+      const op = document.createElement("option");
+      op.value = d.name;
+      op.textContent = (d.description || d.name) + (d.present ? "" : "（不在位）");
+      sel.appendChild(op);
+    }
+    if (keep) sel.value = keep;
+  }
+  if (!sel.dataset.touched && o.device) sel.value = o.device;
+  el("outstate").textContent = (o.routed && o.routed === o.device) ? "已挂载" : (o.routed ? "挂在别处" : "未挂载");
+  el("outhint").textContent = o.note || "";
+}
+el("outdev").addEventListener("change", () => { el("outdev").dataset.touched = "1"; });
+el("outapply").addEventListener("click", async () => {
+  const name = el("outdev").value;
+  if (!name) return;
+  const r = await fetch("/api/device", {
+    method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({name})});
+  const d = await r.json().catch(() => ({}));
+  say(d.ok ? ("输出设备: " + (d.message || name)) : ("切换失败: " + (d.error || "未知错误")));
+  el("outdev").dataset.touched = "";
+  if (d.output) updateOutput(d.output);
+});
 el("flat").addEventListener("click", () => { gains = new Array(32).fill(0); commitEq(); markPreset("平直"); markVenue(null); buildEq(state ? state.freqs : []); });
 el("reset").addEventListener("click", () => { state = null; fetch("/api/state").then(r => r.json()).then(applyState).catch(() => say("面板与 DSP 失联")); });
 fetch("/api/state").then(r => r.json()).then(applyState).catch(() => say("面板与 DSP 失联"));
diff --git a/web/output_route.py b/web/output_route.py
new file mode 100644
index 0000000..b7ee3d6
--- /dev/null
+++ b/web/output_route.py
@@ -0,0 +1,299 @@
+"""输出设备路由 + 自动挂载守护(纯标准库, 只依赖 pw-dump / pw-link)。
+
+为什么需要它
+------------
+链路末段原来把输出设备名**写死在 30-collaplex-eq.conf** 里:
+
+    node.target = "alsa_output.usb-EDIFIER_...iec958-stereo"
+
+开机时那台设备要是还没枚举出来(USB 耳机晚到很常见: 2026-09-24 实测开机 08:57、
+耳机 09:19:43 才出现), 会话管理器建链时目标不存在, 末段就连到别处或者干脆不连;
+等设备出现了也**不会**自己改回来 —— 听感上就是"双重混响 / 声音不对", 只能
+`collaplex-audio stop` + `start` 才好。
+
+本模块把这件事拆成两半:
+
+  1. **设备选择落盘**: `~/.local/state/cinema-spatial/output.json` 记住用户选了哪台
+     设备(面板按钮改它), 下次 start 优先用它, 不再猜"第一台数字输出"。
+  2. **自动挂载守护**: 后台线程每 3 秒核对一次"选中的设备在位 且 collaplex_eq_out
+     **只**连到它"; 不对就拆掉错的、补上对的。设备一出现就自动挂上, 不用再手动重启。
+
+守护只做"把末段挂到用户选的设备"这一件事, 不碰 DSP 参数、不重建链路。
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import threading
+import time
+from typing import Any
+
+EQ_OUT = "collaplex_eq_out"                 # 链路末段节点(它的输出要挂到设备上)
+CHAIN_PREFIX = "collaplex_"                 # 链路自己的节点, 不能当输出设备
+SINK_PREFIX = "alsa_output."                # 真实硬件输出节点名前缀
+STATE_DIR = os.path.expanduser("~/.local/state/cinema-spatial")
+OUTPUT_JSON = os.path.join(STATE_DIR, "output.json")
+POLL_SEC = 3.0                              # 守护核对间隔
+
+_last_note = ""
+
+
+def _run(*args: str) -> str:
+    """跑一条命令, 返回 stdout(失败返回空串, 不抛)。"""
+    try:
+        done = subprocess.run(args, capture_output=True, text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout
+
+
+def _dump() -> list[dict[str, Any]]:
+    """pw-dump 的对象列表(失败返回空表)。"""
+    raw = _run("pw-dump")
+    if not raw.strip():
+        return []
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return []
+    return data if isinstance(data, list) else []
+
+
+def _node_props(objs: list[dict[str, Any]]) -> dict[int, dict[str, Any]]:
+    """节点 id -> props。"""
+    out: dict[int, dict[str, Any]] = {}
+    for obj in objs:
+        if obj.get("type") == "PipeWire:Interface:Node":
+            info = obj.get("info")
+            props = (info or {}).get("props") or {}
+            if isinstance(props, dict):
+                out[int(obj["id"])] = props
+    return out
+
+
+def _port_map(objs: list[dict[str, Any]]) -> dict[int, dict[str, Any]]:
+    """端口 id -> props。"""
+    out: dict[int, dict[str, Any]] = {}
+    for obj in objs:
+        if obj.get("type") == "PipeWire:Interface:Port":
+            info = obj.get("info")
+            props = (info or {}).get("props") or {}
+            if isinstance(props, dict):
+                out[int(obj["id"])] = props
+    return out
+
+
+def _link_pairs(objs: list[dict[str, Any]],
+                nodes: dict[int, dict[str, Any]],
+                ports: dict[int, dict[str, Any]]) -> list[tuple[str, str, str, str]]:
+    """所有连线 -> (源节点名, 源端口名, 目标节点名, 目标端口名)。"""
+    def name_of(port_id: int) -> tuple[str, str]:
+        props = ports.get(port_id, {})
+        nid = int(str(props.get("node.id", -1)))
+        nname = str(nodes.get(nid, {}).get("node.name", ""))
+        return nname, str(props.get("port.name", ""))
+
+    out: list[tuple[str, str, str, str]] = []
+    for obj in objs:
+        if obj.get("type") != "PipeWire:Interface:Link":
+            continue
+        info = obj.get("info") or {}
+        # ★ 键名是 output-port-id / input-port-id(不是 output-port), 写错就一条连线都拿不到
+        on, op = name_of(int(info.get("output-port-id", -1)))
+        dn, dp = name_of(int(info.get("input-port-id", -1)))
+        if on and dn:
+            out.append((on, op, dn, dp))
+    return out
+
+
+def _graph() -> tuple[dict[int, dict[str, Any]], dict[int, dict[str, Any]],
+                      list[tuple[str, str, str, str]]]:
+    """一次拿到(节点表, 端口表, 连线表)。"""
+    objs = _dump()
+    nodes = _node_props(objs)
+    ports = _port_map(objs)
+    return nodes, ports, _link_pairs(objs, nodes, ports)
+
+
+def _port_by_channel(nodes: dict[int, dict[str, Any]],
+                     ports: dict[int, dict[str, Any]],
+                     node_name: str, direction: str) -> dict[str, str]:
+    """某节点的端口按声道取名: {"FL": "output_FL", "FR": "output_FR"}。"""
+    wanted_ids = {nid for nid, props in nodes.items()
+                  if str(props.get("node.name", "")) == node_name}
+    out: dict[str, str] = {}
+    for props in ports.values():
+        if int(str(props.get("node.id", -1))) not in wanted_ids:
+            continue
+        if str(props.get("port.direction", "")) != direction:
+            continue
+        channel = str(props.get("audio.channel", ""))
+        pname = str(props.get("port.name", ""))
+        if channel in ("FL", "FR"):
+            out[channel] = pname
+        elif pname.endswith("_FL"):
+            out["FL"] = pname
+        elif pname.endswith("_FR"):
+            out["FR"] = pname
+    return out
+
+
+def hardware_sinks() -> list[dict[str, Any]]:
+    """真实硬件输出设备清单(排除链路自己的虚拟节点)。
+
+    选中的设备即使不在位也带一条(present=False), 这样面板里不会"选项消失"。
+    """
+    nodes, _ports, _links = _graph()
+    found: list[dict[str, Any]] = []
+    for props in nodes.values():
+        if str(props.get("media.class", "")) != "Audio/Sink":
+            continue
+        name = str(props.get("node.name", ""))
+        if not name.startswith(SINK_PREFIX) or name.startswith(CHAIN_PREFIX):
+            continue
+        found.append({
+            "name": name,
+            "description": str(props.get("node.description", name)),
+            "present": True,
+        })
+    found.sort(key=lambda d: str(d["name"]))
+    chosen = saved()
+    if chosen["node_name"] and all(d["name"] != chosen["node_name"] for d in found):
+        found.append({
+            "name": chosen["node_name"],
+            "description": chosen["description"] or chosen["node_name"],
+            "present": False,
+        })
+    return found
+
+
+def saved() -> dict[str, str]:
+    """读落盘的设备选择; 没有就返回空(调用方自行回落探测)。"""
+    try:
+        with open(OUTPUT_JSON, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return {"node_name": "", "description": ""}
+    if not isinstance(data, dict):
+        return {"node_name": "", "description": ""}
+    return {
+        "node_name": str(data.get("node_name", "")),
+        "description": str(data.get("description", "")),
+    }
+
+
+def save(name: str, description: str) -> None:
+    """落盘设备选择(原子写: 临时文件 + rename)。"""
+    os.makedirs(STATE_DIR, exist_ok=True)
+    tmp = OUTPUT_JSON + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump({"node_name": name, "description": description}, fh)
+        fh.flush()
+        os.fsync(fh.fileno())
+    os.replace(tmp, OUTPUT_JSON)
+
+
+def routed() -> str:
+    """当前实际挂在哪台硬件设备上(没挂上返回空)。"""
+    nodes, _ports, links = _graph()
+    hardware = {name for name in
+                (str(p.get("node.name", "")) for p in nodes.values())
+                if name.startswith(SINK_PREFIX)}
+    for on, _op, dn, _dp in links:
+        if on == EQ_OUT and dn in hardware:
+            return dn
+    return ""
+
+
+def present(name: str) -> bool:
+    """设备现在在不在位。"""
+    nodes, _ports, _links = _graph()
+    return any(str(p.get("node.name", "")) == name for p in nodes.values())
+
+
+def apply_routing(target: str) -> tuple[bool, str]:
+    """把链路末段挂到 target: 先拆掉连到别处的线, 再按声道补上。
+
+    返回 (是否成功, 说明)。幂等: 已经挂对了就什么都不做。
+    """
+    if not target:
+        return False, "没选输出设备"
+    nodes, ports, links = _graph()
+    names = {str(p.get("node.name", "")) for p in nodes.values()}
+    if target not in names:
+        return False, "设备不在位"
+    if EQ_OUT not in names:
+        return False, "链路没在跑"
+
+    removed: list[str] = []
+    for on, op, dn, dp in links:
+        if on == EQ_OUT and dn != target:
+            _run("pw-link", "-d", f"{on}:{op}", f"{dn}:{dp}")
+            removed.append(dn)
+
+    have = {(op, dp) for on, op, dn, dp in links if on == EQ_OUT and dn == target}
+    outs = _port_by_channel(nodes, ports, EQ_OUT, "out")
+    ins = _port_by_channel(nodes, ports, target, "in")
+    added = 0
+    for channel in ("FL", "FR"):
+        op, ip = outs.get(channel), ins.get(channel)
+        if op is None or ip is None or (op, ip) in have:
+            continue
+        _run("pw-link", f"{EQ_OUT}:{op}", f"{target}:{ip}")
+        added += 1
+    detail = []
+    if removed:
+        detail.append("拆掉连到 " + "/".join(sorted(set(removed))))
+    if added:
+        detail.append(f"补上 {added} 条声道连线")
+    return True, ("已挂到 " + target + ("(" + ", ".join(detail) + ")" if detail else "(本来就挂对了)"))
+
+
+def status() -> dict[str, Any]:
+    """给面板用的一段状态: 选中设备 / 实际挂载 / 设备清单 / 守护备注。"""
+    chosen = saved()
+    now_routed = routed()
+    return {
+        "device": chosen["node_name"],
+        "description": chosen["description"],
+        "routed": now_routed,
+        "present": present(chosen["node_name"]) if chosen["node_name"] else False,
+        "devices": hardware_sinks(),
+        "note": _last_note,
+    }
+
+
+def select(name: str, description: str = "") -> tuple[bool, str]:
+    """面板按钮走过来: 落盘 + 立刻挂载一次。"""
+    save(name, description)
+    ok, msg = apply_routing(name)
+    return ok, msg
+
+
+def _watch() -> None:
+    """守护循环: 设备在位就确保挂载正确, 不在位就等着(设备一出现立刻挂上)。"""
+    global _last_note
+    while True:
+        try:
+            chosen = saved()
+            target = chosen["node_name"]
+            if not target:
+                _last_note = "没选输出设备"
+            elif not present(target):
+                _last_note = "等待设备: " + (chosen["description"] or target)
+            elif routed() != target:
+                ok, msg = apply_routing(target)
+                _last_note = msg if ok else ("挂载失败: " + msg)
+            else:
+                _last_note = "已挂到 " + (chosen["description"] or target)
+        except Exception as exc:                    # 守护线程绝不能死
+            _last_note = "守护异常: %s" % exc
+        time.sleep(POLL_SEC)
+
+
+def start_watcher() -> threading.Thread:
+    """起守护线程(daemon: 面板退出就跟着走)。"""
+    thread = threading.Thread(target=_watch, name="collaplex-output-watch", daemon=True)
+    thread.start()
+    return thread
diff --git a/web/server.py b/web/server.py
index 903f041..1609531 100644
--- a/web/server.py
+++ b/web/server.py
@@ -5,10 +5,12 @@
 页面:      /
 接口:
     GET  /api/state     参数 + DSP 双声道电平
+    GET  /api/devices   可选输出设备清单 + 当前挂载状态
     POST /api/eq        {"gains": [32 个数]}   每段 dB(±15)
     POST /api/volume    {"db": -12..12}        总音量
     POST /api/wet       {"wet": 0..1}          混响湿量
     POST /api/loudness  {"target_db": -30..-6, "on": bool}   响度归一化(DSP 每秒重读该 JSON)
+    POST /api/device    {"name": "alsa_output.xxx"}          输出设备(落盘 + 立刻挂载)
 """
 from __future__ import annotations
 
@@ -21,8 +23,10 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import cast
 
 sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir, "dsp"))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 import common  # noqa: E402
+import output_route  # noqa: E402
 
 PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8789
 FRAME_SEC = 0.016                # 面板推送间隔(约 60 Hz)
@@ -105,6 +109,7 @@ class Handler(BaseHTTPRequestHandler):
             "volume_limit": common.VOLUME_LIMIT,
             "levels": levels,
             "loudness": read_loudness(),
+            "output": output_route.status(),
         }
 
     def _stream(self) -> None:
@@ -144,6 +149,9 @@ class Handler(BaseHTTPRequestHandler):
         if self.path == "/api/state":
             self._send_json(self._snapshot())
             return
+        if self.path == "/api/devices":
+            self._send_json(output_route.status())
+            return
         if self.path == "/api/stream":
             self._stream()
             return
@@ -175,6 +183,16 @@ class Handler(BaseHTTPRequestHandler):
                 write_loudness({"target_db": target, "on": bool(on)})
                 self._send_json({"ok": True, "loudness": read_loudness()})
                 return
+            elif self.path == "/api/device":
+                name = str(data.get("name", ""))
+                known = {str(d["name"]): str(d["description"])
+                         for d in output_route.hardware_sinks()}
+                if name not in known:
+                    self._send_json({"ok": False, "error": "未知的输出设备: %s" % name}, 400)
+                    return
+                ok, msg = output_route.select(name, known[name])
+                self._send_json({"ok": ok, "message": msg, "output": output_route.status()})
+                return
             else:
                 self.send_error(404)
                 return
@@ -189,7 +207,10 @@ class Handler(BaseHTTPRequestHandler):
 
 def main() -> None:
     server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
-    print("Collaplex 音效面板: http://127.0.0.1:%d" % PORT, flush=True)
+    # ★ 输出设备守护: 设备晚到(USB 耳机开机后才枚举)时自动把链路末段挂上去,
+    #   否则末段会停在错的设备/不连, 听感就是"双重混响", 只能手动 stop + start。
+    output_route.start_watcher()
+    print("Collaplex 音效面板: http://127.0.0.1:%d (输出设备守护已启动)" % PORT, flush=True)
     server.serve_forever()
 
 
diff --git a/测试/包络示波器.py b/测试/包络示波器.py
new file mode 100644
index 0000000..3e4744b
--- /dev/null
+++ b/测试/包络示波器.py
@@ -0,0 +1,134 @@
+"""链路包络示波器: 直接读 DSP 共享内存, 拿"响度后(vsink_out)"与"EQ后(最终)"两处的包络。
+
+★ 为什么这么做: 这台机器没有 ALSA sink 的 .monitor 节点, 手动把链路输出 link 进录音流
+  会让录音流写 NaN(实测), 所以改用链路**自己**的电平表当示波器 —— DSP 每块(1024 样本
+  = 10.7 ms @96k)把输入/输出峰值写进 /dev/shm, 高频率轮询就能还原包络。
+
+判据(看形状, 不看绝对值):
+  干路脉冲   -> 一个孤立尖峰, 之后立刻掉到 -100 dBFS 以下
+  正常混响   -> 尖峰后**单调**衰减的尾巴
+  ★双重混响 -> 尾巴里出现第二个驼峰 / 第二段衰减, 或 20~200 ms 处有远高于邻域的孤立峰
+
+用法: python3 包络示波器.py [标签]
+"""
+from __future__ import annotations
+
+import mmap
+import struct
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+EQ_SHM = "/dev/shm/collaplex-eq"
+LOUD_SHM = "/dev/shm/collaplex-loudness"
+IMPULSE = Path.home() / "桌面/工作区/实验/collaplex音效/测试/取证/脉冲.wav"
+LABEL = sys.argv[1] if len(sys.argv) > 1 else "now"
+POLL_S = 0.002          # 轮询间隔 2 ms(远快于 10.7 ms 的块率)
+RUN_S = 6.0
+PLAY_AT = 2.0           # 第 2 秒播脉冲
+
+# common.py 布局: 参数(34×8)+版本(4) 之后是每声道 6×double
+STATE_OFF = 34 * 8 + 4
+CH_STRIDE = 6 * 8
+
+
+def db(x: float) -> float:
+    """线性 -> dBFS。"""
+    return 20.0 * np.log10(max(float(x), 1e-7))
+
+
+def read_eq(mm: mmap.mmap) -> tuple[list[float], list[float], list[float]]:
+    """EQ 段: (每声道 in_peak, out_peak, 已处理块数)。"""
+    inp: list[float] = []
+    outp: list[float] = []
+    cnt: list[float] = []
+    for ch in range(2):
+        base = STATE_OFF + ch * CH_STRIDE
+        inp.append(struct.unpack_from("<d", mm, base + 8)[0])
+        outp.append(struct.unpack_from("<d", mm, base + 24)[0])
+    mm.seek(STATE_OFF + 2 * CH_STRIDE)
+    for ch in range(2):     # 用 loudness 侧的块数当时间轴不合适, 这里用 out_peak 变化计数
+        cnt.append(0.0)
+    return inp, outp, cnt
+
+
+def read_loud(mm: mmap.mmap) -> tuple[list[float], list[float], list[float]]:
+    """响度段: (每声道输入峰值, 输出峰值, 施加增益 dB)。"""
+    peaks: list[float] = []
+    outs: list[float] = []
+    gains: list[float] = []
+    for ch in range(2):
+        base = ch * 32
+        peaks.append(struct.unpack_from("<f", mm, base + 8)[0])
+        gains.append(struct.unpack_from("<f", mm, base + 12)[0])
+        outs.append(struct.unpack_from("<f", mm, base + 28)[0])
+    return peaks, outs, gains
+
+
+def main() -> None:
+    """采样 + 播脉冲 + 打印包络。"""
+    feq = open(EQ_SHM, "rb")
+    meq = mmap.mmap(feq.fileno(), 0, prot=mmap.PROT_READ)
+    floud = open(LOUD_SHM, "rb")
+    mloud = mmap.mmap(floud.fileno(), 0, prot=mmap.PROT_READ)
+
+    # (t, loud_in, loud_out, eq_in, eq_out) —— 每次读到**变化**就记一笔(块级)
+    rows: list[tuple[float, float, float, float, float]] = []
+    t0 = time.monotonic()
+    played = False
+    last: dict[str, object] = {}
+    while True:
+        now = time.monotonic()
+        el = now - t0
+        if el > RUN_S:
+            break
+        if not played and el >= PLAY_AT:
+            print("播脉冲...")
+            subprocess.run(["pw-play", "--target", "collaplex_vsink", str(IMPULSE)],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30)
+            played = True
+        lp, lo, _lg = read_loud(mloud)
+        ei, eo, _ = read_eq(meq)
+        key = (round(lp[0], 6), round(lo[0], 6), round(ei[0], 6), round(eo[0], 6))
+        if key != last.get("k"):
+            last["k"] = key
+            rows.append((el, lp[0], lo[0], ei[0], eo[0]))
+        time.sleep(POLL_S)
+    meq.close()
+    mloud.close()
+
+    print(f"\n########## 包络标签: {LABEL} ##########")
+    print(f"块级采样 {len(rows)} 个点")
+    # 找 EQ 后输出的主峰(用脉冲那一侧的左声道)
+    eq_out = np.array([r[4] for r in rows], dtype=np.float64)
+    times = np.array([r[0] for r in rows], dtype=np.float64)
+    if eq_out.size == 0 or np.max(eq_out) <= 1e-9:
+        print("!! EQ 后全程无信号 —— 链路没在跑")
+        return
+    pk = int(np.argmax(eq_out))
+    print(f"主峰 {db(eq_out[pk]):.1f} dBFS @ 运行后 {times[pk]:.3f} s")
+    print("\n主峰前后的块序列(相对主峰, 每行 8 个点):")
+    lo_i, hi_i = max(0, pk - 8), min(len(rows), pk + 96)
+    for i in range(lo_i, hi_i, 8):
+        seg = rows[i:i + 8]
+        txt = " ".join(f"{db(r[4]):6.1f}" for r in seg)
+        print(f"  {(i - pk) * 10.7:>7.0f}ms  {txt}")
+    # 孤立峰判据
+    env = [db(v) for v in eq_out]
+    print("\n孤立峰检测(比前后 3 点中位数高 8 dB 以上, 且主峰外):")
+    hit = False
+    for i in range(4, len(env) - 4):
+        if abs(i - pk) <= 2 or env[i] < -70:
+            continue
+        nb = float(np.median(env[i - 4:i] + env[i + 1:i + 5]))
+        if env[i] - nb > 8.0:
+            print(f"   !! 距主峰 {(i - pk) * 10.7:.0f} ms: {env[i]:.1f} dBFS (邻域 {nb:.1f})")
+            hit = True
+    if not hit:
+        print("   无(尾巴是单调衰减)")
+
+
+main()
diff --git a/测试/面板截图.py b/测试/面板截图.py
new file mode 100644
index 0000000..1a83d96
--- /dev/null
+++ b/测试/面板截图.py
@@ -0,0 +1,57 @@
+"""面板截图(CDP): 打开 http://127.0.0.1:8789/ 截图, 用于像素级验收。
+
+用法: uv run --with websocket-client python 面板截图.py [输出png] [宽] [高]
+前置: google-chrome --headless=new --disable-gpu --no-sandbox \
+        --remote-debugging-port=9333 --remote-allow-origins='*' about:blank &
+"""
+from __future__ import annotations
+
+import base64
+import json
+import sys
+import time
+import urllib.request
+
+import websocket
+
+OUT = sys.argv[1] if len(sys.argv) > 1 else "/tmp/panel.png"
+W = int(sys.argv[2]) if len(sys.argv) > 2 else 1200
+H = int(sys.argv[3]) if len(sys.argv) > 3 else 1400
+URL = "http://127.0.0.1:8789/"
+
+targets = json.load(urllib.request.urlopen("http://127.0.0.1:9333/json/list"))
+page = [t for t in targets if t["type"] == "page"][0]
+ws = websocket.create_connection(page["webSocketDebuggerUrl"], timeout=30)
+_seq = [0]
+
+
+def cmd(method: str, **params: object) -> dict[str, object]:
+    """发一条 CDP 命令并等回包。"""
+    _seq[0] += 1
+    ws.send(json.dumps({"id": _seq[0], "method": method, "params": params}))
+    while True:
+        msg = json.loads(ws.recv())
+        if msg.get("id") == _seq[0]:
+            return msg
+
+
+cmd("Page.enable")
+cmd("Emulation.setDeviceMetricsOverride", width=W, height=H,
+    deviceScaleFactor=1, mobile=False)
+cmd("Page.navigate", url=URL)
+time.sleep(3.0)          # 等页面 + SSE 首帧
+
+# 顺手把新卡片里的文字读出来(和像素一起留证)
+expr = ("JSON.stringify({sel:document.getElementById('outdev')?document.getElementById('outdev').options.length:-1,"
+        "value:document.getElementById('outdev')?document.getElementById('outdev').value:'',"
+        "state:document.getElementById('outstate')?document.getElementById('outstate').textContent:'',"
+        "hint:document.getElementById('outhint')?document.getElementById('outhint').textContent:'',"
+        "status:document.getElementById('status')?document.getElementById('status').textContent:''})")
+got = cmd("Runtime.evaluate", expression=expr, returnByValue=True)
+print("页面自述:", got.get("result", {}).get("result", {}).get("value"))
+
+shot = cmd("Page.captureScreenshot", format="png", captureBeyondViewport=True)
+data = base64.b64decode(str(shot["result"]["data"]))  # type: ignore[index]
+with open(OUT, "wb") as fh:
+    fh.write(data)
+print("已保存:", OUT, len(data), "字节")
diff --git a/脚本/安装.sh b/脚本/安装.sh
index 03655aa..b863fd2 100755
--- a/脚本/安装.sh
+++ b/脚本/安装.sh
@@ -22,21 +22,48 @@ EQ_IN="collaplex_eq_in"
 PY="${PY:-$ROOT/.venv/bin/python}"
 [ -x "$PY" ] || PY=/usr/bin/python3
 
-# ---- 1. 探测数字输出 ----
-TARGET=$(pw-dump | /usr/bin/python3 -c '
-import json, sys
-for n in json.load(sys.stdin):
-    if n.get("type") != "PipeWire:Interface:Node":
-        continue
-    p = (n.get("info") or {}).get("props") or {}
-    if p.get("media.class") == "Audio/Sink":
-        nm = p.get("node.name") or ""
-        if "iec958" in nm or "digital" in nm.lower():
-            print(nm)
+# ---- 1. 探测输出设备 ----
+# 优先用**记住的选择**(面板按钮/上次 start 落盘的 output.json) —— 设备名跨重插是稳定的
+# (含 USB 序列号), 所以"现在不在位"也照样先按它建链, 设备一插上由面板守护自动挂上。
+# 没记忆过就照旧: 先找数字输出(iec958), 再退到任意硬件输出。
+TARGET_INFO=$(/usr/bin/python3 - "$ROOT/web" <<'PY'
+import sys
+
+sys.path.insert(0, sys.argv[1])
+
+import output_route  # noqa: E402
+
+chosen = output_route.saved()
+sinks = output_route.hardware_sinks()
+desc_of = {d["name"]: d["description"] for d in sinks}
+target = chosen["node_name"]
+if not target:
+    for d in sinks:
+        if "iec958" in d["name"] or "digital" in d["name"].lower():
+            target = d["name"]
             break
-')
-[ -n "$TARGET" ] || { echo "找不到数字输出设备(iec958)"; exit 1; }
-echo "数字输出: $TARGET"
+    if not target and sinks:
+        target = sinks[0]["name"]
+if not target:
+    print("\t\t")
+    raise SystemExit
+desc = desc_of.get(target, "")
+output_route.save(target, desc)          # 落盘: 面板守护与下次 start 共用这一份选择
+present = any(d["name"] == target and d["present"] for d in sinks)
+print("%s\t%s\t%s" % (target, desc, "在位" if present else "不在位"))
+PY
+)
+TARGET=$(printf '%s' "$TARGET_INFO" | cut -f1)
+TARGET_DESC=$(printf '%s' "$TARGET_INFO" | cut -f2)
+TARGET_STATE=$(printf '%s' "$TARGET_INFO" | cut -f3)
+if [ -z "$TARGET" ]; then
+    echo "找不到任何输出设备, 也没有记住的选择 —— 先把耳机/声卡接上再 start"
+    exit 1
+fi
+echo "输出设备: $TARGET (${TARGET_DESC:-未知}) [$TARGET_STATE]"
+if [ "$TARGET_STATE" != "在位" ]; then
+    echo "  ★ 设备当前不在位: 链路先建好, 设备一出现由面板守护(output_route)自动挂上, 不用重启"
+fi
 
 # ---- 2. 部署 pipe 插件入口(必须 ASCII 路径) ----
 mkdir -p "$(dirname "$WRAPPER")"