docs(op): refine pro-audio verification + snapshot guidance

Clarify sink/ELD/Jack mapping pitfalls, add drain-timeout troubleshooting, and document a baseline snapshot workflow for repeatable HDMI audio verification. Debian packaging is explicitly deferred until validation is complete.

Made-with: Cursor

docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

@@ -2,6 +2,8 @@
 
 **适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。
 
+**当前阶段**：以 **本机手工配置 + 文档/脚本复现** 完成技术验证（pro-audio / UCM、插拔、多显示器等）。**Debian 包（`debian/`、`kaisa-hdmi-pipewire-fix`）暂缓**：待验证结论稳定后再考虑打包与分发，本文 **§4.4** 仅作预留参考。
+
 ---
 
 ## 路径选择（pro-audio 与 UCM，先选哪条）
@@ -23,7 +25,7 @@
 |------|------|
 | 设置里只有 **「立体声」**、**`pactl list short sinks` 仅 1 个** | 声卡 profile 为 **`stereo-fallback`**，未暴露多路 HDMI PCM。 |
 | GNOME **「测试扬声器」** 无图标 | HDMI / Pro Audio 常无 Front L/R 声道名，**界面不可用**不代表无声；PipeWire 下用 **`speaker-test -D pulse`** 或 **`paplay`**（走默认 sink）；**`plughw:…`** 常与 PipeWire **EBUSY (-16)** 冲突。 |
-| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
+| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器** 时，通常不应指望有声；但 **Jack 与 ELD、`hw:0,N` 的编号不一定一一对应**（见 §3 文末）。排障以 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 里的 **`api.alsa.path`（如 `hw:0,2`）** 与 **`aplay -l` 子设备**为准。 |
 | **`IEC958',N` 与 `IEC958 Playback Switch`** | 本机简单控件名为 **`IEC958',0`** 等（与 **pcm=2/3/4** 对应）；**`Mono: Playback [off]`** 时 PipeWire 仍可能 **RUNNING**、**`speaker-test -D pulse`** 仍跑计数，但 **HDMI 无声**。核对：**`amixer -c0 cget numid=14,20,26`** 或 **`sget 'IEC958',0`**。 |
 
 ---
@@ -115,10 +117,18 @@ pactl get-default-sink
 pactl list short sinks
 ```
 
-插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。
+插入 HDMI 后，**默认 sink 以本机为准**：可能是 **`...pro-output-2`**（界面常标 **Pro 2 / HDMI1**），也可能是 **`pro-output-3` / `pro-output-4`**，取决于物理口、显示器与 PipeWire 优先级。**不要**仅凭 **`HDMI/DP,pcm=N Jack`** 或某条 **`eld#2.X`** 就断定必须用 `pro-output-N`；用下面命令确认当前默认输出实际绑定的 ALSA 设备：
+
+```bash
+wpctl inspect @DEFAULT_AUDIO_SINK@ | grep -E 'api\.alsa\.path|node\.name|alsa\.device'
+```
+
+例如 **`api.alsa.path = "hw:0,2"`** 即当前声音送往 ALSA **device 2**（常对应 **Pro 2**）。
 
 **出声测试（推荐）**：桌面默认用 PipeWire 时，声卡常被其占用；此时 **`speaker-test -D plughw:0,2`** 会报 **打开错误: -16（设备或资源忙，EBUSY）**，属正常现象。请先 **`pactl set-default-sink`** 指到目标 HDMI sink，再经 **Pulse 兼容设备** 测试：
 
+**若 `paplay` 报「排空流失败：超时」、且 `pactl list short sink-inputs` 为空**：该路 sink 可能未能正常完成播放（或默认 sink 并非你以为的那路）。请依次 **`pactl set-default-sink …pro-output-2/3/4`** 配合 §4.2 打开对应 **IEC958**，并用 **`speaker-test -D pipewire`** 复测；同时查看 **`journalctl --user -u pipewire`** 是否出现 **`set_hw_params` / 输入输出错误**。
+
 ```bash
 speaker-test -D pulse -c2 -t sine -f 440 -l 3
 ```
@@ -215,13 +225,15 @@ amixer -c0 sset 'IEC958',0 on
 
 ### 4.3 登录自动恢复（规划中）
 
-**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为稳定工具随 **`kaisa-hdmi-pipewire-fix`** 发布。
+**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为随仓库分发的稳定工具（deb 亦暂缓，见文首说明）。
 
 **当前**：请用 §4.1 / §4.2 **手动命令**；需要登录自启时，自行编写 **user systemd**（可参考 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 结构，**`ExecStart`** 指向你本机的 shell 片段或脚本）。
 
-### 4.4 Debian 包（系统级交付）
+### 4.4 Debian 包（系统级交付，暂缓）
 
-仓库 **`debian/`** 提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
+**说明**：在技术验证未收尾前，**不必**关注本节；优先完成 §1–§3、UCM 与基线脚本。**验证稳定后**再决定是否维护 **`debian/`** 与 **`kaisa-hdmi-pipewire-fix`**。
+
+仓库 **`debian/`** 可提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
 
 ```bash
 ./scripts/build-deb.sh
@@ -284,6 +296,24 @@ cd /path/to/chromebox_10th_audio_driver
 
 **若曾自建** §4.3 的 **user systemd** 自动执行 **`pactl`/`amixer`**，恢复基线前请先 **`disable --now`** 相应单元，避免登录后仍改 profile。
 
+### 4.6 已验证出声后如何「落盘记录」（备份与 Git 分工）
+
+**目的**：区分「本机可还原的现场」与「仓库里可复现的配置/说明」，避免把大块拓扑采集误提交进 Git。
+
+| 做法 | 内容 | 是否适合进 Git |
+|------|------|------------------|
+| **本机基线** | 运行 **`./scripts/capture-ubuntu-audio-baseline.sh`**，得到 `audio_topology/baseline-stash/<时间戳>_<hostname>/`（含 **`topology.txt`**、**`manifest.txt`** 等） | **通常否**（目录默认在 **`.gitignore`**，体积与隐私不宜入库） |
+| **仓库提交** | 更新 **`OPERATION`** / **`REPRO_*.md`**、UCM 与 WirePlumber 源码；在文档中**写一句**当时验证要点（例如 **`pro-audio` + 默认 **`Pro 2`**、`hw:0,2`）。**`debian/`** 待完整验证后再纳入常规提交 | **是**（deb 相关目录**暂缓**） |
+
+**建议在 OPERATION 或提交说明里记一行「事实锚点」**（便于以后对照）：`pactl get-default-sink` 的 sink 名、**`wpctl inspect @DEFAULT_AUDIO_SINK@`** 中的 **`api.alsa.path`**、以及 **`amixer -c0 cget numid=14,20,26`** 中对应 **IEC958** 是否为 on。
+
+**本机最新一次“技术验证过程快照（含已验证 Pro 2/Pro 3 HDMI 可出声）”（勿入库）**：
+
+- 基线目录：`audio_topology/baseline-stash/20260407_235227_jack-Kaisa/`
+- 采集时间：`2026-04-07T23:52:31+08:00`
+- 采集命令：`./scripts/capture-ubuntu-audio-baseline.sh`
+- 快速锚点（供对照）：`IEC958 numid=14/20/26 = on`；ELD/Jack/默认 sink 等以该基线的 `topology.txt` 与采集时现场为准（建议同时记录 `pactl get-default-sink` 与 `wpctl inspect @DEFAULT_AUDIO_SINK@`）
+
 ---
 
 ## 5. 参考链接