docs(kaisa): ProAudio 主路线、WirePlumber default-profile 与一键脚本

- 新增 OPERATION_PipeWire_Kaisa_ProAudio / UCM_HiFi，核心问题复盘与恢复 Ubuntu 重测手顺；HDMI 旧文改为 stub。
- 脚本：apply / verify-pro-audio、strip default-profile、reapply-session、remove deb 与 UCM overlay、verify-audio-environment。
- systemd-user：kaisa-pro-audio-reapply.service 示例。
- README、docs 索引、REPO_INDEX、REPRO deb 存档说明；deb 标为未来计划；reference/ucm2 与采集脚本小改。
- debian 与 _bmad-output 规划文件随本次工作区一并更新。

Made-with: Cursor

docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

@@ -1,373 +1,10 @@
-# 操作：Kaisa（sof-rt5682）Ubuntu 上 HDMI 出声与 WirePlumber 固化
+# 本文件已拆分（兼容旧链接）
 
-**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。
+原 **`OPERATION_PipeWire_Kaisa_HDMI.md`** 已拆成两篇，请直接打开：
 
-**当前阶段**：以 **本机手工配置 + 文档/脚本复现** 完成技术验证（pro-audio / UCM、插拔、多显示器等）。**Debian 包（`debian/`、`kaisa-hdmi-pipewire-fix`）暂缓**：待验证结论稳定后再考虑打包与分发，本文 **§4.4** 仅作预留参考。
-
----
-
-## 路径选择（pro-audio 与 UCM，先选哪条）
-
-| 目标 | 做法 |
+| 文档 | 内容 |
 |------|------|
-| **先确认 HDMI 能否出声（对照实验）** | **pro-audio**：把 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)** 放到 **`~/.config/wireplumber/wireplumber.conf.d/`**（文件名以 **`.conf`** 结尾），**`systemctl --user restart wireplumber pipewire pipewire-pulse`**，再 **`pactl set-card-profile <卡名> pro-audio`**、**`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应路），按 §4.2 打开对应 **`IEC958',N`**，最后 **`paplay` / `speaker-test -D pulse`**。 |
-| **长期「无 Jack 不误导」、桌面端口模型** | **UCM**：安装 overlay 后 **移走** 上述 WirePlumber 片段，依赖 WirePlumber 按 UCM 启用 **`HDMI1/2/3`**；与 pro-audio **互斥**（见下 §2.3）。 |
+| **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** | **主路线（已验证）**：PipeWire **pro-audio**、`50-kaisa-sof-rt5682-hdmi.conf`、默认 **`pro-output-0` / `pro-output-2`**、IEC958、一键脚本与基线（**deb 仅 §4.4 存档**） |
+| **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** | **可选**：ALSA **UCM2**、**HiFi**、`60-kaisa-ucm.lua`、Jack 驱动端口、安装 / 验收 / 卸载 |
 
-**建议顺序**：先走 **pro-audio** 验证硬件与 PipeWire 路由；**有声之后**再决定继续 **修 UCM**（例如消除 **`Failed to enable ucm device HDMI*`**）或 **长期保留 pro-audio**。**「自动屏蔽未插入的 HDMI」** 依赖 UCM 或自写策略，见 §2.3，应在 **HDMI 已能出声** 之后再做。
-
-**若已安装 `kaisa-hdmi-pipewire-fix` 却未卸载**：deb 会把 **UCM2** 装入 **`/usr/share/alsa/ucm2/`**（如 **GoogleKaisa**）。仅恢复 **`50-kaisa-…conf`** 时，WirePlumber **仍会按 UCM 做端口可用性**，未插线的 HDMI 可能继续**不可用 / 像被「隐藏」**，与「全开 pro-audio 对照」不一致。要做**干净 pro-audio 基线**：先 **`sudo apt purge kaisa-hdmi-pipewire-fix`**，再按上文复制 WirePlumber 片段。系统自带的 **`alsa-ucm-conf`** 仍可能提供通用 **`sof-rt5682`** 配置；若仍异常，以本机 **`alsaucm` / `pactl list cards`** 为准。
-
----
-
-## 1. 现象与原因（摘要）
-
-| 现象 | 说明 |
-|------|------|
-| 设置里只有 **「立体声」**、**`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** | 该路 **未检测到显示器** 时，通常不应指望有声；但 **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`**。 |
-
----
-
-## 2. 固化方案：WirePlumber `wireplumber.conf.d`
-
-在 **`~/.config/wireplumber/wireplumber.conf.d/`** 下放片段（**文件名以 `.conf` 结尾**），实现：
-
-1. **强制 `device.profile = pro-audio`**：始终暴露 **Pro / Pro 2 / Pro 3 / Pro 4**（与 `aplay -l` 中 **Port1 / HDMI1/2/3** 对应）。
-2. **`monitor.alsa.rules` 提高 HDMI 相对模拟口的 `priority.session`**：HDMI sink **可用且优先级更高** 时，WirePlumber 倾向将其设为 **默认输出**；拔出后回退到模拟（以本机行为为准）。
-
-仓库内 **示例文件**（可复制到上述目录）：
-
-- [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)
-
-安装命令示例：
-
-```bash
-mkdir -p ~/.config/wireplumber/wireplumber.conf.d
-cp /path/to/chromebox_10th_audio_driver/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
-   ~/.config/wireplumber/wireplumber.conf.d/
-systemctl --user restart wireplumber pipewire pipewire-pulse
-```
-
-**优先级（示例文件内）**：`pro-output-0`（模拟）**1000**；`pro-output-3` **1090**；`pro-output-4` **1095**；`pro-output-2`（HDMI1）**1100**。多路 HDMI 同时存在时 **HDMI1 优先**；若你常接 **HDMI2/3**，可把对应 `node.name` 的优先级调到 **高于 1100**。
-
-**PCI 路径变化**：若 `lspci` 中音频 BDF 不是 **`0000:00:1f.3`**，用以下命令查看实际 **`device.name` / `node.name`** 并替换 conf 中的字符串：
-
-```bash
-pactl list cards
-pactl list short sinks
-```
-
-**WirePlumber 大版本升级**：语法可能变化，见 [WirePlumber migration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html)。
-
-### 与系统「声音设置」里输出列表的预期
-
-本文 **`pro-audio` + `monitor.alsa.rules`** 的首要目标是：**在 PipeWire 侧暴露多路 sink**（**`pactl list short sinks`** 中的 **`pro-output-*`**）、配合 **IEC958** 与 **默认 sink / 优先级** 让 HDMI **能出声**、可经 **`pactl set-default-sink`** 或 **`speaker-test -D pulse`** 验证。各**桌面环境**自带的 **「设置 → 声音」** 面板如何枚举输出，取决于其是否把 **`pro-audio` 下的节点**画成易选项、以及 **`pactl list cards`** 里 **声卡「端口」**是否包含 HDMI；在 **`pro-audio`** 下常出现 **仅列出模拟类端口、HDMI 不单独出现在卡端口列表** 的情况，**不等于** HDMI sink 不存在。因此 **「插上 HDMI 后，这一路自动出现在系统声音设置的选择器里」** 不能仅凭本仓库片段保证；若需在图形界面里切换 **`pro-output-*`**，可改用 **Pulse 兼容混音器**、**Patchbay / 节点路由工具** 等（包名因发行版而异；常见可选组件如 **pavucontrol**、**Helvum**），或在终端用 **`wpctl`** 查看与切换。若期望 **插拔与可用性严格对应、并在设置里以「端口」形式出现**，长期更依赖 **ALSA UCM（`alsa-ucm-conf` 等）** 与栈的集成，而非仅 WirePlumber 静态规则。
-
-### 与「无 Jack 就从选择器里删掉」
-
-**与本文 §2 策略存在根本取舍**：
-
-- **`device.profile = pro-audio`** 的作用，正是把 **`aplay -l` 里多路 PCM（含 HDMI1/2/3）都变成独立 sink**（**`pro-output-*`**），**一般不随** 某路 **`HDMI/DP,pcm=N` Jack** 关而自动从 PipeWire 里消失；否则也谈不上「多路一次暴露、再调优先级」。
-- WirePlumber 文档里虽有 **`node.disabled`**（设为 true 时 **PipeWire 会从节点列表里去掉该 sink**），但 **要匹配「无 Jack」** 需要 **节点属性里存在可随插拔变化的量**，且 **规则在 Jack 变化时会被重新应用**；**仅靠** 仓库里这一条 **静态 `monitor.alsa.rules`**，**不能保证** 对所有机型、所有 PipeWire 版本都实现 **「无 Jack = 选择器里完全没有该项」**。
-
-**若把「按 Jack 隐藏」放在第一位**，可行方向是 **换策略**，而不是把 **`50-kaisa-sof-rt5682-hdmi.conf` 改两行就完事**：
-
-1. **UCM / ACP 端口模型**：用 **端口 availability** 驱动路由，让 **未接线的 HDMI** 不成为可选输出（**更接近** Windows/桌面对「无效口」的处理）；**代价**是与 **强制 pro-audio 一次性拉满多路** 的路线不同，需单独调通 **Kaisa** 的 UCM 与 **IEC958**（详见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)** 与 §2.3 互斥说明）。
-2. **WirePlumber Lua 或自写守护**：监听 **ALSA jack** / 轮询 **`amixer`**，在 **Jack off** 时对对应节点设 **`node.disabled`**（或 **`pw-cli`** 改属性）；**可定制**，但要 **自己维护** 与升级。
-3. **保持本文 §2**：继续 **pro-audio + IEC958**，接受 **选择器里可能仍列出多路**（即便某路 **Jack off**），以 **换线后 `set-default-sink` / `amixer`** 对齐实际出声口。
-
-**结论**：**「无 Jack 就从选择器里删掉」** 与 **「强制 pro-audio 暴露全部 HDMI」** 不能无代价同时成立；要实现前者，**应优先评估 UCM 路线或自定义策略**，而不是假定 **单靠一个与当前 `50-*.conf` 同类的静态片段** 即可覆盖。
-
-### UCM 模式 vs pro-audio 模式（互斥）
-
-| 模式 | 做法 | 适用 |
-|------|------|------|
-| **pro-audio（§2 过渡）** | **`50-kaisa-sof-rt5682-hdmi.conf`** 强制 **`device.profile = pro-audio`** + **IEC958**（**`pactl`/`amixer`**，§4.2） | 快速多路 **`pro-output-*`**、先保证出声 |
-| **UCM（产品目标）** | 安装 **[reference/ucm2/](../../reference/ucm2/README.md)** 至 **`/usr/share/alsa/ucm2/`**（或 **`apt install kaisa-hdmi-pipewire-fix`**），让 **ACP** 按 **JackControl** 暴露路由 | **无 Jack 不误导**、更接近桌面「端口」模型 |
-
-**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若由 deb 安装，见 §4.4 **UCM 优先时**说明），否则 **强制 pro-audio** 仍会盖过 **UCM 的 profile 语义**。改完后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
-
-**验证 UCM 是否生效**：`pactl list cards` 中活动配置宜为 **HiFi** 等 **UCM 定义的 profile**，而非长期锁在 **pro-audio**（以本机 **`pactl`** 为准）。
-
-**UCM 模式下 HDMI 无声（IEC958）**：与 §4.2 相同根因——**`IEC958',N` 仍为 off** 时，界面可选中 **HDMI/DisplayPort** 仍无声音。**请勿** **`pactl set-card-profile … pro-audio`** 做「恢复」，与 UCM 互斥。应：
-
-1. 先用 **`pactl set-default-sink`** 选中外接 HDMI 对应的 **`HiFi__hw_sofrt5682_N__sink`**（或 **`HiFi__hw__0_N__`**，以 **`pactl list short sinks`** 为准）。
-2. 再按 §4.2 打开对应 **`IEC958',N`**（**pcm=2→`IEC958',0`**，**pcm=3/4→`IEC958',1`/`',2`**）。
-
-**Kaisa 实机 sink 名**常为 **`HiFi__hw_sofrt5682_N__sink`**（**`N`** 为 **device** 号，**0**=Port1，**2/3/4**=HDMI），与 **`HiFi__hw__0_N__`** 不同。
-
-若 **`IEC958',N` 已为 on**、默认 sink 已是 HDMI 仍无声：检查 **`wpctl`** 静音/音量（**`wpctl set-mute @DEFAULT_AUDIO_SINK@ 0`**、**`wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0`**）、**物理线是否插在对应 HDMI1/2/3**（与 **`aplay -l`** 里 **device 2/3/4** 一致），以及 **`amixer`** 里 **`HDMI/DP,pcm=N` Jack** 是否为 **on**。
-
-**自动化（未随 deb 提供）**：登录后自动 **`set-card-profile` / `set-default-sink` / 开 IEC958**、以及 **按 Jack 轮询默认 sink** 等，**尚未**在本仓库验证完毕，**`kaisa-hdmi-pipewire-fix` ≥0.3.0** 仅装 **UCM2 + WirePlumber 片段**。若你自行编写 **user systemd**，勿在 **UCM 模式**下执行会强制 **pro-audio** 的命令。**插入 HDMI 时是否弹出输出选择** 由 **桌面/会话** 决定。
-
-### UCM Jack：自动显示/隐藏（安装与验收）
-
-**思路**：UCM2 在 **[`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf)** 为 **HDMI1/2/3** 配置 **`JackControl "HDMI/DP,pcm=N Jack"`** 与 **`IEC958`** 开关序列；WirePlumber 通过 **[`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua)** 对 **`sof-rt5682`** 启用 **`api.alsa.use-ucm`**、**`device.profile = "HiFi"`**（并关闭 **`api.acp.auto-profile`**，避免默认抢 **stereo-fallback**），再开 **`api.acp.auto-port`**，让 ACP 按端口可用性暴露路由（**Jack off 时该 HDMI 不对桌面表现为随意可用**）。
-
-**若安装后只剩模拟/耳机、HDMI 全消失**：先看 **`pactl list cards`** 里 **活动配置** 是否为 **`stereo-fallback`**。若是，说明未切到 UCM 的 **`HiFi`**。请 **`sudo cp` 更新后的 `60-kaisa-ucm.lua`** 并 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**，或手动切 profile：
-
-```bash
-pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
-```
-
-**若 `pactl set-card-profile … HiFi` 报「无此实体」**：多半是 **UCM 未成功加载**（WirePlumber 因此注册不出 `HiFi` profile）。先在终端验证 ALSA 能否解析配置：
-
-```bash
-alsaucm -c sof-rt5682 list _verbs
-```
-
-若出现 **`parse_verb_file` / `no use case device defined`** 等，说明 **`HiFi.conf` 结构不符合 UCM2 要求**（已修正为「顶层 `SectionDevice`」写法）；请 **`git pull`** 后重新执行 **`./scripts/install-kaisa-ucm-overlay.sh`**，再 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
-
-**安装（在仓库根目录，需 sudo）**：
-
-```bash
-./scripts/disable-kaisa-pro-audio-wireplumber.sh          # 禁用强制 pro-audio 片段
-# 若曾在 /etc/wireplumber 装过同类片段：
-# ./scripts/disable-kaisa-pro-audio-wireplumber.sh --system
-
-./scripts/install-kaisa-ucm-overlay.sh                     # UCM -> /usr/share/alsa/ucm2/ ，Lua -> /usr/share/wireplumber/main.lua.d/
-```
-
-**验收**：
-
-1. **`pactl list cards`**：声卡 **活动配置** 为 **`HiFi`**（或 UCM 定义的 profile），**非**长期锁在 **`pro-audio`**。
-2. **`pactl list short sinks`**：出现 **`HiFi__…`** 风格 sink（名称以本机为准）。
-3. **插拔 HDMI**：对应 **`HDMI/DP,pcm=N Jack`** on/off 时，GNOME/ACP 下该路 **显示或不可用**（具体 UI 表现因桌面版本而异；若仅「灰掉/不可用」亦属常见）。
-4. **无声排障**：若 Jack on 仍无声，仍按本文 **ELD / 子设备 / `set_hw_params`** 段落处理；UCM 只管 **Jack 驱动的可用性**，不保证显示器 OSD/ELD 始终一致。
-
-**卸载/回退 UCM overlay**：**`sudo apt install --reinstall alsa-ucm-conf`** 恢复 vendor **`conf.d/sof-rt5682/`**；并 **`sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`** 后重启 **`wireplumber`/`pipewire`**。详见 §4.5。
-
----
-
-## 3. 验证
-
-**本节默认针对 §2「pro-audio 对照」路径**；若已按上文 **「UCM Jack：自动显示/隐藏」** 安装 overlay，**活动配置宜为 `HiFi`**，以该节验收表为准。
-
-```bash
-pactl list cards
-```
-
-**活动配置** 应为 **`pro-audio`**（对照实验时）。
-
-```bash
-pactl get-default-sink
-pactl list short sinks
-```
-
-插入 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
-```
-
-或 **`paplay /usr/share/sounds/alsa/Front_Center.wav`**（同样走当前默认 sink）。
-
-**ALSA 直连**（仅在不与 PipeWire 争用同一路时可用，例如已 **`systemctl --user stop pipewire pipewire-pulse wireplumber`** 的排障会话）：
-
-```bash
-speaker-test -D plughw:0,2 -c2 -t sine -f 440 -l 3
-```
-
----
-
-## 4. 可选与兜底
-
-- **`api.acp.auto-port = true`**：可在 **同一条 `device` 匹配规则** 的 `update-props` 中尝试（与 **`pro-audio`** / UCM 可能交互）；**先备份 conf**，再 A/B。
-- **优先级仍不理想**：可用 **user systemd oneshot**（登录执行 `pactl set-card-profile … pro-audio` + `pactl set-default-sink …`）作次级方案。
-
-### 4.1 重启后又没声
-
-WirePlumber 片段若仍在，常见原因不是 profile 丢失，而是 **GNOME/会话记住了旧的默认 sink**、**冷启动时 HDMI Jack 尚未就绪**、或 **应用仍指向已不存在的 sink**。
-
-**先快速自检：**
-
-```bash
-pactl list cards | grep -E "名称：alsa_card|活动配置"
-pactl get-default-sink
-pactl list short sinks
-```
-
-若 **活动配置** 回到 **`stereo-fallback`**，检查 **`~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`** 是否仍存在，然后：
-
-```bash
-systemctl --user restart wireplumber pipewire pipewire-pulse
-```
-
-若已是 **`pro-audio`** 但仍无声，可 **手动** 设默认 sink 并开 IEC958（卡名、sink 名以本机为准）：
-
-```bash
-pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" pro-audio
-pactl set-default-sink "$(pactl list short sinks | awk '/\\.pro-output-2/ {print $2; exit}')"
-amixer -c0 sset 'IEC958',0 on   # 或按 §4.2 对 pcm=3/4 开 IEC958',1 / ',2
-```
-
-再用 **`speaker-test -D pulse`**（或 **`paplay`**）确认经 PipeWire 的默认 sink 是否有声；**`-D plughw:…`** 在 PipeWire 占用声卡时会出现 **EBUSY (-16)**。
-
-**登录自动执行（可选，自建）**：自行编写 **user systemd** oneshot（**`pactl`/`amixer`**），**`After=pipewire-pulse.service`**，必要时 **`ExecStartPre=/bin/sleep 2`**。仓库 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 仅为示例，**需自备** **`ExecStart`** 所指可执行文件（deb **不**提供）。
-
-### 4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声
-
-**常见原因**
-
-1. **默认 sink 是「粘住」的**：GNOME / 会话会记住 **`pactl get-default-sink`**；WirePlumber 又用 **`priority.session`** 把某一路（示例里是 **`pro-output-2`**）抬成首选。**换线**不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 **`pro-output-3` / `pro-output-4`**。
-2. **出声不一定等于「已切到你心里的那一路」**：声音仍可能从 **当前默认 sink** 对应的那条 **IEC958 / pcm** 出来；若显示器 **多路 HDMI 共用一套喇叭**、或你其实还在听 **模拟口**，会感觉「换口了怎么还有声」。
-3. **画面跟声音可以来自不同逻辑设备**：例如线接到显示器 **HDMI2**，但默认 sink 仍是 **`…pro-output-2`**（逻辑 HDMI1）；部分显示器会把当前选中输入的声音播出来，容易混淆。
-
-**建议自检**
-
-```bash
-pactl get-default-sink
-pactl list short sinks
-pactl list cards
-# 在 cards 输出里看各 HDMI/DP 的 Jack 与 profile，对照 aplay -l 的 pcm 号
-```
-
-**要对齐「物理口 ↔ 默认输出」**：把默认 sink 设到 **Jack=on** 且与当前线一致的那一路，例如（名称以你机器 **`pactl list short sinks`** 为准）：
-
-```bash
-pactl set-default-sink alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-3
-```
-
-**换插后**：请在 **设置 / pavucontrol** 里重选输出，或 **`pactl set-default-sink`**；若你**固定**用机箱某一 HDMI 口，可在 **`50-kaisa-sof-rt5682-hdmi.conf`** 里把该口对应 **`pro-output-N`** 的 **`priority.session`** 调到 **高于 1100**（见 §2 文末说明）。
-
-### 4.2 IEC958 关闭导致「Pulse 正常、HDMI 无声」
-
-若 **`HDMI/DP,pcm=2 Jack` = on**、默认 sink 为 **`pro-output-2`**，仍无声，检查 **数字输出开关**（本机 **pcm=2** 对应 **`IEC958',0` / `IEC958 Playback Switch` numid=14）：
-
-```bash
-amixer -c0 sget 'IEC958',0
-```
-
-若为 **`[off]`**，执行：
-
-```bash
-amixer -c0 sset 'IEC958',0 on
-```
-
-**pcm=3 / pcm=4** 分别对应 **`IEC958',1`**、**`IEC958',2`**（与 **`pro-output-3` / `pro-output-4`** 对齐）。
-
-**IEC958 已为 on、仍无声，且 `journalctl --user -u pipewire` 出现 `spa.alsa: set_hw_params` / `输入/输出错误`、对应 sink `suspended -> error`**：对照 **`aplay -l`**，若该 HDMI **device** 下一行 **`子设备: 0/1`**（**Subdevices: 0/1**）——左侧 **0** 表示 **ALSA 当前无法打开该 device**，与 **IEC958** 无关。可 **换插另一 HDMI 口**、**`systemctl --user restart wireplumber pipewire pipewire-pulse`** 或 **重启**；勿把默认 sink 锁在 **Jack=on 但子设备为 0** 的那一路。
-
-**另见**：若 **`journalctl --user -u wireplumber`** 有 **`Failed to enable ucm device HDMI2`**（或 **HDMI1** / **HDMI3**），且 **`pipewire`** 仅对 **`HiFi__hw_sofrt5682_3__sink`**（或 `_2__` / `_4__`）报错，则为 **UCM SectionDevice 启用失败**（与 **[reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf)** 中 **HDMI1/2/3** 对应 **device 2/3/4** 一致）。宜 **换插到另一 HDMI 物理口** 或 **`alsaucm -c sof-rt5682 set _verb HiFi set _device …`** 单独验证；详见 **[next.md](../../next.md)**（单命令：安装 + 诊断）。
-
-### 4.3 登录自动恢复（规划中）
-
-**根因**：**`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 包（系统级交付，暂缓）
-
-**说明**：在技术验证未收尾前，**不必**关注本节；优先完成 §1–§3、UCM 与基线脚本。**验证稳定后**再决定是否维护 **`debian/`** 与 **`kaisa-hdmi-pipewire-fix`**。
-
-仓库 **`debian/`** 可提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
-
-```bash
-./scripts/build-deb.sh
-```
-
-`dpkg-buildpackage` 默认把 **`.deb` / `.changes` / `.buildinfo`** 写到**上一级目录**；本脚本在构建后把 **`kaisa-hdmi-pipewire-fix_*`** 移回**项目根目录**（与根目录 **`.gitignore`** 中的 `*.deb` 等一致），**`chmod 644`**，并把 **`*_all.deb`** 复制到 **`/tmp/`**（供 **`sudo apt install /tmp/…`**，避免家目录权限导致 **`_apt`** 读包报错）。若需沿用默认行为，仍可直接执行 **`dpkg-buildpackage -us -uc -b`**，再到上级目录取 **`kaisa-hdmi-pipewire-fix_<版本>_all.deb`**。
-
-安装示例（在项目根目录先 **`./scripts/build-deb.sh`**；优先用 **`/tmp`** 副本，避免 **`apt`** / **`_apt`** 无法遍历家目录）：
-
-```bash
-sudo apt install /tmp/kaisa-hdmi-pipewire-fix_0.3.0_all.deb
-```
-
-**包内内容（≥0.3.0：仅配置，无 `/usr/bin` 辅助工具）**：
-
-- **UCM2**：**`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`**、**`/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`**（源码见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)**）；**依赖** **`alsa-ucm-conf`**。
-- **WirePlumber**：**`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`**（**系统级**，与 **`~/.config/...`** 二选一即可，勿重复冲突）。**`apt upgrade`** 安装本包新版本时，若该路径在系统上**不存在**（例如已改名为 **`.disabled`**），dpkg **会再次装入**该文件；走 **UCM** 时，升级后请**再移走**或确认仍为 **`.disabled`**。
-- **文档**：**`/usr/share/doc/kaisa-hdmi-pipewire-fix/`**（**`README.md.gz`** = UCM 说明；可选打包 **OPERATION**）。
-
-**0.2.x 及更早** 曾附带 **`kaisa-restore-*`** 与 user systemd 单元；**0.3.0** 起移除，直至手工验证与自动化策略定型。
-
-**UCM 优先时**：按上文 **「UCM 模式 vs pro-audio 模式」** 移走 **`50-kaisa-…`**，避免与 **强制 pro-audio** 叠用。发布前请改 **`debian/control`**、**`debian/changelog`**、**`debian/copyright`** 中的维护者与许可证说明。
-
-**说明**
-
-- **更广分发**：可将该 deb 放入自建 **APT 仓库 / PPA**；更长远的修复仍是 **ALSA UCM / 上游** 在适用机型上 **默认打开 IEC958**（与发行版/上游沟通，不在本仓库另文维护）。
-
-### 4.5 基线备份与恢复（Ubuntu 默认 / 安装 deb 前状态）
-
-**目的**：在**首次安装** `kaisa-hdmi-pipewire-fix` 或做大改之前，把当前机的音频相关路径与诊断**落盘**，并在后续工作中可**尽量恢复**到该状态。
-
-**为何 `reinstall alsa-ucm-conf`**：本 deb 会向 **`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`** 安装与 **`alsa-ucm-conf` 同路径**的文件，相当于**覆盖**发行版 vendor 配置。`apt purge kaisa-hdmi-pipewire-fix` 会移除本包提供的文件，但**稳妥恢复 vendor 内容**应执行 **`sudo apt install --reinstall alsa-ucm-conf`**（与基线脚本中的 **`system-overlay.tar.gz`** 二选一通常等价）。
-
-**deb 涉及的绝对路径（与 §4.4 一致，便于核对）**
-
-| 路径 | 说明 |
-|------|------|
-| `/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf` | conffile |
-| `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf` | 与 vendor 同路径，purge 后需 reinstall |
-| `/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf` | 本包新增 |
-| （无 **`/usr/bin` 辅助脚本**，≥0.3.0） | 见 §4.4 |
-| `/usr/share/doc/kaisa-hdmi-pipewire-fix/` | 文档（常为 `.gz`） |
-
-**一键采集基线**（默认目录：`audio_topology/baseline-stash/<时间戳>_<hostname>/`，已加入根目录 **`.gitignore`**，避免大块采集误入版本库）：
-
-```bash
-cd /path/to/chromebox_10th_audio_driver
-./scripts/capture-ubuntu-audio-baseline.sh
-```
-
-生成文件通常包括：**`manifest.txt`**（dpkg 状态、上表路径是否存在与 sha256）、**`topology.txt`**（调用 `audio_topology/collect_linux_audio_topology.sh` 的完整输出）、**`system-overlay.tar.gz`**（若存在 vendor **`sof-rt5682.conf`** 则备份）、**`user-wireplumber-conf.tar.gz`**（若 `~/.config/wireplumber/wireplumber.conf.d/` 下已有文件名含 kaisa 的片段）。
-
-**一键恢复**（不传参数时使用 **最近**一次基线目录）：
-
-```bash
-./scripts/restore-ubuntu-audio-baseline.sh
-# 或指定目录：
-./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/
-```
-
-**若曾自建** §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 可出声）”（勿入库）**：
-
-- **当前冻结快照（推荐用于 `./scripts/restore-ubuntu-audio-baseline.sh <目录>`）**  
-  - 基线目录：`audio_topology/baseline-stash/20260408_000644_jack-Kaisa/`  
-  - 采集时间：`2026-04-08T00:06:44+08:00`（以 `manifest.txt` 内 `created_iso` 为准）  
-  - 采集命令：`./scripts/capture-ubuntu-audio-baseline.sh`  
-  - 内容：`manifest.txt`、`topology.txt`、`user-wireplumber-conf.tar.gz`（若存在）等；**目录默认被 `.gitignore` 忽略**，仅在本机磁盘保留  
-- **较早快照（仅供参考）**：`audio_topology/baseline-stash/20260407_235227_jack-Kaisa/`（`2026-04-07T23:52:31+08:00`）
-- **仓库纳入 UCM2 / WirePlumber Lua 源码后的追加采集**：`audio_topology/baseline-stash/20260408_001125_jack-Kaisa/`（`2026-04-08T00:11:25+08:00` 左右，以 `manifest.txt` 为准）。**在系统上执行 `./scripts/install-kaisa-ucm-overlay.sh` 且 `pactl list cards` 已显示 `HiFi` 后**，请再运行一次 **`capture-ubuntu-audio-baseline.sh`**，用新目录作为「UCM 已生效」的黄金快照。
-- 快速锚点（供对照）：`IEC958 numid=14/20/26 = on`；ELD/Jack/默认 sink 等以该基线的 `topology.txt` 与采集时现场为准（建议同时记录 `pactl get-default-sink` 与 `wpctl inspect @DEFAULT_AUDIO_SINK@`）
-
-**本机一次对照（`pro-audio` 下 PipeWire 节点名 ↔ ALSA，以 `wpctl inspect` 为准）**：
-
-- **`…pro-output-0`（Pro）**：对应 **`hw:0,0`** / `aplay` 的 **Port1**，即 **3.5mm 模拟输出**（手动验证可正常出声）。
-- **`…pro-output-2`（Pro 2）**：对应 **`hw:0,2`** / `aplay` 的 **HDMI1**，**`IEC958',0`**（numid **14**）。
-- **`…pro-output-3`（Pro 3）**：对应 **`hw:0,3`** / `aplay` 的 **HDMI2**，**`IEC958',1`**（numid **20**）。
-
-换线、重启或内核/固件变化后，仍以 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 与 **`aplay -l` 子设备**为准，勿死记编号。
-
----
-
-## 5. 参考链接
-
-- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
-- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority)
+两路线 **互斥**。新读者请从 **ProAudio** 文档读起。