jack/chromebox_10th_audio_driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 新增 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
This commit is contained in:
jack
2026-04-08 11:07:13 +08:00
parent 5c7d0aa360
commit 17f0a4521f
29 changed files with 1505 additions and 427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@@ -1,16 +1,17 @@
# chromebox_10th_audio_driver # chromebox_10th_audio_driver
Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**交付：仓库主线为 **`pro-audio` + IEC958 + WirePlumber 片段**（及可选 **UCM2**），与 **`kaisa-hdmi-pipewire-fix` deb**。**自编内核 / SOF 诊断补丁**与 **`kernel-src/` 大目录**已不随仓库提供；若要做 **ChromiumOS ↔ HWE** 源码对照，在本机 **`apt source linux-hwe-6.17`** 后对两棵树自行 **`diff -u`** / **`diff -rq`**（**`chromiumos_kernel/v5.15`** 与解压的 `linux-hwe-6.17-*`）。 Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**交付：仓库主线为 **`pro-audio` + IEC958 + WirePlumber 用户级片段**（及可选 **UCM2 overlay 脚本**）。**`kaisa-hdmi-pipewire-fix` deb 不作为当前交付**，仅作未来计划（见 [ProAudio §4.4](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) 存档）。**自编内核 / SOF 诊断补丁**与 **`kernel-src/` 大目录**已不随仓库提供；若要做 **ChromiumOS ↔ HWE** 源码对照，在本机 **`apt source linux-hwe-6.17`** 后对两棵树自行 **`diff -u`** / **`diff -rq`**（**`chromiumos_kernel/v5.15`** 与解压的 `linux-hwe-6.17-*`）。
## 文档（仅保留已实机验证路线） ## 文档（仅保留已实机验证路线）
| 你想… | 打开 | | 你想… | 打开 |
| ----- | ---- | | ----- | ---- |
| **操作与排障**（WirePlumber、`50-kaisa-…`、deb、基线脚本） | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | | **操作与排障（pro-audio 主路线）** | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)（文内 **「核心问题」**、**恢复 Ubuntu 后重测**） |
| **deb 手顺与验收** | [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | | **UCM / HiFi（可选）** | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) |
| **deb 手顺（存档，未来计划）** | [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) |
| 速查下一步 | [next.md](next.md) | | 速查下一步 | [next.md](next.md) |
| 全仓库路径与脚本表 | [REPO_INDEX.md](REPO_INDEX.md) | | 全仓库路径与脚本表 | [REPO_INDEX.md](REPO_INDEX.md) |
| UCM2 源码（打入 deb） | [reference/ucm2/README.md](reference/ucm2/README.md) | | UCM2 源码（overlay / 曾拟打入 deb） | [reference/ucm2/README.md](reference/ucm2/README.md) |
| 拓扑采集脚本 | [audio_topology/COLLECT.md](audio_topology/COLLECT.md) | | 拓扑采集脚本 | [audio_topology/COLLECT.md](audio_topology/COLLECT.md) |
| BMad 菜单码 | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) | | BMad 菜单码 | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) |
| 产品需求（若仍用 BMad） | [_bmad-output/planning-artifacts/prd.md](_bmad-output/planning-artifacts/prd.md) | | 产品需求（若仍用 BMad） | [_bmad-output/planning-artifacts/prd.md](_bmad-output/planning-artifacts/prd.md) |
@@ -25,12 +26,15 @@ Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**
|------|------|-------| |------|------|-------|
| Linux（本仓库目标） | 需 **pro-audio profile** + 正确 **IEC958** / 默认 sink；**`stereo-fallback` 常仅一路** | 一般有（以本机 `aplay -L` 为准） | | Linux（本仓库目标） | 需 **pro-audio profile** + 正确 **IEC958** / 默认 sink；**`stereo-fallback` 常仅一路** | 一般有（以本机 `aplay -L` 为准） |
细节以 **OPERATION** 为准。 细节以 **[ProAudio 文档](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)** 为准。
--- ---
## 速链 ## 速链
- **基线**：`scripts/capture-ubuntu-audio-baseline.sh`（装 deb / 大改前）、`scripts/restore-ubuntu-audio-baseline.sh`（回滚）— [OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5。 - **基线**：`scripts/capture-ubuntu-audio-baseline.sh`（大改前 / 曾用 overlay 或历史 deb 时）、`scripts/restore-ubuntu-audio-baseline.sh`（回滚）— [ProAudio 文档](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) §4.5。
- **打 deb**：`debian/` + `scripts/build-deb.sh`（**≥0.3.0** 包内为 **UCM2 + WirePlumber 片段**，无随包 shell 工具）。 - **一键 pro-audio**：`scripts/apply-kaisa-pro-audio.sh`（默认 purge 已装的 `kaisa-hdmi-pipewire-fix` + 应用 + `verify-kaisa-pro-audio.sh` 门禁）；仅校验：`scripts/verify-kaisa-pro-audio.sh` — 见 [ProAudio「一键脚本」](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)。
- **只卸历史 deb**：`scripts/remove-kaisa-hdmi-deb.sh`（`apt purge kaisa-hdmi-pipewire-fix` + `reinstall alsa-ucm-conf`，不改 WirePlumber）。
- **登录后 pro-audio 被顶掉**：多为 **`~/.local/state/wireplumber/default-profile`** 里持久了 **stereo-fallback**；`scripts/strip-kaisa-default-profile-state.sh` 或重跑 **`apply-kaisa-pro-audio.sh`**。仍偶发再用 `scripts/kaisa-reapply-pro-audio-session.sh` / [§4.1b](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)。
- **打 deb（未来计划）**：`debian/` + `scripts/build-deb.sh` 仅作存档，**当前不维护发布**；见 [ProAudio §4.4](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)。
- 原始拓扑与 dmesg：`audio_topology/collected/`（`baseline-stash/` 见 `.gitignore`）。 - 原始拓扑与 dmesg：`audio_topology/collected/`（`baseline-stash/` 见 `.gitignore`）。

15
REPO_INDEX.md
View File

@@ -17,8 +17,9 @@
| 文件 | 说明 | | 文件 | 说明 |
| ---- | ---- | | ---- | ---- |
| [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | PipeWire / deb / 基线 | | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **核心问题复盘**、pro-audio、`default-profile`、恢复 Ubuntu 重测、基线（deb §4.4 存档） |
| [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](./docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 验收手顺 | | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | 可选 UCM / HiFi |
| [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](./docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 手顺存档（未来计划） |
## [`audio_topology/`](./audio_topology/) ## [`audio_topology/`](./audio_topology/)
@@ -32,13 +33,17 @@
| 脚本 | 说明 | | 脚本 | 说明 |
| ---- | ---- | | ---- | ---- |
| [capture-ubuntu-audio-baseline.sh](./scripts/capture-ubuntu-audio-baseline.sh) | 安装 deb / 大改前采集系统音频基线 | | [capture-ubuntu-audio-baseline.sh](./scripts/capture-ubuntu-audio-baseline.sh) | 大改前 / overlay 或历史 deb 后采集系统音频基线 |
| [restore-ubuntu-audio-baseline.sh](./scripts/restore-ubuntu-audio-baseline.sh) | 恢复到某次基线 | | [restore-ubuntu-audio-baseline.sh](./scripts/restore-ubuntu-audio-baseline.sh) | 恢复到某次基线 |
| [build-deb.sh](./scripts/build-deb.sh) | 生成 `kaisa-hdmi-pipewire-fix_*.deb`（**≥0.3.0** 仅 **UCM2 + WirePlumber**，无 `/usr/bin` 辅助脚本） | | [remove-kaisa-hdmi-deb.sh](./scripts/remove-kaisa-hdmi-deb.sh) | **purge `kaisa-hdmi-pipewire-fix`** + **reinstall `alsa-ucm-conf`**（仅清 deb，不改 WirePlumber） |
| [apply-kaisa-pro-audio.sh](./scripts/apply-kaisa-pro-audio.sh) / [verify-kaisa-pro-audio.sh](./scripts/verify-kaisa-pro-audio.sh) | 一键 pro-audio / 门禁 |
| [strip-kaisa-default-profile-state.sh](./scripts/strip-kaisa-default-profile-state.sh) | 去掉 WirePlumber `default-profile` 里 cml_rt5682 的 stereo-fallback 持久行 |
| [kaisa-reapply-pro-audio-session.sh](./scripts/kaisa-reapply-pro-audio-session.sh) | strip + 再拉 pro-audio（见 ProAudio §4.1b） |
| [build-deb.sh](./scripts/build-deb.sh) | 生成 `kaisa-hdmi-pipewire-fix_*.deb`（**未来计划**，当前不维护发布；若不存在见 ProAudio §4.4） |
BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad/scripts/render_bmad_help_zh_cn.py) → 根目录 `bmad-help.zh-CN.md`。 BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad/scripts/render_bmad_help_zh_cn.py) → 根目录 `bmad-help.zh-CN.md`。
## [`debian/`](./debian/) ## [`debian/`](./debian/)（deb 打包草稿，**未来计划**，当前不维护）
`kaisa-hdmi-pipewire-fix` 包定义与安装文件。 `kaisa-hdmi-pipewire-fix` 包定义与安装文件。

4
_bmad-output/planning-artifacts/epics.md
View File

@@ -90,7 +90,7 @@ workflowType: epics
- **Given** 仓库根已克隆 - **Given** 仓库根已克隆
- **When** 打开 `docs/INDEX.md` - **When** 打开 `docs/INDEX.md`
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_HDMI.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目 - **Then** 存在指向 `OPERATION_PipeWire_Kaisa_ProAudio.md`、`OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目
### Story 1.2：（已收敛）路线图 ### Story 1.2：（已收敛）路线图
@@ -125,7 +125,7 @@ workflowType: epics
### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动 ### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动
作为一名 **Kaisa 用户**， 作为一名 **Kaisa 用户**，
我希望 **OPERATION_PipeWire_Kaisa_HDMI.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**， 我希望 **OPERATION_PipeWire_Kaisa_ProAudio.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**，
以便 **排障不靠口口相传**（**FR5**）。 以便 **排障不靠口口相传**（**FR5**）。
**验收标准：** **验收标准：**

19
_bmad-output/planning-artifacts/prd.md
View File

@@ -4,7 +4,8 @@ stepsCompleted:
inputDocuments: inputDocuments:
- README.md - README.md
- docs/INDEX.md - docs/INDEX.md
- docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md - docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
- docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
- docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md - docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
workflowType: prd workflowType: prd
brownfield_synthesis: true brownfield_synthesis: true
@@ -18,7 +19,7 @@ last_edited: '2026-04-06'
**日期：** 2026-04-06 **日期：** 2026-04-06
**状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4） **状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4）
**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md**、**OPERATION_PipeWire_Kaisa_HDMI.md**、**REPRO_Kaisa_Deb_ProAudio_Manual.md** 为准。下文仍出现旧路径处视为历史表述。 **2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md**、**OPERATION_PipeWire_Kaisa_ProAudio.md**、**OPERATION_PipeWire_Kaisa_UCM_HiFi.md**、**REPRO_Kaisa_Deb_ProAudio_Manual.md** 为准。旧名 **OPERATION_PipeWire_Kaisa_HDMI.md** 仅为重定向 stub。
--- ---
@@ -63,7 +64,7 @@ last_edited: '2026-04-06'
| 角色 | 目标 | 主要触点 | | 角色 | 目标 | 主要触点 |
|------|------|----------| |------|------|----------|
| **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） | | **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） |
| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_HDMI.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 | | **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_ProAudio.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 |
| **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） | | **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） |
--- ---
@@ -88,8 +89,8 @@ last_edited: '2026-04-06'
| ID | 能力 | 验收要点 | | ID | 能力 | 验收要点 |
|----|------|----------| |----|------|----------|
| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 | | **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 |
| **FR2** | **Linux HDMI 技术路线** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 pro-audio / UCM / deb；**REPRO** 为验收手顺。 | | **FR2** | **Linux HDMI 技术路线** | **ProAudio / UCM 文档** 覆盖 pro-audio、UCM、deb；**REPRO** 为验收手顺。 |
| **FR5** | **桌面 HDMI 操作说明** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 | | **FR5** | **桌面 HDMI 操作说明** | **ProAudio 文档** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 |
| **FR6** | **登录自动修复（Kaisa）** | **OPERATION §4.3**：**user systemd** 示例 + 手顺；**deb ≥0.3.0** 不随包提供可执行工具。 | | **FR6** | **登录自动修复（Kaisa）** | **OPERATION §4.3**：**user systemd** 示例 + 手顺；**deb ≥0.3.0** 不随包提供可执行工具。 |
| **FR7** | **WirePlumber 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 | | **FR7** | **WirePlumber 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 |
| **FR8** | **对照与导出** | **ChromeOS ↔ Ubuntu**：本机两树 **`diff`**；可选输出至 **`reference/chromeos-ubuntu-sound-diffs/`**（见该目录 README）。 | | **FR8** | **对照与导出** | **ChromeOS ↔ Ubuntu**：本机两树 **`diff`**；可选输出至 **`reference/chromeos-ubuntu-sound-diffs/`**（见该目录 README）。 |
@@ -103,9 +104,10 @@ last_edited: '2026-04-06'
```bash ```bash
test -f docs/INDEX.md test -f docs/INDEX.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
grep -q 'OPERATION_PipeWire_Kaisa_HDMI' docs/INDEX.md grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
``` ```
--- ---
@@ -144,7 +146,8 @@ grep -q 'OPERATION_PipeWire_Kaisa_HDMI' docs/INDEX.md
## 10. 参考（仓库内） ## 10. 参考（仓库内）
- [docs/INDEX.md](../../docs/INDEX.md) - [docs/INDEX.md](../../docs/INDEX.md)
- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) - [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)
- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)
- [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](../../docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) - [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](../../docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)
- [README.md](../../README.md) - [README.md](../../README.md)

2
audio_topology/COLLECT.md
View File

@@ -31,4 +31,4 @@ sudo ./audio_topology/collect_linux_audio_topology.sh /path/to/output.txt
## 与当前维护文档的关系 ## 与当前维护文档的关系
排查 HDMI 用户态路由以 **[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)** 为准；本目录采集为**辅助证据**，不替代该操作文档。 排查 HDMI 用户态路由以 **[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)**（及可选 **[UCM 文档](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）为准；本目录采集为**辅助证据**，不替代操作文档。

2
audio_topology/collect_linux_audio_topology.sh
View File

@@ -151,7 +151,7 @@ dmesg 2>/dev/null | grep -iE 'snd|hda|audio|codec|hdmi' >> "$OUTPUT" || echo "(
echo "\`\`\`" >> "$OUTPUT" echo "\`\`\`" >> "$OUTPUT"
echo "" >> "$OUTPUT" echo "" >> "$OUTPUT"
# --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md）--- # --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md）---
section "SOF / HDMI / IPC 基线 (dmesg)" section "SOF / HDMI / IPC 基线 (dmesg)"
echo "# dmesg | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120" >> "$OUTPUT" echo "# dmesg | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120" >> "$OUTPUT"
echo "# 用于对照 SOF/IPC 与 dmesg；建议 sudo 运行本脚本以读全量 dmesg" >> "$OUTPUT" echo "# 用于对照 SOF/IPC 与 dmesg；建议 sudo 运行本脚本以读全量 dmesg" >> "$OUTPUT"

11
debian/control vendored
View File

@@ -16,10 +16,11 @@ Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences, GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences,
and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink
priorities). Does not ship helper binaries or user systemd units yet — priorities). Does not ship helper binaries or user systemd units yet —
use manual pactl/amixer steps in OPERATION until automated restore is ready. use manual pactl/amixer steps in upstream docs (ProAudio / UCM) until
UCM-first and pro-audio WirePlumber are mutually exclusive — see automated restore is ready. UCM-first and pro-audio WirePlumber are mutually
/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION. exclusive — see /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and
docs in the source tree: OPERATION_PipeWire_Kaisa_ProAudio.md,
OPERATION_PipeWire_Kaisa_UCM_HiFi.md.
. .
PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
/etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in /etc/wireplumber/ if needed.
/usr/share/doc/.

11
debian/kaisa-hdmi-pipewire-fix/DEBIAN/control vendored
View File

@@ -12,10 +12,11 @@ Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences, GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences,
and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink
priorities). Does not ship helper binaries or user systemd units yet — priorities). Does not ship helper binaries or user systemd units yet —
use manual pactl/amixer steps in OPERATION until automated restore is ready. use manual pactl/amixer steps in upstream docs (ProAudio / UCM) until
UCM-first and pro-audio WirePlumber are mutually exclusive — see automated restore is ready. UCM-first and pro-audio WirePlumber are mutually
/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION. exclusive — see /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and
docs in the source tree: OPERATION_PipeWire_Kaisa_ProAudio.md,
OPERATION_PipeWire_Kaisa_UCM_HiFi.md.
. .
PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
/etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in /etc/wireplumber/ if needed.
/usr/share/doc/.

4
debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md vendored
View File

@@ -1,6 +1,6 @@
# Kaisa UCM2 overlay（`sof-rt5682`） # Kaisa UCM2 overlay（`sof-rt5682`）
本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。 本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见源码树 **[UCM 操作文档](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 与 **[ProAudio](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)**）。
## 布局 ## 布局
@@ -9,7 +9,7 @@
| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` | | `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` |
| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** | | `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** |
上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。 上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与源码树 [UCM / ProAudio 文档](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) 中互斥说明一致）。
## 手工安装（调试） ## 手工安装（调试）

8
docs/INDEX.md
View File

@@ -4,6 +4,10 @@
| 文档 | 说明 | | 文档 | 说明 |
| ---- | ---- | | ---- | ---- |
| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | 主操作文档 | | [linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **主路线**：**「核心问题」复盘**、pro-audio、`50-kaisa`、**default-profile**、IEC958、一键脚本、**恢复 Ubuntu 后重测**（**deb 见 §4.4**） |
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 复现与验收 | | [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **可选**：UCM2、HiFi、`60-kaisa-ucm.lua`（与 pro-audio 互斥） |
| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | 旧文件名重定向（上表两篇取代） |
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 手顺**存档**（未来计划） |
| [README.md](README.md) | 本目录说明 | | [README.md](README.md) | 本目录说明 |
**脚本（仓库根 `scripts/`）**：一键 pro-audio — [`apply-kaisa-pro-audio.sh`](../scripts/apply-kaisa-pro-audio.sh)；登录后再拉 pro-audio — [`kaisa-reapply-pro-audio-session.sh`](../scripts/kaisa-reapply-pro-audio-session.sh)（[ProAudio §4.1b](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)）；卸历史 deb — [`remove-kaisa-hdmi-deb.sh`](../scripts/remove-kaisa-hdmi-deb.sh)；门禁 — [`verify-kaisa-pro-audio.sh`](../scripts/verify-kaisa-pro-audio.sh)。

7
docs/README.md
View File

@@ -1,11 +1,12 @@
# `docs/` 说明 # `docs/` 说明
本目录仅保留 **已实机验证** 的 PipeWire / deb 技术路线： 本目录保留 **已实机验证** 的 PipeWire 主路线；**deb 不作为当前交付**（仅未来计划存档）。
| 文档 | 内容 | | 文档 | 内容 |
| ---- | ---- | | ---- | ---- |
| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | WirePlumber、`50-kaisa-sof-rt5682-hdmi.conf`、pro-audio / UCM、deb、基线采集 | | [linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **主路线**：**核心问题复盘**、**default-profile**、pro-audio、`50-kaisa`、一键脚本、**恢复 Ubuntu 重测**、基线 |
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 安装与手动验收 | | [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **可选**：UCM2、HiFi（与 pro-audio 互斥） |
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 手顺**存档**（未来若恢复打包时对照） |
附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。 附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。

375
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
View File

@@ -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`**。 | | **[`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 存档**） |
| **长期「无 Jack 不误导」、桌面端口模型** | **UCM**：安装 overlay 后 **移走** 上述 WirePlumber 片段，依赖 WirePlumber 按 UCM 启用 **`HDMI1/2/3`**；与 pro-audio **互斥**（见下 §2.3）。 | | **[`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 已能出声** 之后再做。 两路线 **互斥**。新读者请从 **ProAudio** 文档读起。
**若已安装 `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)

448
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md Normal file
View File

@@ -0,0 +1,448 @@
# 操作：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)

127
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md Normal file
View File

@@ -0,0 +1,127 @@
# 操作：Kaisa（sof-rt5682）UCM2 + HiFi（可选路线）
**适用**：与 **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** 相同机型（Google **Kaisa**、PipeWire + WirePlumber、**`sof-rt5682`**）。
**本文定位**：在需要 **Jack 驱动端口可用性**、**桌面「端口」模型**（未插线的 HDMI 尽量不表现为随意可选输出）时，使用 **ALSA UCM2** + PipeWire **HiFi** profile，配合 WirePlumber **`60-kaisa-ucm.lua`**。**与强制 pro-audio 的 `50-kaisa-sof-rt5682-hdmi.conf` 互斥**，勿与 ProAudio 主路线同时启用。
**相关**：UCM 源码与目录说明见 **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**；**IEC958 / `aplay -l` 子设备 / 直连 ALSA 试声** 等通用排障与 **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md) §4.2** 一致，下文仅补充 **HiFi sink 名** 与 **UCM 特有** 现象。
---
## 1. pro-audio 与 UCM 二选一
| 路线 | 做法 | 适用 |
|------|------|------|
| **pro-audio（主路线）** | **`50-kaisa-sof-rt5682-hdmi.conf`** + **禁用 `60-kaisa-ucm.lua`**；默认 **`pro-output-0` / `pro-output-2`** | 多路 **`pro-output-*`**、已验证基线，见 **[ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md)** |
| **UCM / HiFi（本文）** | **`./scripts/install-kaisa-ucm-overlay.sh`**；**移走** **`50-kaisa-…conf`**（历史 **`kaisa-hdmi-pipewire-fix` deb** 若曾安装，见 [ProAudio §4.4](OPERATION_PipeWire_Kaisa_ProAudio.md) **存档**，**当前不维护 deb**） | **Jack 驱动端口**、更接近桌面对「无效口」的处理 |
**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若机器上仍有历史 deb 装入的片段，见 **[ProAudio §4.4](OPERATION_PipeWire_Kaisa_ProAudio.md)** 路径表）。改完后：
```bash
systemctl --user restart wireplumber pipewire pipewire-pulse
```
从 **pro-audio 迁到 UCM** 前，可运行 **`./scripts/disable-kaisa-pro-audio-wireplumber.sh`**（及可选 **`--system`**）统一禁用 pro-audio 片段。
---
## 2. 验证 UCM 是否在 PipeWire 侧生效
先看 **`pactl list cards`** 的 **「配置文件」** 是否已列出 **`HiFi:`**；若已列出，**活动配置** 宜为 **`HiFi`**，而非长期锁在 **pro-audio**。
若 **`alsaucm -c sof-rt5682 list _verbs` 有 HiFi** 而 **`pactl list cards` 始终没有 `HiFi:`**，说明 **ALSA UCM 可读** 但 **ACP 未注册该 profile**，见下文 **§4 排障**（以本机 **`pactl`** 为准）。
仅在 **`pactl list cards`** 已出现 **`HiFi:`** 时，才可手动切 profile（卡名以 **`pactl list cards short`** 第二列为准）：
```bash
pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
```
**等价（按整数 profile 序号）**：**`wpctl status`** → **Audio → Devices** 找到 **`sof-rt5682`** 的 **Device id**，再 **`wpctl set-profile <id> <INDEX>`**（**`0` = off**；若仅 **off + pro-audio**，则 **pro-audio** 一般为 **`1`**）。勿用 **MIDI** 等其它对象的 id。
---
## 3. HiFi 下 HDMI 无声（IEC958）
与 **[ProAudio §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md)** 根因相同：**`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. 再打开对应 **`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**。
**自动化**：登录后自动 **`set-card-profile` / `set-default-sink` / 开 IEC958** 等**尚未**作为稳定随包工具；若自写 **user systemd**，**勿在 UCM 模式**下执行会强制 **pro-audio** 的命令。**插入 HDMI 时是否弹出输出选择** 由 **桌面/会话** 决定。
---
## 4. 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`**。
### 4.1 `alsaucm` 与 `pactl` 不是同一层验收
**`alsaucm -c sof-rt5682 list _verbs` 能列出 `HiFi`**，只说明 **ALSA UCM 配置可被解析**；**PipeWire 是否把该 verb 注册成声卡「配置文件」**，要看 **`pactl list cards`** 里 **「配置文件：」** 下列出的 **名称**（例如 **`off:`**、**`pro-audio:`**、**`HiFi:`**）。若此处 **只有 `off` 与 `pro-audio`、没有 `HiFi:`**，则 **`pactl set-card-profile … HiFi`** 会失败（**「无效参数」** / **「无此实体」**），因为 **对 PipeWire 而言不存在名为 `HiFi` 的 card profile**。
**若 `alsaucm` 正常而 `pactl list cards` 始终没有 `HiFi` profile`**：属于 **spa-acp 未把 UCM HiFi 暴露为 PipeWire 卡配置**。请：
```bash
journalctl --user -u pipewire -u wireplumber -b --no-pager | grep -iE 'ucm|acp|alsa'
```
并确认 **`api.alsa.use-ucm = true`**（**`wpctl inspect <device_id>`** 可见）。在此之前，**不要用 `set-card-profile … HiFi` 做硬验收**。
若 **`alsaucm`** 侧就报错，再查 UCM 文件：
```bash
alsaucm -c sof-rt5682 list _verbs
```
若出现 **`parse_verb_file` / `no use case device defined`** 等，说明 **`HiFi.conf` 结构不符合 UCM2 要求**；请 **`git pull`** 后重新执行 **`./scripts/install-kaisa-ucm-overlay.sh`**，再 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
### 4.2 安装（在仓库根目录，需 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/
```
### 4.3 验收清单
1. **`pactl list cards`**：**「配置文件」** 中若已列出 **`HiFi:`**，则 **活动配置** 宜为 **`HiFi`**；若 **仅有 `off` / `pro-audio`**，则 **尚未** 将 UCM **`HiFi`** 注册为 PipeWire profile，**勿**强行要求 **`set-card-profile … HiFi`** 成功。
2. **`pactl list short sinks`**：在 **HiFi profile 已存在** 时，宜出现 **`HiFi__…`** 风格 sink；若卡上只有 **pro-audio**，则常见 **`pro-output-*`**（与 UCM Jack 语义不同）。
3. **插拔 HDMI**：对应 **`HDMI/DP,pcm=N Jack`** on/off 时，GNOME/ACP 下该路 **显示或不可用**（因桌面版本而异）。
4. **无声排障**：Jack on 仍无声时，仍按 **[ProAudio 文档 §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md)**（**ELD / 子设备 / `set_hw_params`**）；UCM 只管 **Jack 驱动的可用性**。
### 4.4 PipeWire 日志中的 UCM 设备失败
若 **`journalctl --user -u wireplumber`** 有 **`Failed to enable ucm device HDMI2`**（或 **HDMI1** / **HDMI3**），且 **`pipewire`** 仅对某 **`HiFi__hw_sofrt5682_N__sink`** 报错，则为 **UCM SectionDevice 启用失败**（与 **`HiFi.conf`** 中 **HDMI1/2/3** 对应 **device 2/3/4** 一致）。宜 **换插另一 HDMI 物理口** 或 **`alsaucm -c sof-rt5682 set _verb HiFi set _device …`** 单独验证；详见 **[`next.md`](../../next.md)**。
---
## 5. 卸载 / 回退 UCM overlay
```bash
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
sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua.disabled # 若曾改名保留
```
然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。若需回到 **pro-audio**，按 **[ProAudio 文档](OPERATION_PipeWire_Kaisa_ProAudio.md)** 重新启用 **`50-kaisa-sof-rt5682-hdmi.conf`** 并禁用 **`60-kaisa-ucm.lua`**。
**deb 存档路径、基线采集与恢复** 见 **[ProAudio §4.4–§4.5](OPERATION_PipeWire_Kaisa_ProAudio.md)**（**deb 不作为当前交付**）。
---
## 6. 参考链接
- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
- **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**

20
docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
View File

@@ -1,8 +1,10 @@
# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现） # 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现）
**目的**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」，用于打包前验收。 **状态（当前）**：**不作为维护中的交付路径**；仓库**放弃 deb 工作**，仅作**未来计划**。本文与下文「打包前」表述保留为**存档**，便于日后若恢复 **`kaisa-hdmi-pipewire-fix`** 时对照。日常请直接用 **`scripts/apply-kaisa-pro-audio.sh`**（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md)）。
**相关**：deb 安装内容见 [OPERATION_PipeWire_Kaisa_HDMI.md](OPERATION_PipeWire_Kaisa_HDMI.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。 **目的（存档）**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按曾拟定的 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」。
**相关**：deb 存档见 [OPERATION_PipeWire_Kaisa_ProAudio.md](OPERATION_PipeWire_Kaisa_ProAudio.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。UCM 见 [OPERATION_PipeWire_Kaisa_UCM_HiFi.md](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)。
### 常用检查（sinks / 设备，不依赖 pulseaudio-utils） ### 常用检查（sinks / 设备，不依赖 pulseaudio-utils）
@@ -59,7 +61,7 @@ cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
~/.config/wireplumber/wireplumber.conf.d/ ~/.config/wireplumber/wireplumber.conf.d/
``` ```
若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [OPERATION](OPERATION_PipeWire_Kaisa_HDMI.md) §2）。 若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md) §2）。
--- ---
@@ -109,7 +111,7 @@ pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-au
**说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。 **说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。
**GUI 试声后 Pro sinks 消失**：在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出时，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」。属 **Pro-audio 与桌面会话抢 profile** 的常见现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 OPERATION §2「测试扬声器」说明）。 **GUI 试声后 Pro sinks 消失**：（**先分清阶段**：**出厂/默认 Ubuntu** 往往只有 3.5mm 等模拟、设置里 **无 profile 开关**，那是 **栈未暴露 pro-audio**，**不是**「GNOME 在抢 pro-audio」。）在 **已经** 执行过 **`pactl set-card-profile … pro-audio`** 且 **`pactl list short sinks`** 已有多条 **`pro-output-*`** 之后，若在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」——属 **已启用 pro-audio 后** GUI 触发 **profile 回退** 的现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 [ProAudio §2–§3](OPERATION_PipeWire_Kaisa_ProAudio.md) 与 **「Ubuntu 默认 GNOME vs 启用 pro-audio 之后」**）。
- **PCI 路径不同**的机器：用 `pactl list cards short` 第二列**实际卡名**替换上面长名。 - **PCI 路径不同**的机器：用 `pactl list cards short` 第二列**实际卡名**替换上面长名。
- **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。 - **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。
@@ -119,9 +121,9 @@ pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-au
## 4. 默认 sink + IEC958 ## 4. 默认 sink + IEC958
**≥0.3.0** 的 deb **不**包含 **`kaisa-restore-pipewire-hdmi`**。请在本机用 **`pactl`**（需 **`pulseaudio-utils`**）完成与 §3 同源的 profile 切换，再 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应 **`pro-output-N`**），并按 [OPERATION §4.2](OPERATION_PipeWire_Kaisa_HDMI.md) 打开对应 **`IEC958',N`**。 **≥0.3.0** 的 deb **不**包含 **`kaisa-restore-pipewire-hdmi`**。请在本机用 **`pactl`**（需 **`pulseaudio-utils`**）完成与 §3 同源的 profile 切换，再 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应 **`pro-output-N`**），并按 [ProAudio §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md) 打开对应 **`IEC958',N`**。
若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 OPERATION §4.1），再 **`amixer`** 开 IEC958。 若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 [ProAudio §4.1](OPERATION_PipeWire_Kaisa_ProAudio.md)），再 **`amixer`** 开 IEC958。
--- ---
@@ -148,8 +150,10 @@ pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-au
--- ---
## 7. deb 打包前建议 ## 7. deb 打包前建议（存档；当前不执行）
若**未来**恢复 **`kaisa-hdmi-pipewire-fix`** 打包，可参考：
1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。 1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。
2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。 2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。
3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 OPERATION「互斥」一致）。 3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 [UCM 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)「互斥」一致）。

26
docs/linux-hdmi/systemd-user/kaisa-pro-audio-reapply.service Normal file
View File

@@ -0,0 +1,26 @@
# 登录会话：在 pipewire-pulse 就绪后延迟重施 pro-audio，缓解「启动后出现一下又消失」
# （多为 GNOME/会话稍晚把卡改回 HiFi 或 stereo-fallback）。
#
# 安装（示例：脚本放到 ~/.local/bin，避免 unit 里写死仓库路径）：
# mkdir -p ~/.local/bin
# ln -sf /path/to/chromebox_10th_audio_driver/scripts/kaisa-reapply-pro-audio-session.sh ~/.local/bin/
# mkdir -p ~/.config/systemd/user
# cp docs/linux-hdmi/systemd-user/kaisa-pro-audio-reapply.service ~/.config/systemd/user/
# systemctl --user daemon-reload
# systemctl --user enable --now kaisa-pro-audio-reapply.service
#
# 与仓库示例 kaisa-hdmi-iec958-pipewire.service 二选一即可；本 unit 自带可执行路径（~/.local/bin）。
[Unit]
Description=Kaisa: re-apply PipeWire pro-audio after login (mitigate profile revert)
After=pipewire-pulse.service
Wants=pipewire-pulse.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStartPre=/bin/sleep 2
ExecStart=%h/.local/bin/kaisa-reapply-pro-audio-session.sh
[Install]
WantedBy=default.target

2
help.md
View File

@@ -57,7 +57,7 @@
### 本仓库当前产品目标（Kaisa 桌面音频） ### 本仓库当前产品目标（Kaisa 桌面音频）
**权威操作与交付**（PipeWire / pro-audio / deb / UCM）：**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)**、**[reference/ucm2/README.md](reference/ucm2/README.md)**。 **权威操作与交付**：**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)**（pro-audio 主路线）、**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**（可选 UCM）、**[reference/ucm2/README.md](reference/ucm2/README.md)**。
在此目标下，BMad 更偏 **棕地攻关 + 文档/交付对齐**。常用下一步： 在此目标下，BMad 更偏 **棕地攻关 + 文档/交付对齐**。常用下一步：

6
next.md
View File

@@ -1,9 +1,9 @@
# next # next
[docs/README.md](docs/README.md) · [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) · [reference/ucm2/README.md](reference/ucm2/README.md) [docs/README.md](docs/README.md) · [OPERATION_PipeWire_Kaisa_ProAudio.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) · [OPERATION_PipeWire_Kaisa_UCM_HiFi.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) · [reference/ucm2/README.md](reference/ucm2/README.md)
- **安装 deb 前基线 / 事后恢复**：[scripts/capture-ubuntu-audio-baseline.sh](scripts/capture-ubuntu-audio-baseline.sh) · [scripts/restore-ubuntu-audio-baseline.sh](scripts/restore-ubuntu-audio-baseline.sh)（详见 [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5）。 - **安装 deb 前基线 / 事后恢复**：[scripts/capture-ubuntu-audio-baseline.sh](scripts/capture-ubuntu-audio-baseline.sh) · [scripts/restore-ubuntu-audio-baseline.sh](scripts/restore-ubuntu-audio-baseline.sh)（详见 [ProAudio 文档](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) §4.5）。
- **pro-audio / UCM / deb 手顺**：[OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)（§2 起）；与 deb 等价的可复现验收：[REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)。 - **pro-audio / deb 手顺**：[ProAudio](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)；**UCM / HiFi**：[UCM 文档](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)；与 deb 等价的可复现验收：[REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)。
```bash ```bash
cd /path/to/chromebox_10th_audio_driver cd /path/to/chromebox_10th_audio_driver

6
reference/ucm2/README.md
View File

@@ -1,6 +1,6 @@
# Kaisa UCM2 overlay（`sof-rt5682`） # Kaisa UCM2 overlay（`sof-rt5682`）
本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。 本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 **[UCM 操作文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 与 **[ProAudio 文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)**）。
## 布局 ## 布局
@@ -9,7 +9,7 @@
| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` | | `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` |
| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** | | `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** |
上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。 上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与 **本 overlay 或历史 deb 路径** 可能冲突 — 优先 **合并上游** 或 **改名/拆包**（与 [UCM / ProAudio 文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) 中互斥说明一致；**deb 当前不作为交付**，见 [ProAudio §4.4](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)）。
## 手工安装（调试） ## 手工安装（调试）
@@ -46,6 +46,8 @@ alsaucm -c sof-rt5682 set _verb HiFi list _devices
插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。 插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。
**一次跑完（推荐）**：在仓库根目录执行 **`./scripts/verify-kaisa-audio-environment.sh`**（可选 **`--output ~/kaisa-audio-verify.txt`**），覆盖硬件枚举、UCM、PipeWire、WirePlumber 与摘要；详见 [ProAudio 文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)「一键环境验证」。
## 实机验收表（勾选） ## 实机验收表（勾选）
| 步骤 | 预期 | | 步骤 | 预期 |

240
scripts/apply-kaisa-pro-audio.sh Executable file
View File

@@ -0,0 +1,240 @@
#!/usr/bin/env bash
# 一键应用 Kaisa pro-audio 基线（见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md）。
# deb 不作为当前交付（见 ProAudio §4.4 存档）；默认仍会 purge 已装的 kaisa-hdmi-pipewire-fix，避免历史安装与脚本路线冲突。
# 默认：purge kaisa-hdmi-pipewire-fix、reinstall alsa-ucm-conf、禁用 60-kaisa-ucm.lua、
# 禁用系统级 50-kaisa*.conf、安装用户 50-kaisa、重启 PipeWire 栈、pactl + IEC958、跑 verify-kaisa-pro-audio.sh。
#
# 用法（仓库根，登录用户图形/会话）：
# ./scripts/apply-kaisa-pro-audio.sh
# ./scripts/apply-kaisa-pro-audio.sh --keep-deb
# ./scripts/apply-kaisa-pro-audio.sh --verify-only
# ./scripts/apply-kaisa-pro-audio.sh --restore-only /path/to/baseline-stash/...
# ./scripts/apply-kaisa-pro-audio.sh --restore /path/to/baseline-stash/...
# ./scripts/apply-kaisa-pro-audio.sh --restore-stash-substring 20260406
# ./scripts/apply-kaisa-pro-audio.sh --no-verify
#
# 若只想卸载历史 deb（purge + reinstall alsa-ucm-conf）、不跑整套 apply：
# ./scripts/remove-kaisa-hdmi-deb.sh
#
# 需要：sudo、systemctl --user、pactl、amixer；建议 pulseaudio-utils。
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
VERIFY_SH="${REPO_ROOT}/scripts/verify-kaisa-pro-audio.sh"
RESTORE_SH="${REPO_ROOT}/scripts/restore-ubuntu-audio-baseline.sh"
CONF_SRC="${REPO_ROOT}/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf"
KEEP_DEB=0
VERIFY_ONLY=0
NO_VERIFY=0
RESTORE_DIR=""
RESTORE_ONLY=0
RESTORE_SUBSTR=""
resolve_stash_substring() {
local sub="$1"
local base="${REPO_ROOT}/audio_topology/baseline-stash"
if [[ ! -d "$base" ]]; then
echo "apply-kaisa-pro-audio: 无目录 $base（请先 capture-ubuntu-audio-baseline.sh）" >&2
exit 1
fi
local matches=()
shopt -s nullglob
for d in "$base"/*"${sub}"*/; do
[[ -d "$d" ]] || continue
matches+=("$d")
done
shopt -u nullglob
if ((${#matches[@]} == 0)); then
echo "apply-kaisa-pro-audio: 未找到基线目录名含「${sub}」于 $base" >&2
echo "现有目录:" >&2
ls -la "$base" 2>/dev/null | head -20 >&2 || true
exit 1
fi
local latest
latest="$(ls -td "${matches[@]}" | head -1)"
realpath "$latest"
}
usage() {
sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'
exit "${1:-0}"
}
while [[ $# -gt 0 ]]; do
case "$1" in
--keep-deb) KEEP_DEB=1 ;;
--verify-only) VERIFY_ONLY=1 ;;
--no-verify) NO_VERIFY=1 ;;
--restore-only)
RESTORE_ONLY=1
if [[ -n "${2:-}" && "${2:0:1}" != - ]]; then
RESTORE_DIR="$2"
shift
fi
;;
--restore)
RESTORE_DIR="${2:?--restore 需要目录参数}"
shift
;;
--restore-stash-substring)
RESTORE_SUBSTR="${2:?--restore-stash-substring 需要子串，如 20260406}"
shift
;;
-h|--help) usage 0 ;;
*)
echo "未知参数: $1" >&2
usage 1
;;
esac
shift
done
if [[ "$VERIFY_ONLY" -eq 1 ]]; then
exec "$VERIFY_SH"
fi
if [[ -n "$RESTORE_SUBSTR" ]]; then
RESTORE_DIR="$(resolve_stash_substring "$RESTORE_SUBSTR")"
echo ">>> 解析基线目录: $RESTORE_DIR"
fi
if [[ "$RESTORE_ONLY" -eq 1 && -z "$RESTORE_DIR" ]]; then
echo "apply-kaisa-pro-audio: --restore-only 需要目录参数，或与 --restore-stash-substring 同用。" >&2
exit 1
fi
if [[ $EUID -eq 0 && -z "${SUDO_USER:-}" ]]; then
echo "apply-kaisa-pro-audio: 请勿以 root 直接运行（无法正确操作 user pipewire）。请用登录用户执行。" >&2
exit 1
fi
if [[ ! -f "$CONF_SRC" ]]; then
echo "apply-kaisa-pro-audio: 缺少仓库 conf: $CONF_SRC" >&2
exit 1
fi
if ! command -v sudo &>/dev/null; then
echo "apply-kaisa-pro-audio: 需要 sudo。" >&2
exit 1
fi
# pactl 前缀：root+sudo 时代理会话用户
PACTL_PREFIX=()
if [[ $EUID -eq 0 && -n "${SUDO_USER:-}" ]] && id -u "$SUDO_USER" &>/dev/null; then
_VU="$(id -u "$SUDO_USER")"
if [[ -d "/run/user/${_VU}" ]]; then
_VH="$(getent passwd "$SUDO_USER" | cut -d: -f6)"
_VH="${_VH:-/home/$SUDO_USER}"
PACTL_PREFIX=(sudo -u "$SUDO_USER" env XDG_RUNTIME_DIR="/run/user/${_VU}" HOME="$_VH")
fi
fi
run_pactl() { "${PACTL_PREFIX[@]}" pactl "$@"; }
restart_audio_stack() {
if ((${#PACTL_PREFIX[@]})); then
sudo -u "${SUDO_USER}" env XDG_RUNTIME_DIR="/run/user/$(id -u "$SUDO_USER")" \
systemctl --user restart wireplumber pipewire pipewire-pulse
else
systemctl --user restart wireplumber pipewire pipewire-pulse
fi
}
if [[ -n "$RESTORE_DIR" ]]; then
echo ">>> 执行基线恢复: $RESTORE_SH $RESTORE_DIR"
"$RESTORE_SH" "$RESTORE_DIR"
if [[ "$RESTORE_ONLY" -eq 1 ]]; then
echo ">>> --restore-only：已恢复，跳过 pro-audio 应用。"
exit 0
fi
fi
if [[ "$KEEP_DEB" -eq 0 ]]; then
if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
echo ">>> apt purge -y kaisa-hdmi-pipewire-fix"
sudo apt purge -y kaisa-hdmi-pipewire-fix
else
echo "(未安装 kaisa-hdmi-pipewire-fix，跳过 purge)"
fi
echo ">>> apt install --reinstall -y alsa-ucm-conf"
sudo apt install --reinstall -y alsa-ucm-conf
else
echo "(--keep-deb：跳过 purge / reinstall alsa-ucm-conf)"
fi
LUA="/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua"
if [[ -f "$LUA" ]]; then
echo ">>> sudo mv $LUA -> ${LUA}.disabled"
sudo mv -n -- "$LUA" "${LUA}.disabled"
else
echo "(无激活的 $LUA，跳过)"
fi
if [[ -d /etc/wireplumber/wireplumber.conf.d ]]; then
echo ">>> 禁用系统级 50-kaisa*.conf（避免与用户级重复）"
sudo bash -c '
shopt -s nullglob
for f in /etc/wireplumber/wireplumber.conf.d/50-kaisa*.conf; do
[[ -f "$f" ]] || continue
t="${f}.disabled"
[[ -e "$t" ]] && t="${f}.disabled.$(date +%s)"
echo "mv $f -> $t"
mv -n -- "$f" "$t"
done
'
fi
USER_CONF_DIR="${HOME}/.config/wireplumber/wireplumber.conf.d"
mkdir -p "$USER_CONF_DIR"
echo ">>> cp $CONF_SRC -> $USER_CONF_DIR/50-kaisa-sof-rt5682-hdmi.conf"
cp -f -- "$CONF_SRC" "$USER_CONF_DIR/50-kaisa-sof-rt5682-hdmi.conf"
echo ">>> strip-kaisa-default-profile-state（避免 WirePlumber 从 default-profile 恢复 stereo-fallback）"
"$REPO_ROOT/scripts/strip-kaisa-default-profile-state.sh" || true
if systemctl --user is-system-running &>/dev/null; then
echo ">>> systemctl --user restart wireplumber pipewire pipewire-pulse"
restart_audio_stack
sleep 2
else
echo "apply-kaisa-pro-audio: 警告：user systemd 会话不可用，请登录桌面后手动: systemctl --user restart wireplumber pipewire pipewire-pulse" >&2
fi
if ! command -v pactl &>/dev/null; then
echo "apply-kaisa-pro-audio: 未找到 pactl，无法 set-card-profile。请安装 pulseaudio-utils 后重试。" >&2
exit 1
fi
CARD="$(run_pactl list cards short 2>/dev/null | awk '/cml_rt5682/ {print $2; exit}')" || true
if [[ -z "$CARD" ]]; then
echo "apply-kaisa-pro-audio: 无法从 pactl list cards short 解析 cml_rt5682 卡名（PCI 是否与 conf 中 pci-0000_00_1f.3 一致？）" >&2
exit 1
fi
echo ">>> pactl set-card-profile $CARD pro-audio"
run_pactl set-card-profile "$CARD" pro-audio
SINK="$(run_pactl list short sinks 2>/dev/null | awk '/cml_rt5682/ && /\.pro-output-2/ {print $2; exit}')" || true
if [[ -z "$SINK" ]]; then
echo "apply-kaisa-pro-audio: 未找到 …pro-output-2 sink；请核对 profile 是否已为 pro-audio。" >&2
exit 1
fi
echo ">>> pactl set-default-sink $SINK"
run_pactl set-default-sink "$SINK"
echo ">>> amixer IEC958 0/1/2 on"
amixer -c0 sset 'IEC958',0 on
amixer -c0 sset 'IEC958',1 on
amixer -c0 sset 'IEC958',2 on
if [[ "$NO_VERIFY" -eq 1 ]]; then
echo ">>> --no-verify：跳过门禁（不推荐）。"
exit 0
fi
echo ">>> $VERIFY_SH"
if ! "$VERIFY_SH"; then
echo "" >&2
echo "apply-kaisa-pro-audio: 门禁未通过。可查看上文，或运行: $REPO_ROOT/scripts/verify-kaisa-audio-environment.sh --output /tmp/kaisa-verify.txt" >&2
exit 1
fi
echo "apply-kaisa-pro-audio: 完成。"

2
scripts/capture-ubuntu-audio-baseline.sh
View File

@@ -2,7 +2,7 @@
# 在安装 kaisa-hdmi-pipewire-fix 或其它大改前，采集「Ubuntu / 当前机」音频基线并落盘。 # 在安装 kaisa-hdmi-pipewire-fix 或其它大改前，采集「Ubuntu / 当前机」音频基线并落盘。
# 输出目录默认：audio_topology/baseline-stash/<时间戳>_<hostname>/ # 输出目录默认：audio_topology/baseline-stash/<时间戳>_<hostname>/
# 用法：./scripts/capture-ubuntu-audio-baseline.sh [输出目录] # 用法：./scripts/capture-ubuntu-audio-baseline.sh [输出目录]
# 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md「基线备份与恢复」 # 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md「基线备份与恢复」
set -euo pipefail set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

2
scripts/disable-kaisa-pro-audio-wireplumber.sh
View File

@@ -62,4 +62,4 @@ else
echo "（无 user systemd 会话，请登录桌面后手动执行 restart）" >&2 echo "（无 user systemd 会话，请登录桌面后手动执行 restart）" >&2
fi fi
echo "完成。随后请安装 UCM overlay 与 wireplumber/main.lua.d/60-kaisa-ucm.lua（见 OPERATION）。" echo "完成。随后请安装 UCM overlay 与 wireplumber/main.lua.d/60-kaisa-ucm.lua（见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md）。"

3
scripts/install-kaisa-ucm-overlay.sh
View File

@@ -2,6 +2,7 @@
# 将仓库内 UCM2 overlay 与 WirePlumber Lua 安装到系统路径（需 sudo）。 # 将仓库内 UCM2 overlay 与 WirePlumber Lua 安装到系统路径（需 sudo）。
# 用法：在仓库根目录执行 ./scripts/install-kaisa-ucm-overlay.sh # 用法：在仓库根目录执行 ./scripts/install-kaisa-ucm-overlay.sh
# 安装前请先运行 ./scripts/disable-kaisa-pro-audio-wireplumber.sh # 安装前请先运行 ./scripts/disable-kaisa-pro-audio-wireplumber.sh
# 卸载同路径 overlay：./scripts/remove-kaisa-ucm-overlay.sh
set -euo pipefail set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -32,4 +33,4 @@ fi
echo "完成。请先验证 UCM 能解析（应列出 HiFi，不应报 parse 错误）：" echo "完成。请先验证 UCM 能解析（应列出 HiFi，不应报 parse 错误）："
echo " alsaucm -c sof-rt5682 list _verbs" echo " alsaucm -c sof-rt5682 list _verbs"
echo "再按 OPERATION「UCM Jack 自动显示/隐藏」验收 pactl / GNOME。" echo "再按 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md 验收 pactl / GNOME。"

51
scripts/kaisa-reapply-pro-audio-session.sh Executable file
View File

@@ -0,0 +1,51 @@
#!/usr/bin/env bash
# 在用户会话里把 cml_rt5682 拉回 pro-audio + 默认 pro-output-2 + IEC958。
# 用于：开机/登录后 profile 变回 stereo-fallback，导致 pro-output-*「出现又消失」。
# 根因常为 ~/.local/state/wireplumber/default-profile 里持久了 stereo-fallback（见 strip-kaisa-default-profile-state.sh）。
# 可重复执行；建议由 systemd --user oneshot 在 pipewire-pulse 之后延迟调用（见 systemd-user/kaisa-pro-audio-reapply.service）。
set -euo pipefail
# 与 strip-kaisa-default-profile-state.sh 同逻辑（本脚本常被单独 symlink 到 ~/.local/bin，勿依赖同目录 strip）
_wp_state="${HOME}/.local/state/wireplumber/default-profile"
if [[ -f "$_wp_state" ]] && grep -q 'cml_rt5682' "$_wp_state" 2>/dev/null; then
_tmp="${_wp_state}.tmp.$$"
grep -v 'cml_rt5682' "$_wp_state" > "$_tmp"
mv -f -- "$_tmp" "$_wp_state"
echo "kaisa-reapply-pro-audio-session: 已清除 default-profile 中含 cml_rt5682 的持久行" >&2
fi
if ! command -v pactl &>/dev/null; then
echo "kaisa-reapply-pro-audio-session: 未找到 pactl" >&2
exit 1
fi
apply_once() {
local card sink
card="$(pactl list cards short 2>/dev/null | awk '/cml_rt5682/ {print $2; exit}')" || true
[[ -z "$card" ]] && return 1
pactl set-card-profile "$card" pro-audio 2>/dev/null || true
# 给 WirePlumber 一点时间生成 sink
sleep 0.4
sink="$(pactl list short sinks 2>/dev/null | awk '/cml_rt5682/ && /\.pro-output-2/ {print $2; exit}')" || true
[[ -n "$sink" ]] && pactl set-default-sink "$sink" 2>/dev/null || true
if command -v amixer &>/dev/null; then
amixer -c0 sset 'IEC958',0 on 2>/dev/null || true
amixer -c0 sset 'IEC958',1 on 2>/dev/null || true
amixer -c0 sset 'IEC958',2 on 2>/dev/null || true
fi
return 0
}
# 首次：栈可能尚未完全就绪
for _ in 1 2 3 4 5 6 7 8 9 10; do
if apply_once; then
# 再等一会：GNOME 常在登录后数秒内改 profile，第二次拉回去
sleep 6
apply_once || true
exit 0
fi
sleep 1
done
echo "kaisa-reapply-pro-audio-session: 超时未找到 cml_rt5682 卡（pactl list cards short）" >&2
exit 1

52
scripts/remove-kaisa-hdmi-deb.sh Executable file
View File

@@ -0,0 +1,52 @@
#!/usr/bin/env bash
# 卸载历史上可能安装过的 kaisa-hdmi-pipewire-fix（apt purge），并 reinstall alsa-ucm-conf
# 以恢复发行版自带的 UCM 文件（与 apply-kaisa-pro-audio.sh 中 KEEP_DEB=0 时前两步一致）。
#
# 不改动用户级 WirePlumber；不自动重启 PipeWire。若曾用手工 UCM overlay，另见
# ./scripts/remove-kaisa-ucm-overlay.sh
# 若要走 pro-audio 主路线，purge 完成后可执行：
# ./scripts/apply-kaisa-pro-audio.sh --keep-deb
#
# 用法：
# ./scripts/remove-kaisa-hdmi-deb.sh
# ./scripts/remove-kaisa-hdmi-deb.sh --no-reinstall-ucm # 仅 purge，不 touch alsa-ucm-conf
set -euo pipefail
NO_REINSTALL=0
while [[ $# -gt 0 ]]; do
case "$1" in
--no-reinstall-ucm) NO_REINSTALL=1 ;;
-h|--help)
sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'
exit 0
;;
*)
echo "未知参数: $1（用 --help）" >&2
exit 1
;;
esac
shift
done
if ! command -v sudo &>/dev/null; then
echo "需要 sudo。" >&2
exit 1
fi
if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
echo ">>> apt purge -y kaisa-hdmi-pipewire-fix"
sudo apt purge -y kaisa-hdmi-pipewire-fix
else
echo "(dpkg 无已登记包 kaisa-hdmi-pipewire-fix，跳过 purge；若曾改名安装请自行 apt purge 包名)"
fi
if [[ "$NO_REINSTALL" -eq 0 ]]; then
echo ">>> apt install --reinstall -y alsa-ucm-conf"
sudo apt install --reinstall -y alsa-ucm-conf
else
echo "(--no-reinstall-ucm：跳过 alsa-ucm-conf reinstall)"
fi
echo "remove-kaisa-hdmi-deb: 完成。建议登录用户会话下: systemctl --user restart wireplumber pipewire pipewire-pulse"
echo "若仍有手工 UCM: ./scripts/remove-kaisa-ucm-overlay.sh"
echo "若应用 pro-audio: ./scripts/apply-kaisa-pro-audio.sh --keep-deb"

55
scripts/remove-kaisa-ucm-overlay.sh Executable file
View File

@@ -0,0 +1,55 @@
#!/usr/bin/env bash
# 卸载本仓库安装的 Kaisa UCM2 overlay 与系统级 60-kaisa-ucm.lua（需 sudo）。
# 不卸载 alsa-ucm-conf 整包；仅删除 install-kaisa-ucm-overlay.sh 写入的路径。
# 用法：在仓库根目录执行 ./scripts/remove-kaisa-ucm-overlay.sh
# 卸载后若走 pro-audio，请再执行 ./scripts/apply-kaisa-pro-audio.sh
set -euo pipefail
if ! command -v sudo &>/dev/null; then
echo "需要 sudo。" >&2
exit 1
fi
removed=0
echo ">>> 删除 /usr/share/alsa/ucm2/GoogleKaisa/（若存在）"
if [[ -d /usr/share/alsa/ucm2/GoogleKaisa ]]; then
sudo rm -rf -- /usr/share/alsa/ucm2/GoogleKaisa
removed=1
echo " 已删除。"
else
echo " （不存在，跳过）"
fi
echo ">>> 删除 /usr/share/alsa/ucm2/conf.d/sof-rt5682/（若存在）"
if [[ -d /usr/share/alsa/ucm2/conf.d/sof-rt5682 ]]; then
sudo rm -rf -- /usr/share/alsa/ucm2/conf.d/sof-rt5682
removed=1
echo " 已删除。"
else
echo " （不存在，跳过）"
fi
LUA="/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua"
echo ">>> 禁用 $LUA（若存在）"
if [[ -f "$LUA" ]]; then
sudo mv -n -- "$LUA" "${LUA}.disabled"
removed=1
echo " 已移至 ${LUA}.disabled"
elif [[ -f "${LUA}.disabled" ]]; then
echo " （已是 .disabled，跳过）"
else
echo " （不存在，跳过）"
fi
if systemctl --user is-system-running &>/dev/null; then
echo ">>> systemctl --user restart wireplumber pipewire pipewire-pulse"
systemctl --user restart wireplumber pipewire pipewire-pulse
else
echo "（无 user 会话，请登录后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）" >&2
fi
echo "完成。sof-rt5682 将不再使用本仓库的 HiFi UCM（HDMI1/2/3 等端口名来自该 overlay）。"
if [[ "$removed" -eq 1 ]]; then
echo "建议：走 pro-audio 时在仓库根执行 ./scripts/apply-kaisa-pro-audio.sh"
fi

21
scripts/strip-kaisa-default-profile-state.sh Executable file
View File

@@ -0,0 +1,21 @@
#!/usr/bin/env bash
# 从 WirePlumber 持久状态里删掉 cml_rt5682 声卡那一行。
# 原因：default-profile 模块会读取 ~/.local/state/wireplumber/default-profile，
# 若其中保存了 output:stereo-fallback+input:stereo-fallback，会在每次启动时
# 覆盖 monitor.alsa.rules 里设的 pro-audio，表现为「pro-output 出现一下又变回 stereo-fallback」。
#
# 由 apply-kaisa-pro-audio.sh（重启栈之前）与 kaisa-reapply-pro-audio-session.sh 调用；也可单独执行。
set -euo pipefail
STATE_DIR="${HOME}/.local/state/wireplumber"
F="${STATE_DIR}/default-profile"
[[ -f "$F" ]] || exit 0
if ! grep -q 'cml_rt5682' "$F" 2>/dev/null; then
exit 0
fi
tmp="${F}.tmp.$$"
grep -v 'cml_rt5682' "$F" > "$tmp"
mv -f -- "$tmp" "$F"
echo "strip-kaisa-default-profile-state: 已从 $F 移除含 cml_rt5682 的行（请保持 pro-audio 后由 WirePlumber 再写回正确 profile）"

287
scripts/verify-kaisa-audio-environment.sh Executable file
View File

@@ -0,0 +1,287 @@
#!/usr/bin/env bash
# Kaisa（Google-Kaisa / sof-rt5682 / cml_rt5682）音频环境一次性全面验证。
# 覆盖：PCI、ALSA 枚举、UCM2、已安装 overlay、PipeWire/Pulse、WirePlumber、
# IEC958/Jack（amixer）、HDMI ELD、近期用户态日志片段。
#
# 用法（在图形会话或 SSH 带 XDG_RUNTIME_DIR 时）：
# ./scripts/verify-kaisa-audio-environment.sh
# ./scripts/verify-kaisa-audio-environment.sh --output ~/kaisa-audio-verify.txt
# sudo ./scripts/verify-kaisa-audio-environment.sh # 会经 sudo -u $SUDO_USER 调用 pactl/journalctl（勿裸 root 登录）
#
# 注意：PipeWire-Pulse 的 pactl 必须「以会话用户 + 其 /run/user/<uid>」连接；root 进程不能直接占用普通用户的 XDG_RUNTIME_DIR。
#
# 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
set -uo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
export REPO_ROOT
OUT_FILE=""
while [[ $# -gt 0 ]]; do
case "$1" in
--output|-o)
OUT_FILE="${2:?}"
shift 2
;;
-h|--help)
sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'
exit 0
;;
*)
echo "未知参数: $1 （使用 --help）" >&2
exit 1
;;
esac
done
# root + sudo：pactl / wpctl / journalctl --user 必须代会话用户执行（不能 root 直连用户 PipeWire）
PACTL_PREFIX=()
JOURNAL_PREFIX=()
WCONF_HOME="${HOME}"
if [[ $EUID -eq 0 && -n "${SUDO_USER:-}" ]] && command -v sudo &>/dev/null && id -u "$SUDO_USER" &>/dev/null; then
_VU="$(id -u "$SUDO_USER")"
if [[ -d "/run/user/${_VU}" ]]; then
_VH="$(getent passwd "$SUDO_USER" | cut -d: -f6)"
_VH="${_VH:-/home/$SUDO_USER}"
PACTL_PREFIX=(sudo -u "$SUDO_USER" env XDG_RUNTIME_DIR="/run/user/${_VU}" HOME="$_VH")
JOURNAL_PREFIX=(sudo -u "$SUDO_USER" env XDG_RUNTIME_DIR="/run/user/${_VU}")
WCONF_HOME="$_VH"
fi
fi
if [[ -n "$OUT_FILE" ]]; then
exec > >(tee -a "$OUT_FILE")
exec 2>&1
echo "# 报告文件: $OUT_FILE"
fi
hr() { printf '%s\n' "================================================================================"; }
sec() { printf '\n'; hr; echo "### $*"; hr; echo ""; }
run() {
local title="$1"
shift
echo "# $title"
echo "\`\`\`"
if "$@" 2>&1; then
:
else
echo "(命令返回非零: exit $?)"
fi
echo "\`\`\`"
echo ""
}
have() { command -v "$1" &>/dev/null; }
echo "verify-kaisa-audio-environment"
echo "时间: $(date -Iseconds)"
echo "主机: $(hostname)"
echo "用户: ${USER:-?} EUID=$EUID"
echo "XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-<unset>}"
echo "仓库: $REPO_ROOT"
if [[ $EUID -eq 0 ]]; then
if ((${#PACTL_PREFIX[@]})); then
echo "提示: 当前 root；pactl/journalctl/用户 WirePlumber 路径将经 sudo -u ${SUDO_USER}（会话 UID $(id -u "$SUDO_USER")）。"
else
echo "提示: 当前 root 且无法解析 SUDO_USER 或 /run/user/<uid>；pactl 与 --user 日志可能失败（建议普通用户执行本脚本，或 sudo -u <登录用户> ./scripts/...）。"
fi
fi
echo ""
sec "1) 系统与软件包"
run "uname -a" uname -a
if have dpkg; then
run "dpkg 相关包版本" bash -c "dpkg -l 2>/dev/null | grep -E '^(ii|rc)\s+(alsa-ucm-conf|alsa-utils|libasound|wireplumber|pipewire|pipewire-pulse|pipewire-bin|pipewire-audio-client-libraries)\s' || true"
fi
for c in pipewire wireplumber pactl wpctl alsaucm aplay amixer; do
if have "$c"; then
echo "# $c: $(command -v "$c")"
else
echo "# $c: (未安装)"
fi
done
echo ""
sec "2) PCI 音频"
if have lspci; then
run "lspci -nn | grep -iE 'audio|multimedia'" bash -c "lspci -nn 2>/dev/null | grep -iE 'audio|multimedia|display' || true"
else
echo "(无 lspci)"
echo ""
fi
sec "3) ALSA 声卡与 PCM"
run "/proc/asound/cards" cat /proc/asound/cards
run "/proc/asound/pcm（节选）" bash -c "head -120 /proc/asound/pcm 2>/dev/null || true"
if have aplay; then
run "aplay -l" aplay -l
run "aplay -L（节选 HDMI/sof/0）" bash -c "aplay -L 2>/dev/null | grep -iE 'hdmi|display|sof|card 0|plughw' | head -80 || true"
else
echo "(无 aplay)"
echo ""
fi
sec "4) HDMI ELD（有接线时才有内容）"
shopt -s nullglob
eld_files=(/proc/asound/card*/eld*)
if ((${#eld_files[@]})); then
for f in "${eld_files[@]}"; do
echo "# $f"
echo "\`\`\`"
cat "$f" 2>/dev/null || echo "(无法读取)"
echo "\`\`\`"
echo ""
done
else
echo "(未找到 /proc/asound/card*/eld*)"
echo ""
fi
sec "5) UCM2（alsaucm）与系统路径"
run "vendor/overlay UCM 文件是否存在" bash -c '
for p in \
/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf \
/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf \
"$REPO_ROOT/reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" \
"$REPO_ROOT/reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf"
do
if [[ -f "$p" ]]; then echo "OK $p"; else echo "NO $p"; fi
done
'
UCM_NAME=""
if grep -q 'sof-rt5682' /proc/asound/cards 2>/dev/null; then
UCM_NAME="sof-rt5682"
fi
if have alsaucm; then
if [[ -n "$UCM_NAME" ]]; then
run "alsaucm -c ${UCM_NAME} list _verbs" alsaucm -c "$UCM_NAME" list _verbs
else
run "alsaucm（未在 /proc/asound/cards 识别 sof-rt5682；尝试 sof-rt5682）" alsaucm -c sof-rt5682 list _verbs
fi
else
echo "(未安装 alsaucm，跳过 UCM 列表)"
echo ""
fi
sec "6) WirePlumber / 桌面侧配置"
run "系统 Lua 60-kaisa-ucm.lua" bash -c '
f=/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua
if [[ -f "$f" ]]; then echo "OK $f"; wc -l "$f"; head -25 "$f"; else echo "NO $f"; fi
'
run "用户 ~/.config/wireplumber 中含 kaisa 的片段（主目录: ${WCONF_HOME}）" bash -c '
d="'"$WCONF_HOME"'/.config/wireplumber/wireplumber.conf.d"
if [[ -d "$d" ]]; then
find "$d" -maxdepth 1 -type f \( -iname "*kaisa*" -o -iname "50-kaisa*" \) -print 2>/dev/null | while read -r p; do echo "FILE $p"; done
if ! find "$d" -maxdepth 1 -type f \( -iname "*kaisa*" -o -iname "50-kaisa*" \) -print -quit 2>/dev/null | grep -q .; then
echo "(未找到 kaisa 相关片段)"
fi
else
echo "(目录不存在: $d)"
fi
'
sec "7) PipeWire / Pulse（pactl）"
if have pactl; then
if ((${#PACTL_PREFIX[@]})); then
echo "#（经 ${PACTL_PREFIX[0]} ${PACTL_PREFIX[1]} … 调用 pactl，连接用户 PipeWire-Pulse）"
echo ""
fi
run "pactl 版本" "${PACTL_PREFIX[@]}" pactl --version
echo "# 默认 sink / source"
echo "\`\`\`"
echo -n "default-sink: "
"${PACTL_PREFIX[@]}" pactl get-default-sink 2>&1 || echo "?"
echo -n "default-source: "
"${PACTL_PREFIX[@]}" pactl get-default-source 2>&1 || echo "?"
echo "\`\`\`"
echo ""
run "pactl list short cards" "${PACTL_PREFIX[@]}" pactl list short cards
run "pactl list short sinks" "${PACTL_PREFIX[@]}" pactl list short sinks
run "pactl list short sources" "${PACTL_PREFIX[@]}" pactl list short sources
run "pactl list cards（全文）" "${PACTL_PREFIX[@]}" pactl list cards
else
echo "(无 pactl，无法检测 PipeWire-Pulse 会话；请登录图形会话或设置 XDG_RUNTIME_DIR)"
echo ""
fi
sec "8) wpctl（若可用）"
if have wpctl; then
if ((${#PACTL_PREFIX[@]})); then
echo "#（经 sudo -u … 调用 wpctl，与 pactl 同一会话 PipeWire）"
echo ""
fi
run "wpctl status" "${PACTL_PREFIX[@]}" wpctl status
else
echo "(无 wpctl)"
echo ""
fi
sec "9) amixer：IEC958 / Jack（卡 0，常见为 Kaisa）"
if have amixer; then
run "amixer -c0（节选）" bash -c "amixer -c0 2>/dev/null | grep -iE 'IEC958|Jack|Simple' | head -80 || true"
else
echo "(无 amixer)"
echo ""
fi
sec "10) 内核环缓冲（需 root 时更完整）"
if [[ -r /dev/kmsg ]] || dmesg &>/dev/null; then
run "dmesg | grep -iE 'sof|snd|hda|audio|hdmi|ASoC|rt5682|iDisp' | tail -60" bash -c "dmesg 2>/dev/null | grep -iE 'sof|snd|hda|audio|hdmi|ASoC|rt5682|iDisp' | tail -60 || true"
else
echo "(dmesg 受限；可 sudo 重跑本脚本)"
echo ""
fi
sec "11) 用户态 pipewire / wireplumber 日志（本启动项）"
if have journalctl; then
if ((${#JOURNAL_PREFIX[@]})); then
echo "# journalctl --user -u pipewire -u wireplumber（经 sudo -u ${SUDO_USER}）| tail -40"
echo "\`\`\`"
"${JOURNAL_PREFIX[@]}" journalctl --user -u pipewire -u wireplumber -b --no-pager 2>/dev/null | tail -40 || echo "(无条目或失败)"
echo "\`\`\`"
echo ""
else
run "journalctl --user -u pipewire -u wireplumber -b --no-pager | tail -40" bash -c "journalctl --user -u pipewire -u wireplumber -b --no-pager 2>/dev/null | tail -40 || true"
fi
else
echo "(journalctl 未安装)"
echo ""
fi
sec "12) 摘要（自动推断，仅供参考）"
KAISA_IN_CARDS=0
grep -q 'sof-rt5682' /proc/asound/cards 2>/dev/null && KAISA_IN_CARDS=1
HIFI_UCM=0
if have alsaucm && [[ "$KAISA_IN_CARDS" -eq 1 ]]; then
alsaucm -c sof-rt5682 list _verbs 2>/dev/null | grep -q HiFi && HIFI_UCM=1 || true
fi
PACTL_HIFI_PROFILE=0
USE_UCM_TRUE=0
PC_TEXT=""
if have pactl; then
PC_TEXT="$("${PACTL_PREFIX[@]}" pactl list cards 2>/dev/null)" || true
if [[ -n "$PC_TEXT" ]]; then
echo "$PC_TEXT" | grep -qiE 'HiFi[[:space:]]*:' && PACTL_HIFI_PROFILE=1 || true
echo "$PC_TEXT" | grep -q 'api.alsa.use-ucm = "true"' && USE_UCM_TRUE=1 || true
fi
fi
LUA_SYS=0
[[ -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua ]] && LUA_SYS=1
echo "- 内核 /proc/asound/cards 含 sof-rt5682: $([[ "$KAISA_IN_CARDS" -eq 1 ]] && echo OK || echo FAIL)"
echo "- alsaucm 列出 HiFi verb: $([[ "$HIFI_UCM" -eq 1 ]] && echo OK || echo FAIL/WARN)"
echo "- pactl 声卡段出现 HiFi profile（HiFi: 行）: $([[ "$PACTL_HIFI_PROFILE" -eq 1 ]] && echo OK || echo WARN（可与 UCM 不一致，见 OPERATION）)"
echo "- pactl api.alsa.use-ucm = true: $([[ "$USE_UCM_TRUE" -eq 1 ]] && echo OK || echo WARN)"
echo "- /usr/share/.../60-kaisa-ucm.lua 存在: $([[ "$LUA_SYS" -eq 1 ]] && echo OK || echo WARN)"
echo ""
echo "说明：「alsaucm 有 HiFi」但「pactl 无 HiFi profile」时，属 ACP 未注册该 profile，"
echo " 不要以 pactl set-card-profile … HiFi 作为唯一验收依据。"
echo ""
hr
echo "完成。"
exit 0

108
scripts/verify-kaisa-pro-audio.sh Executable file
View File

@@ -0,0 +1,108 @@
#!/usr/bin/env bash
# Kaisa pro-audio 基线门禁：检查 WirePlumber 片段、UCM Lua、卡 profile、sinks、IEC958。
# 退出码 0 = 通过，1 = 未满足（stdout 说明缺项）。
#
# 须在图形/用户会话下执行（pactl 连接 PipeWire-Pulse）；勿裸 root 占用普通用户 XDG_RUNTIME_DIR。
# 若用 sudo 调用本脚本，需带 SUDO_USER，脚本会经 sudo -u $SUDO_USER + XDG_RUNTIME_DIR 调用 pactl。
#
# 用法：./scripts/verify-kaisa-pro-audio.sh
set -uo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PACTL_PREFIX=()
WCONF_HOME="${HOME}"
if [[ $EUID -eq 0 && -n "${SUDO_USER:-}" ]] && command -v sudo &>/dev/null && id -u "$SUDO_USER" &>/dev/null; then
_VU="$(id -u "$SUDO_USER")"
if [[ -d "/run/user/${_VU}" ]]; then
_VH="$(getent passwd "$SUDO_USER" | cut -d: -f6)"
_VH="${_VH:-/home/$SUDO_USER}"
PACTL_PREFIX=(sudo -u "$SUDO_USER" env XDG_RUNTIME_DIR="/run/user/${_VU}" HOME="$_VH")
WCONF_HOME="$_VH"
fi
fi
if [[ $EUID -eq 0 && ${#PACTL_PREFIX[@]} -eq 0 ]]; then
echo "verify-kaisa-pro-audio: 当前为 root 且无法解析 SUDO_USER/会话；请用登录用户执行，或: sudo -u <用户> $0" >&2
exit 1
fi
fail() { echo "verify-kaisa-pro-audio: FAIL — $*" >&2; exit 1; }
ok() { echo "verify-kaisa-pro-audio: OK — $*"; }
if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'
exit 0
fi
if ! command -v pactl &>/dev/null; then
fail "未找到 pactl（建议安装 pulseaudio-utils）"
fi
if ! command -v amixer &>/dev/null; then
fail "未找到 amixer（alsa-utils）"
fi
if ! grep -q 'sof-rt5682' /proc/asound/cards 2>/dev/null; then
fail "/proc/asound/cards 中无 sof-rt5682"
fi
ok "ALSA 卡 sof-rt5682 存在"
if [[ -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua ]]; then
fail "仍存在可加载的 /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua（应改为 .disabled 或删除）"
fi
ok "60-kaisa-ucm.lua 未处于激活路径"
conf="${WCONF_HOME}/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf"
if [[ ! -f "$conf" ]]; then
fail "缺少用户 WirePlumber 片段: $conf"
fi
ok "用户级 50-kaisa-sof-rt5682-hdmi.conf 存在"
wp_state="${WCONF_HOME}/.local/state/wireplumber/default-profile"
if [[ -f "$wp_state" ]] && grep 'cml_rt5682' "$wp_state" 2>/dev/null | grep -qF 'stereo-fallback'; then
fail "WirePlumber 状态文件仍要求 cml_rt5682 使用 stereo-fallback（会在重启后顶掉 pro-audio）。请执行: ${REPO_ROOT}/scripts/strip-kaisa-default-profile-state.sh 后 systemctl --user restart wireplumber pipewire pipewire-pulse，或重新运行 apply-kaisa-pro-audio.sh"
fi
pactl_cards="$("${PACTL_PREFIX[@]}" pactl list cards 2>/dev/null)" || fail "pactl list cards 失败"
if ! grep -qF 'cml_rt5682' <<< "$pactl_cards"; then
fail "pactl list cards 中无 cml_rt5682（PCI/卡名是否与仓库 conf 一致？）"
fi
# 在「含 cml_rt5682 的卡」块内取第一条 活动配置 / Active Profile（避免匹配到「配置文件」里的 pro-audio 行）
active_line="$(awk '
/^卡 #[0-9]+/ || /^Card #[0-9]+/ { in_c=0 }
/cml_rt5682/ { in_c=1 }
in_c && (/活动配置/ || /Active Profile/) { print; exit }
' <<< "$pactl_cards")"
if [[ -z "$active_line" ]]; then
fail "无法在 cml_rt5682 卡块内解析 活动配置/Active Profile 行"
fi
if [[ "$active_line" != *pro-audio* ]]; then
_al="$(echo "$active_line" | tr -d '\t' | sed 's/^[[:space:]]*//')"
fail "该卡活动配置不是 pro-audio（当前: ${_al}）。请执行: ${REPO_ROOT}/scripts/apply-kaisa-pro-audio.sh（勿加 --verify-only）"
fi
ok "pactl 声卡活动配置为 pro-audio"
sinks="$("${PACTL_PREFIX[@]}" pactl list short sinks 2>/dev/null)" || fail "pactl list short sinks 失败"
for po in pro-output-0 pro-output-2 pro-output-3 pro-output-4; do
if ! grep -F 'cml_rt5682' <<< "$sinks" | grep -qF "$po"; then
fail "缺少 sink …${po}（pro-audio 下应暴露 Port1 + HDMI1/2/3）"
fi
done
ok "pactl short sinks 含 pro-output-0/2/3/4（cml_rt5682）"
def="$("${PACTL_PREFIX[@]}" pactl get-default-sink 2>/dev/null)" || fail "pactl get-default-sink 失败"
if [[ "$def" != *pro-output-2* ]]; then
fail "默认 sink 应为 …pro-output-2，当前: $def"
fi
ok "默认 sink 为 pro-output-2"
for i in 0 1 2; do
out="$(amixer -c0 sget "IEC958",$i 2>/dev/null || true)"
if ! grep -qiE '\[on\]|\[开启\]' <<< "$out"; then
fail "IEC958',$i' 非开启状态（需 amixer -c0 sset 'IEC958',$i on）"
fi
done
ok "IEC958',0/1/2 均为 on"
echo "verify-kaisa-pro-audio: 全部检查通过。"
exit 0