# 操作：Kaisa（sof-rt5682）ProAudio + HDMI（WirePlumber 固化）

**主路线**：PipeWire **`pro-audio`**；默认 **`pro-output-0`（模拟）** / **`pro-output-2`（外接 HDMI）**。UCM / HiFi 为 **可选互斥路线**，见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。

**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。

**当前阶段**：以 **本机手工配置 + 文档/脚本复现** 完成技术验证。**本文主路线 = 仅 pro-audio（已验证）**：默认 **模拟用 `pro-output-0`、外接 HDMI（逻辑 HDMI1）用 `pro-output-2`**，下文命令与说明均按此约定撰写，除非另行标注排障分支。**Debian 包**：**当前不做交付与维护**，仅作**未来计划**；仓库内 **`debian/`** 与 **§4.4** 保留为日后若恢复打包时的**存档参考**（**`apply-kaisa-pro-audio.sh` 仍会默认 purge 已装的 `kaisa-hdmi-pipewire-fix`，以免与脚本路线冲突**）。

---

## 核心问题（复盘摘要）

**记录说明**（2026-04）：以下摘要用于 **还原/重装 Ubuntu 后的回归测试** 对照；与 **§4.1b**（`default-profile`）、一键脚本及 **`verify-kaisa-pro-audio`** 一致。

**业务目标**：在 Kaisa + Ubuntu + PipeWire 上让 **HDMI 数字声**稳定可用；主路线为 **`pro-audio` + 正确默认 sink + IEC958**，不依赖桌面偶然选到某一路。

**技术本质**

- **`stereo-fallback` 等默认 profile** 往往只暴露 **极少 sink**，多路 HDMI **不会**都在 **`pactl list short sinks`** 里；**GNOME「输出」项少**常与 **profile/端口可用性**有关，**不等于**栈里只有一路。
- **HDMI 出声**还依赖 **`IEC958`（及对应 Playback Switch）为 on**；PipeWire 侧「在播」仍可能 **显示器无声**。
- **机箱物理口 ↔ `hw:0,N` / `pro-output-N`** 要以 **`aplay -l`、`wpctl inspect`、Jack** 对照，不能死记「HDMI1」等 UCM 展示名（见 **[UCM 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）。

**主路线上的硬冲突（重点）**：WirePlumber **`default-profile` 模块**会把上次选用的 profile 记在 **`~/.local/state/wireplumber/default-profile`**。若其中 **`alsa_card…cml_rt5682_def`** 被存成 **`output:stereo-fallback+input:stereo-fallback`**，**每次启动都会从磁盘恢复**，常 **盖过** **`50-kaisa`** 里 **`monitor.alsa.rules` 设的 `pro-audio`**，表现为 **`pro-output-*` 出现一下又变回 `stereo-fallback`**。对策：**`strip-kaisa-default-profile-state.sh`**（**`apply` 已在重启栈前调用**）+ 再 **`pro-audio`**；细节见 **§4.1b**，**`verify-kaisa-pro-audio.sh`** 会对该脏状态 **FAIL**。

**周边**：**UCM/HiFi** 与 **强制 pro-audio** **互斥**；**deb** 非当前交付；登录后若 **`default-profile` 已干净**仍偶发被改 profile，再用 **`kaisa-reapply-pro-audio-session.sh`**（§4.1b）。

### 恢复 Ubuntu 后重新测试（建议手顺）

1. **大改/重装前**（可选）：在仓库根执行 **`./scripts/capture-ubuntu-audio-baseline.sh`**，便于与 **§4.5** 基线对照。
2. **恢复系统**：按你的方式 **重装 / 还原镜像 / `restore-ubuntu-audio-baseline.sh`**；若曾装 **deb** 或 **UCM overlay**，见 **`remove-kaisa-hdmi-deb.sh`**、**`remove-kaisa-ucm-overlay.sh`**。
3. **登录图形会话后**，在仓库根执行 **`./scripts/apply-kaisa-pro-audio.sh`**（干净机用默认即可；已手动清过包的可 **`--keep-deb`**）。
4. **验收**：**`./scripts/verify-kaisa-pro-audio.sh`**；仍异常时 **`./scripts/verify-kaisa-audio-environment.sh --output /tmp/kaisa-audio-verify.txt`**。
5. **确认无回归**：检查 **`grep cml_rt5682 ~/.local/state/wireplumber/default-profile`** — 不应再出现 **`stereo-fallback`**（应为 **`pro-audio`** 或 **无该行**）。

---

## 主路线：仅 pro-audio（已验证默认）

| 步骤 | 做法 |
|------|------|
| 1. 禁用与 pro-audio **抢 profile** 的 UCM Lua | **`/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`** 若存在，应 **`sudo mv` 为 `60-kaisa-ucm.lua.disabled`**（或删除）。**未禁用则**重启后常见仍为 **HiFi**，与本文不一致。 |
| 2. 安装 WirePlumber 片段 | 将 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)** 复制到 **`~/.config/wireplumber/wireplumber.conf.d/`**（文件名以 **`.conf`** 结尾）。 |
| 3. 重启栈 | **`systemctl --user restart wireplumber pipewire pipewire-pulse`** |
| 4. 卡 profile + 默认 HDMI | **`pactl set-card-profile <卡名> pro-audio`**；**`pactl set-default-sink`** 指到 **`…pro-output-2`**（逻辑 **HDMI1** / **`hw:0,2`**）。 |
| 5. IEC958 | 按 §4.2 打开 **`IEC958',0`**（与 **pcm=2 / pro-output-2** 对齐）。 |
| 6. 试声 | **`speaker-test -D pulse`** / **`paplay`**（见 §3，含 **指定 sink** 写法）。 |

### 一键脚本（应用 + 门禁 + 可选基线）

仓库提供：

| 脚本 | 作用 |
|------|------|
| **[`scripts/apply-kaisa-pro-audio.sh`](../../scripts/apply-kaisa-pro-audio.sh)** | 默认 **purge `kaisa-hdmi-pipewire-fix`** 并 **`apt install --reinstall alsa-ucm-conf`**，禁用 **`60-kaisa-ucm.lua`** 与 **系统级 `50-kaisa*.conf`**，安装用户 **`50-kaisa-sof-rt5682-hdmi.conf`**，重启 PipeWire 栈，**`pactl set-card-profile … pro-audio`**、**默认 `pro-output-2`**，**`IEC958',0/1/2` 全开**，最后运行 **`verify-kaisa-pro-audio.sh`**（不通过则 **exit 1**）。 |
| **[`scripts/remove-kaisa-hdmi-deb.sh`](../../scripts/remove-kaisa-hdmi-deb.sh)** | **仅**卸载历史 **`kaisa-hdmi-pipewire-fix`**（**`apt purge`**）并 **`reinstall alsa-ucm-conf`**；**不**改 WirePlumber、**不**重启栈。曾与 **`install-kaisa-ucm-overlay.sh`** 叠用时，purge 后若仍有 **`/usr/share/alsa/ucm2/GoogleKaisa`**，另跑 **`remove-kaisa-ucm-overlay.sh`**。 |
| **[`scripts/strip-kaisa-default-profile-state.sh`](../../scripts/strip-kaisa-default-profile-state.sh)** | 删除 **`~/.local/state/wireplumber/default-profile`** 里 **cml_rt5682** 行，避免 **stereo-fallback** 持久化顶掉 **`50-kaisa`**；**`apply` 已内置调用**，见 **§4.1b**。 |
| **[`scripts/kaisa-reapply-pro-audio-session.sh`](../../scripts/kaisa-reapply-pro-audio-session.sh)** | 先 **strip 同上**，再 **`pro-audio` + 默认 sink + IEC958**（登录 oneshot）；见 **§4.1b**、**[`kaisa-pro-audio-reapply.service`](systemd-user/kaisa-pro-audio-reapply.service)**。 |
| **[`scripts/verify-kaisa-pro-audio.sh`](../../scripts/verify-kaisa-pro-audio.sh)** | 仅做 **pro-audio 基线门禁**（退出码 **0/1**），可被上手或 CI 单独调用。 |

**常用参数（apply）**

- **`--keep-deb`**：不 purge deb、不 reinstall **`alsa-ucm-conf`**（仅改 WirePlumber / pactl / amixer）。
- **`--verify-only`**：不改动系统，只跑 **`verify-kaisa-pro-audio.sh`**。
- **`--no-verify`**：应用后**不**跑门禁（调试用，不推荐）。
- **`--restore DIR`**：先执行 **`scripts/restore-ubuntu-audio-baseline.sh DIR`**，再继续一键应用。
- **`--restore-only [DIR]`**：只做基线恢复，不应用 pro-audio；**`DIR`** 可省略，若与 **`--restore-stash-substring`** 同用则先解析基线目录。
- **`--restore-stash-substring STR`**：在 **`audio_topology/baseline-stash/*STR*/`** 中选 **最新 mtime** 目录作为 **`DIR`**，用于 **`--restore`** 或 **`--restore-only`**；若同时写了 **`--restore DIR`**，**子串解析在后、会覆盖 `DIR`**。找不到则报错并列出现有目录。

**示例**（在仓库根、**登录用户**图形会话下）：

```bash
./scripts/apply-kaisa-pro-audio.sh
./scripts/apply-kaisa-pro-audio.sh --keep-deb
./scripts/remove-kaisa-hdmi-deb.sh          # 只清历史 deb + reinstall alsa-ucm-conf
./scripts/apply-kaisa-pro-audio.sh --restore-stash-substring 20260406
./scripts/verify-kaisa-pro-audio.sh
```

**门禁未通过**：先看 **`verify-kaisa-pro-audio.sh`** 的 **FAIL** 行；仍不清再跑全量采集：**`./scripts/verify-kaisa-audio-environment.sh --output /tmp/kaisa-audio-verify.txt`**。**PCI 非 `0000:00:1f.3`** 时需先改仓库内 **`50-kaisa-…conf`** 再执行 apply。

**默认 sink 约定（已验证基线）**

- **3.5mm 模拟（Port1）**：**`alsa_output.…cml_rt5682_def.pro-output-0`**
- **外接 HDMI（逻辑 HDMI1）**：**`…pro-output-2`**，对应 **`api.alsa.path = "hw:0,2"`**、**`IEC958',0`**

拔 HDMI 或仅听模拟时，把默认 sink 设回 **`…pro-output-0`** 即可。

**若曾安装 `kaisa-hdmi-pipewire-fix`**：deb 会装 **UCM2** 等；要做**干净 pro-audio**，宜先 **`./scripts/remove-kaisa-hdmi-deb.sh`**（或 **`sudo apt purge kaisa-hdmi-pipewire-fix`** 并 **`sudo apt install --reinstall alsa-ucm-conf`**），再只保留用户级 **`50-kaisa-…conf`**。若 deb 与 **`install-kaisa-ucm-overlay.sh`** 都用过，purge 后仍可能有 **`GoogleKaisa`** 目录，需 **`./scripts/remove-kaisa-ucm-overlay.sh`**。系统 **`alsa-ucm-conf`** 以 **`reinstall`** 后为准；若异常以本机 **`pactl list cards`** 为准。

**可选：UCM / HiFi** 与 **pro-audio 互斥**，见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**；**不要**与上表同时启用。

---

## 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` 的 `priority.session`**：**`pro-output-2`（1100）高于 `pro-output-0`（1000）**，故 **有外接 HDMI 时**倾向默认 sink 为 **HDMI（pro-output-2）**；**拔出或只用模拟**时回退 **`pro-output-0`**（以本机行为为准）。

仓库内 **示例文件**（可复制到上述目录）：

- [`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
```

**优先级（示例文件内，与「默认 0 / 2」一致）**：**`pro-output-0`（模拟）1000**；**`pro-output-2`（HDMI1）1100**（默认外接声道）；`pro-output-3` **1090**；`pro-output-4` **1095**。多路 HDMI 同时存在时 **仍优先逻辑 HDMI1（pro-output-2）**；若你**固定**使用机箱 **HDMI2/3 物理口**，再把对应 **`pro-output-3`/`4`** 的 **`priority.session` 调到高于 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`** 查看与切换。若期望 **插拔与可用性严格对应、并在设置里以「端口」形式出现**，可评估 **UCM / HiFi** 路线（**[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**），而非仅 WirePlumber 静态 pro-audio 规则。

### Ubuntu 默认 GNOME vs 启用 pro-audio 之后（避免误解「抢 profile」）

**未按本文修改 WirePlumber 的 Ubuntu 默认态**：声卡活动配置多为 **`stereo-fallback`**（或等价、仅暴露少量 PCM），**GNOME「设置 → 声音」里通常没有**「声卡配置文件 / profile」切换开关，**输出列表往往只有** 3.5mm 模拟（耳机）等 **一两项**。这是因为 **PipeWire/ACP 未切到 pro-audio、未暴露多路 HDMI**，**不是** GNOME 在「主动抢」一个不存在的 pro-audio——**默认下它一般不会去改你没提供的多 profile。**

**按本文启用 pro-audio 之后**（**`pactl list short sinks`** 已有多条 **`pro-output-*`**）：若再在 **GNOME 设置 → 声音** 里用系统「测试扬声器」或反复切换输出，**有可能** 把该卡 **改回 `stereo-fallback` / HiFi**，界面又缩成「**一个 HDMI + 一个 3.5mm**」之类、**像**「自动隐藏」——**这一阶段**才是 **GUI/会话与 profile 回退** 相关现象；**与出厂只有模拟、无开关** 不是同一种情况。

**自检**：动过设置后立刻 **`pactl list cards | grep 活动配置`**（或 **`Active Profile`**）。若 **已非 `pro-audio`**，再 **`pactl set-card-profile … pro-audio`** 或 **`./scripts/apply-kaisa-pro-audio.sh --keep-deb --no-verify`**。若 **仍是 `pro-audio`** 但界面仍少，以 **`pactl list short sinks`** 为准判断是否仍「全开」，勿仅凭 GNOME 列表条数判断。

### 与「无 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** 驱动路由（**[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**、**[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**）；与 **强制 pro-audio** 互斥，需单独调通 **IEC958**。
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 / HiFi 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md) 或自定义策略**，而不是假定 **单靠 `50-*.conf` 静态片段** 即可覆盖。

### 与 UCM / HiFi（可选，互斥）

- **本文（ProAudio）**：**`50-kaisa-sof-rt5682-hdmi.conf`**，**禁用** **`60-kaisa-ucm.lua`**，默认 **`pro-output-0` / `pro-output-2`**。
- **UCM 路线**：安装 **`60-kaisa-ucm.lua`** 与 UCM2 overlay，并 **移走** **`50-kaisa-…conf`**。

安装、**`HiFi` profile** 验收、**`alsaucm` vs `pactl`** 排障、**卸载 overlay** 见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。

**不要同时使用**：走 UCM 时须移走或禁用 **50-kaisa**（**`~/.config/...`** 与 **`/etc/wireplumber/...`**），然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。迁移前可 **`./scripts/disable-kaisa-pro-audio-wireplumber.sh`**（可选 **`--system`**）。

---

## 3. 验证（仅 pro-audio）

**活动配置** 应为 **`pro-audio`**。若你走 **UCM / HiFi**，本节不适用，验收见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。

```bash
pactl list cards
```

```bash
pactl get-default-sink
pactl list short sinks
```

**默认约定（已验证）**：外接 **HDMI（逻辑 HDMI1）** 时，**`pactl get-default-sink`** 宜为 **`…pro-output-2`**，且 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 中 **`api.alsa.path = "hw:0,2"`**。**仅听模拟** 时宜为 **`…pro-output-0`** / **`hw:0,0`**。

**排障时再核对**：不要仅凭 **`HDMI/DP,pcm=N Jack`** 或某条 **`eld#2.X`** 断定 sink；若 §4.2 中 **`aplay -l`** 该 device 为 **子设备 0/1**，或线缆实际对应 **HDMI2/3**，再依次试 **`pro-output-3` / `pro-output-4`** 及 **`IEC958',1` / `',2`**。

```bash
wpctl inspect @DEFAULT_AUDIO_SINK@ | grep -E 'api\.alsa\.path|node\.name|alsa\.device'
```

**出声测试（推荐）**：PipeWire 占用声卡时 **`speaker-test -D plughw:0,2`** 常 **EBUSY (-16)**，属正常。请经 **Pulse 兼容** 设备测试：

```bash
speaker-test -D pulse -c2 -t sine -f 440 -l 3
```

或 **`paplay /usr/share/sounds/alsa/Front_Center.wav`**（走**当前默认 sink**；默认 HDMI 时应已指向 **`pro-output-2`**）。

**指定某一路输出（不改默认 sink）**（`SINK` 取自 **`pactl list short sinks`** 第二列）：

```bash
paplay -d "$SINK" /usr/share/sounds/alsa/Front_Center.wav
# 例：默认验证 HDMI1
paplay -d alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
  /usr/share/sounds/alsa/Front_Center.wav
```

```bash
pw-play --target alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
  /usr/share/sounds/alsa/Front_Center.wav
```

```bash
PULSE_SINK=alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
  speaker-test -D pulse -c2 -t sine -f 440 -l 3
```

**若 `paplay` 报「排空流失败：超时」、且 `pactl list short sink-inputs` 为空**：该路 sink 可能未能正常完成播放。请 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或 §4.2 子设备正常时的 **3/4**），打开对应 **IEC958**，并用 **`speaker-test -D pipewire`** 复测；同时 **`journalctl --user -u pipewire`** 查 **`set_hw_params` / 输入输出错误**。

**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 片段若仍在，常见原因不是片段被删，而是 **活动配置被改回 `stereo-fallback` / HiFi**（多因 **GNOME 设置里操作** 触发，见上节「Ubuntu 默认 GNOME vs 启用 pro-audio 之后」）、**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 名以本机为准）。**已验证默认**：HDMI 用 **`pro-output-2`** + **`IEC958',0`**；仅模拟用 **`pro-output-0`**（无需 IEC958）。

```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   # 默认 HDMI1；若走 HDMI2/3 见 §4.2 开 IEC958',1 / ',2
```

再用 **`speaker-test -D pulse`**（或 **`paplay`**）确认经 PipeWire 的默认 sink 是否有声；**`-D plughw:…`** 在 PipeWire 占用声卡时会出现 **EBUSY (-16)**。

### 4.1b 启动后出现过 pro-audio / 多路输出，随后又自动消失

**首要根因（WirePlumber 0.4 常见）**：会话管理器会把「上次选用的声卡 profile」记在 **`~/.local/state/wireplumber/default-profile`**。若其中对 **`alsa_card…cml_rt5682_def`** 存的是 **`output:stereo-fallback+input:stereo-fallback`**，则 **每次启动 WirePlumber 时会从磁盘恢复该 profile**，往往在 **`50-kaisa` 的 `monitor.alsa.rules` 生效之后仍把卡改回 `stereo-fallback`**，于是 **`pactl list short sinks`** 只剩 **`…stereo-fallback`**，**`pro-output-*` 像「出现一下又没了」**。

**当场核对**：

```bash
grep cml_rt5682 ~/.local/state/wireplumber/default-profile 2>/dev/null || echo "(无该行)"
pactl list cards | grep -E "cml_rt5682|活动配置|Active Profile"
```

**处理**（任选其一）：

1. **一键清状态 + 重载栈**（推荐）：重新执行 **`./scripts/apply-kaisa-pro-audio.sh`**（其中会在 **重启 PipeWire 栈之前** 调用 **`strip-kaisa-default-profile-state.sh`** 删掉上述持久行）。  
2. **仅清持久行**：**[`scripts/strip-kaisa-default-profile-state.sh`](../../scripts/strip-kaisa-default-profile-state.sh)**，然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**，再按 §4.1 手动 **`pactl set-card-profile … pro-audio`**。  
3. **手工删行**：编辑 **`~/.local/state/wireplumber/default-profile`**，删掉 **含 `cml_rt5682` 的那一行**，再重启用户栈。

**门禁**：**`verify-kaisa-pro-audio.sh`** 若发现 **`default-profile` 里仍是 `cml_rt5682` + `stereo-fallback`** 会直接 **FAIL**，避免误以为基线已稳。

**次要因素**：**GNOME 设置** 在登录后数秒内也可能再 **`set-card-profile`**。在 **已清掉 `default-profile` 脏数据** 之后，若仍偶发，再用登录 **oneshot** 拉两次 profile：

| 文件 | 作用 |
|------|------|
| **[`scripts/kaisa-reapply-pro-audio-session.sh`](../../scripts/kaisa-reapply-pro-audio-session.sh)** | 先 **清 `default-profile` 中 cml_rt5682 行**，再 **`pro-audio` / 默认 sink / IEC958**；约 **6 秒后再执行一遍**。 |
| **[`systemd-user/kaisa-pro-audio-reapply.service`](systemd-user/kaisa-pro-audio-reapply.service)** | **user** oneshot；**`ExecStart=%h/.local/bin/kaisa-reapply-pro-audio-session.sh`**（安装见文件头注释）。 |

**登录自动执行（旧示例）**：[**`systemd-user/kaisa-hdmi-iec958-pipewire.service`**](systemd-user/kaisa-hdmi-iec958-pipewire.service) 仍为占位示例（**需自备** **`ExecStart`**）。**优先**上表 **`kaisa-pro-audio-reapply.service`**。

### 4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声

**常见原因**

1. **默认 sink 是「粘住」的**：在 **已有多路 sink** 的前提下，GNOME / 会话会记住 **`pactl get-default-sink`**；WirePlumber 又用 **`priority.session`** 把某一路（示例里是 **`pro-output-2`**）抬成首选。**换线**不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 **`pro-output-3` / `pro-output-4`**。（**默认 Ubuntu 只有一路模拟输出** 时，不存在这种「多 sink 之间粘住」的问题，那是 **未改栈** 时的单一输出模型。）
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** 的那一路。

**另见（UCM 模式）**：若处于 **HiFi / UCM** 且 **`journalctl --user -u wireplumber`** 出现 **`Failed to enable ucm device HDMI*`**，见 **[UCM 文档 §4.4](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 与 **[`next.md`](../../next.md)**。纯 **pro-audio** 排障仍以 **`aplay -l` 子设备** 与上文为主。

### 4.3 登录自动恢复（规划中）

**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 的**发行级**自动化**尚未**定型（**deb 不作为当前交付**，见文首与 §4.4）。

**当前**：请用 §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 包（未来计划；当前不维护）

**现状**：主线交付为 **`scripts/apply-kaisa-pro-audio.sh`** + 用户级 **`50-kaisa-…conf`**，**不**以 deb 为发布形态；**本节及以下安装/打包说明不作为当前工作项**，仅保留给**将来**若重新启用 **`kaisa-hdmi-pipewire-fix`** 时对照。**若本机曾装过该 deb、只想先卸掉**：**[`scripts/remove-kaisa-hdmi-deb.sh`](../../scripts/remove-kaisa-hdmi-deb.sh)**（`purge` + **`reinstall alsa-ucm-conf`**）。

仓库 **`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 说明；可选打包 **ProAudio / UCM 操作文档**）。

**0.2.x 及更早** 曾附带 **`kaisa-restore-*`** 与 user systemd 单元；**0.3.0** 起移除，直至手工验证与自动化策略定型。

**UCM 优先时**：按 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 移走 **`50-kaisa-…`**，避免与 **强制 pro-audio** 叠用。若**未来**恢复 deb 打包，再维护 **`debian/control`**、**`changelog`**、**`copyright`** 等元数据。

**说明**

- **更广分发**：可将该 deb 放入自建 **APT 仓库 / PPA**；更长远的修复仍是 **ALSA UCM / 上游** 在适用机型上 **默认打开 IEC958**（与发行版/上游沟通，不在本仓库另文维护）。

### 4.5 基线备份与恢复（Ubuntu 默认 / 大改前）

**目的**：在**做大改**、安装/卸载 **UCM overlay**、或机器上**曾存在**历史 deb **`kaisa-hdmi-pipewire-fix`** 等情况下，把当前机的音频相关路径与诊断**落盘**，并在后续工作中可**尽量恢复**到该状态。

**为何 `reinstall alsa-ucm-conf`**：若曾通过 deb 或手工 overlay 向 **`/usr/share/alsa/ucm2/conf.d/sof-rt5682/`** 写入与 **`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
```

**一键环境验证（排障前）**：**`./scripts/verify-kaisa-audio-environment.sh`** 在同一会话里汇总 PCI、**`/proc/asound`**、**`aplay`**、**`alsaucm`**、已安装 UCM/Lua、**`pactl`/`wpctl`**、**`amixer`（IEC958/Jack）**、HDMI **ELD**、**`dmesg`** 与 **pipewire/wireplumber** 用户日志片段，末尾输出自动摘要；可选 **`--output FILE`** 保存完整报告。与上文「基线采集」不同：本脚本**不**写入 **`audio_topology/baseline-stash/`**，侧重一次性核对当前机状态。**若用 `sudo ./scripts/verify-…` 跑**：脚本会经 **`sudo -u $SUDO_USER`** 调用 **`pactl`** 与 **`journalctl --user`**（root 进程不能直接占用普通用户的 **`XDG_RUNTIME_DIR`**）；用户 **`~/.config/wireplumber`** 亦按 **`$SUDO_USER` 的家目录** 扫描，避免误读 **`/root/.config`**。

生成文件通常包括：**`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_PipeWire_Kaisa_ProAudio.md`** / **`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`** / **`REPRO_*.md`**、WirePlumber 源码；在文档中**写一句**当时验证要点（例如 **`pro-audio` + 默认 **`pro-output-0`/`pro-output-2`**、`hw:0,2`）。**`debian/`**：**未来计划**，当前**不**作为常规维护项 | **是** |

**建议在 ProAudio / UCM 文档或提交说明里记一行「事实锚点」**（便于以后对照）：`pactl get-default-sink` 的 sink 名、**`wpctl inspect @DEFAULT_AUDIO_SINK@`** 中的 **`api.alsa.path`**、以及 **`amixer -c0 cget numid=14,20,26`** 中对应 **IEC958** 是否为 on。

**本机最新一次技术验证快照（勿入库）**（主路线为 **pro-audio**，默认 **pro-output-0 / pro-output-2**；含历史上 **Pro 3** 等对照时以 `topology.txt` 为准）：

- **当前冻结快照（推荐用于 `./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)