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

docs(kaisa): make UCM HiFi the only supported path

Browse Source 
Promote UCM2/HiFi (Jack-driven) as the primary delivery, add HISTORY.md,
remove ProAudio/REPRO docs and non-UCM scripts, and fix repo-wide references.

Made-with: Cursor
This commit is contained in:
jack
2026-04-08 15:22:45 +08:00
parent 17f0a4521f
commit bda6b60c15
33 changed files with 384 additions and 1780 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -5,7 +5,7 @@
# 本机大文件备份（勿提交）
chromiumos_kernel_v5.15_git_backup.tar.xz
# capture-ubuntu-audio-baseline.sh 本地基线（含 topology / tar，体积与隐私不宜入库）
# 本地基线（含 topology / tar，体积与隐私不宜入库）
audio_topology/baseline-stash/
# 本机 sound/soc 等对照 diff（可选放入 reference/chromeos-ubuntu-sound-diffs/）

83
HISTORY.md Normal file
View File

@@ -0,0 +1,83 @@
# HISTORY（Kaisa 桌面音频：硬件结构与技术路线演进）
本文是**历史记录**：解释我们为什么从早期的 pro-audio 路线迁移到当前的 **UCM2 + HiFi（Jack-driven）**，并把关键事实锚点落盘，避免未来“只剩结论、忘了原因”。
---
## 1. 机型与硬件结构（事实锚点）
- **机型**：Google Kaisa（Chromebox 10）
- **声卡/驱动**：`sof-rt5682`（`snd_soc_sof_rt5682`）
- **ALSA 设备号（常见）**：`aplay -l` 会列出 `card 0: sofrt5682`
- `device 0`：Port1（模拟/3.5mm）
- `device 2/3/4`：HDMI1/HDMI2/HDMI3（iDisp/HDMI 音频）
### 1.1 IEC958 与 HDMI device 对照（本机事实）
在本机验证中，HDMI 数字输出开关与 device 号对齐关系为：
- **pcm=2** → `IEC958',0`（numid=14）
- **pcm=3** → `IEC958',1`（numid=20）
- **pcm=4** → `IEC958',2`（numid=26）
检查与打开（建议三路全开，避免误判）：
```bash
amixer -c0 sget 'IEC958',0; amixer -c0 sget 'IEC958',1; amixer -c0 sget 'IEC958',2
amixer -c0 sset 'IEC958',0 on
amixer -c0 sset 'IEC958',1 on
amixer -c0 sset 'IEC958',2 on
```
---
## 2. 早期路线：PipeWire pro-audio（已弃用）
### 2.1 为什么曾经用 pro-audio
- 默认 profile（如 `stereo-fallback`）往往只暴露极少 sink，HDMI 路由在桌面上很难选。
- 切到 `pro-audio` 后可以强制把多路 PCM 暴露出来，便于用 `pactl`/`wpctl` 明确选到某一路输出。
### 2.2 为什么最终放弃
在 Kaisa 上，`pro-audio` 路线的核心问题不是“能不能出声”，而是**可维护性与一致性**：
- WirePlumber 的 **default-profile 持久化**会把声卡从 `pro-audio` 顶回 `stereo-fallback`，出现“输出出现一下又消失”的体验，需要反复清状态/重拉 profile。
- 桌面环境对 `pro-audio` 的端口枚举不稳定：常出现“输出列表项少/不直观”，与我们想要的“插线才显示、按端口可用性选路”目标相冲突。
结论：pro-audio 作为调试手段尚可，但不适合作为交付主线。
---
## 3. 现行路线：UCM2 + HiFi（Jack-driven，主交付）
### 3.1 方案目标
- **HDMI 仅在插入时**出现在桌面输出列表（Jack-driven ports）
- 使用 PipeWire/ACP 的端口可用性模型，减少“鬼端口/常驻多路输出”的误导
### 3.2 仓库实现（关键文件）
- UCM 入口：`reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`
- HiFi UseCase：`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`
- 每路 HDMI 绑定 `JackControl "HDMI/DP,pcm=N Jack"` + 对应 IEC958 numid 开关序列
- 必须包含 `SectionVerb { Value { TQ "HiFi" } }`，且 **verb 内不要使用 `disdevall`**（否则可能导致 PipeWire 侧不注册 `HiFi:` profile）
- WirePlumber 规则：`wireplumber/main.lua.d/60-kaisa-ucm.lua`
- 启用 `api.alsa.use-ucm=true`、`api.acp.auto-port=true`
- 用 `KAISA_WP_DEVICE_PROFILE` 控制默认 profile（在 `HiFi:` 未注册前可用 `pro-audio` 过渡，避免卡到 `off`）
安装/卸载/验收步骤以主交付文档为准：
- `docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md`
---
## 4. 关于 “HDMI1/HDMI2 展示名”
桌面里看到的 `HDMI1/HDMI2/...` 文案主要来自：
- UCM `HiFi.conf` 中 `SectionDevice."HDMI1"` / `Comment "HDMI1"` 等定义（端口模型）
- PipeWire/ACP 根据 UCM 设备与 Jack 可用性生成端口/路由
不同桌面版本的展示可能略有差异，但 **“插入才可用/可选”** 是此路线的核心目标。

27
README.md
View File

@@ -1,15 +1,12 @@
# chromebox_10th_audio_driver
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-*`）。
Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**交付：仓库主线为 **ALSA UCM2 + PipeWire HiFi（Jack-driven 端口）**，目标是 **HDMI 仅在插入时才出现在输出列表中**，并能稳定出声。
## 文档（仅保留已实机验证路线）
| 你想… | 打开 |
| ----- | ---- |
| **操作与排障（pro-audio 主路线）** | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)（文内 **「核心问题」**、**恢复 Ubuntu 后重测**） |
| **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) |
| **操作与排障（主交付）** | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) |
| 全仓库路径与脚本表 | [REPO_INDEX.md](REPO_INDEX.md) |
| UCM2 源码（overlay / 曾拟打入 deb） | [reference/ucm2/README.md](reference/ucm2/README.md) |
| 拓扑采集脚本 | [audio_topology/COLLECT.md](audio_topology/COLLECT.md) |
@@ -20,21 +17,15 @@ Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**
---
## 现象速览（Kaisa）
## 现象速览（Kaisa / UCM 主线）
| 平台 | HDMI | 3.5mm |
|------|------|-------|
| Linux（本仓库目标） | 需 **pro-audio profile** + 正确 **IEC958** / 默认 sink；**`stereo-fallback` 常仅一路** | 一般有（以本机 `aplay -L` 为准） |
细节以 **[ProAudio 文档](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)** 为准。
- **HDMI**：插入后才在输出列表出现（Jack-driven），并按 UCM `HiFi` 的 device 2/3/4（HDMI1/2/3）出声；IEC958 需为 on。
- **3.5mm**：Port1（模拟）一般可用。
---
## 速链
## 速链（UCM 主线）
- **基线**：`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。
- **一键 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`）。
- **禁用 pro-audio 片段**：`scripts/disable-kaisa-pro-audio-wireplumber.sh`（可选 `--system`）
- **安装 UCM overlay + WirePlumber Lua**：`scripts/install-kaisa-ucm-overlay.sh`
- **卸载 overlay（恢复发行版 vendor 配置）**：见主文档的卸载段落

15
REPO_INDEX.md
View File

@@ -17,9 +17,7 @@
| 文件 | 说明 |
| ---- | ---- |
| [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/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 手顺存档（未来计划） |
| [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2 + HiFi（Jack-driven） |
## [`audio_topology/`](./audio_topology/)
@@ -33,13 +31,9 @@
| 脚本 | 说明 |
| ---- | ---- |
| [capture-ubuntu-audio-baseline.sh](./scripts/capture-ubuntu-audio-baseline.sh) | 大改前 / overlay 或历史 deb 后采集系统音频基线 |
| [restore-ubuntu-audio-baseline.sh](./scripts/restore-ubuntu-audio-baseline.sh) | 恢复到某次基线 |
| [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） |
| [disable-kaisa-pro-audio-wireplumber.sh](./scripts/disable-kaisa-pro-audio-wireplumber.sh) | 禁用强制 pro-audio 的 WirePlumber 片段（与 UCM 互斥） |
| [install-kaisa-ucm-overlay.sh](./scripts/install-kaisa-ucm-overlay.sh) | 安装 UCM2 overlay + `60-kaisa-ucm.lua` 到系统路径 |
| [remove-kaisa-ucm-overlay.sh](./scripts/remove-kaisa-ucm-overlay.sh) | 卸载本仓库安装的 UCM2 overlay 与系统级 `60-kaisa-ucm.lua` |
BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad/scripts/render_bmad_help_zh_cn.py) → 根目录 `bmad-help.zh-CN.md`。
@@ -52,7 +46,6 @@ BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad
| 文件 | 说明 |
| ---- | ---- |
| [README.md](./README.md) | 仓库说明 |
| [next.md](./next.md) | 下一步速查 |
| [help.md](./help.md) | BMad 菜单码 |
## 维护

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

@@ -80,21 +80,21 @@ workflowType: epics
**目标：** 满足 **SC1** 与 **FR1、FR2、FR9**；新贡献者 10 分钟内找到 Linux HDMI 主线。
### Story 1.1：INDEX 与 OPERATION/REPRO
### Story 1.1：INDEX 与 OPERATION
作为一名**维护者**，
我希望 **INDEX.md** 能链到 **OPERATION** 与 **REPRO**，
我希望 **INDEX.md** 能链到 **OPERATION**，
以便 **不必搜全库**（**FR1**）。
**验收标准：**
- **Given** 仓库根已克隆
- **When** 打开 `docs/INDEX.md`
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_ProAudio.md`、`OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 的条目
### Story 1.2：（已收敛）路线图
**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION + REPRO** 为事实源。
**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION** 为事实源。
### Story 1.3：README 与 PRD / BMad 链
@@ -125,7 +125,7 @@ workflowType: epics
### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动
作为一名 **Kaisa 用户**，
我希望 **OPERATION_PipeWire_Kaisa_ProAudio.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**，
我希望 **OPERATION_PipeWire_Kaisa_UCM_HiFi.md** 说明 **UCM2 / HiFi**、**`speaker-test -D pulse`**、**IEC958',N**、以及安装器脚本（disable + install），
以便 **排障不靠口口相传**（**FR5**）。
**验收标准：**

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

@@ -4,9 +4,7 @@ stepsCompleted:
inputDocuments:
- README.md
- docs/INDEX.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
workflowType: prd
brownfield_synthesis: true
synthesis_note: 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。
@@ -19,13 +17,13 @@ last_edited: '2026-04-06'
**日期：** 2026-04-06
**状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4）
**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。
**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md** 与 **OPERATION_PipeWire_Kaisa_UCM_HiFi.md** 为准。
---
## 1. 摘要
本「产品」为 **Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频** 的 **文档、脚本与 deb** 单体仓库，**交付主线**是 **Linux 下 HDMI 可稳定出声**（PipeWire / pro-audio / IEC958）；**自编内核与 SOF 诊断补丁**已不在仓库内维护。保留 **ChromeOS 源码树对照** 与 **拓扑采集**。
本「产品」为 **Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频** 的 **文档、脚本与 deb** 单体仓库，**交付主线**是 **Linux 下 HDMI 可稳定出声**（UCM2 + HiFi / IEC958）；**自编内核与 SOF 诊断补丁**已不在仓库内维护。保留 **ChromeOS 源码树对照** 与 **拓扑采集**。
**已验证关键用户态根因（Kaisa）**：**`IEC958',0`（pcm=2）关闭**时 PipeWire 可看似正常但 **HDMI 无声**；**打开后即有声**。登录自动恢复见 **OPERATION §4.3**（规划中；当前 **pactl**/**amixer** 手顺）。
@@ -64,7 +62,7 @@ last_edited: '2026-04-06'
| 角色 | 目标 | 主要触点 |
|------|------|----------|
| **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） |
| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_ProAudio.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 |
| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_UCM_HiFi.md`、UCM2 overlay、WirePlumber `60-kaisa-ucm.lua` |
| **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） |
---
@@ -88,11 +86,11 @@ last_edited: '2026-04-06'
| ID | 能力 | 验收要点 |
|----|------|----------|
| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 |
| **FR2** | **Linux HDMI 技术路线** | **ProAudio / UCM 文档** 覆盖 pro-audio、UCM、deb；**REPRO** 为验收手顺。 |
| **FR5** | **桌面 HDMI 操作说明** | **ProAudio 文档** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 |
| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**。 |
| **FR2** | **Linux HDMI 技术路线** | **UCM 文档** 覆盖 UCM2 + HiFi、IEC958、安装/验收/排障。 |
| **FR5** | **桌面 HDMI 操作说明** | **UCM 文档** 覆盖 **Jack-driven 端口**、**IEC958**、以及排障注意事项（例如避免在 PipeWire 运行时直连 `hw:` 试声）。 |
| **FR6** | **登录自动修复（Kaisa）** | **OPERATION §4.3**：**user systemd** 示例 + 手顺；**deb ≥0.3.0** 不随包提供可执行工具。 |
| **FR7** | **WirePlumber 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 |
| **FR7** | **WirePlumber 片段示例** | **`60-kaisa-ucm.lua`** 通过 **`api.alsa.use-ucm`** 与 `KAISA_WP_DEVICE_PROFILE` 控制默认 profile。 |
| **FR8** | **对照与导出** | **ChromeOS ↔ Ubuntu**：本机两树 **`diff`**；可选输出至 **`reference/chromeos-ubuntu-sound-diffs/`**（见该目录 README）。 |
| **FR9** | **BMad 规划链** | **本 PRD** 与（可选）**architecture / epics** 可链接；**README** 指向 **`_bmad-output/planning-artifacts/prd.md`**。 |
@@ -104,10 +102,8 @@ last_edited: '2026-04-06'
```bash
test -f docs/INDEX.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
grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
grep -q 'OPERATION_PipeWire_Kaisa_UCM_HiFi' docs/INDEX.md
```
---
@@ -120,7 +116,7 @@ grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
| **NFR2** | **可维护性** | 大目录（如 `chromiumos_kernel/`、本机 HWE 解压树）**不强制入库**；对照脚本用 **`UB=`** 指向本机路径。 |
| **NFR3** | **变更粒度** | 代码/脚本以 **最小 diff** 对齐现有风格；避免无关重构。 |
| **NFR4** | **安全与权限** | 用户态修复以 **`systemctl --user`** 为主；**避免**要求普通用户长期 **root** 改系统 ALSA 全局状态作为唯一路径。 |
| **NFR5** | **诚实边界** | **`pro-audio`** 下 GNOME 可能 **列出多路 Pro N**；文档说明与 **「仅插线才显示」** 的取舍。 |
| **NFR5** | **诚实边界** | 桌面输出列表的表现依赖版本与策略；以 **UCM Jack-driven** 作为主交付，解释其与「常驻多路输出」策略的取舍。 |
---
@@ -146,9 +142,7 @@ grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
## 10. 参考（仓库内）
- [docs/INDEX.md](../../docs/INDEX.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)
- [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_ProAudio.md](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)**（及可选 **[UCM 文档](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）为准；本目录采集为**辅助证据**，不替代操作文档。
排查 HDMI 用户态路由以 **[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](../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"
# --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md）---
# --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md）---
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 "# 用于对照 SOF/IPC 与 dmesg；建议 sudo 运行本脚本以读全量 dmesg" >> "$OUTPUT"

4
debian/changelog vendored
View File

@@ -33,14 +33,14 @@ kaisa-hdmi-pipewire-fix (0.2.4) unstable; urgency=medium
kaisa-hdmi-pipewire-fix (0.2.3) unstable; urgency=medium
* kaisa-restore-iec958-ucm: match HiFi__hw_sofrt5682_N__ sink names (Kaisa pactl).
* next.md OPERATION: troubleshooting when IEC958 on but silent (wpctl, HDMI port).
* OPERATION: troubleshooting when IEC958 on but silent (wpctl, HDMI port).
-- chromebox_10th_audio_driver <maintainers@local> Mon, 07 Apr 2026 12:00:00 +0800
kaisa-hdmi-pipewire-fix (0.2.2) unstable; urgency=medium
* kaisa-restore-iec958-ucm: hdmi/displayport sink heuristics; reject pcm 0/1 with hint.
* next.md / OPERATION / postinst: apt upgrade may reinstall 50-kaisa; diagnostic block.
* OPERATION / postinst: apt upgrade may reinstall 50-kaisa; diagnostic block.
-- chromebox_10th_audio_driver <maintainers@local> Sun, 06 Apr 2026 22:00:00 +0800

3
debian/control vendored
View File

@@ -19,8 +19,7 @@ Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
use manual pactl/amixer steps in upstream docs (ProAudio / UCM) until
automated restore is ready. UCM-first and pro-audio WirePlumber are mutually
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.
docs in the source tree: OPERATION_PipeWire_Kaisa_UCM_HiFi.md.
.
PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
/etc/wireplumber/ if needed.

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

@@ -15,8 +15,7 @@ Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
use manual pactl/amixer steps in upstream docs (ProAudio / UCM) until
automated restore is ready. UCM-first and pro-audio WirePlumber are mutually
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.
docs in the source tree: OPERATION_PipeWire_Kaisa_UCM_HiFi.md.
.
PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
/etc/wireplumber/ if needed.

2
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`）
本目录为 **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)**）。
本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同；见源码树 **[UCM 操作文档](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）。
## 布局

7
docs/INDEX.md
View File

@@ -4,10 +4,7 @@
| 文档 | 说明 |
| ---- | ---- |
| [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/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 手顺**存档**（未来计划） |
| [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2、HiFi、`60-kaisa-ucm.lua`、Jack-driven 端口、IEC958、安装 / 验收 / 排障 |
| [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)。
**脚本（仓库根 `scripts/`）**：禁用 pro-audio 片段 — [`disable-kaisa-pro-audio-wireplumber.sh`](../scripts/disable-kaisa-pro-audio-wireplumber.sh)；安装 UCM overlay — [`install-kaisa-ucm-overlay.sh`](../scripts/install-kaisa-ucm-overlay.sh)。

6
docs/README.md
View File

@@ -1,12 +1,10 @@
# `docs/` 说明
本目录保留 **已实机验证** 的 PipeWire 主路线；**deb 不作为当前交付**（仅未来计划存档）。
本目录保留 **已实机验证** 的 Kaisa（`sof-rt5682`）音频交付文档；当前主交付为 **UCM2 + HiFi（Jack-driven）**。
| 文档 | 内容 |
| ---- | ---- |
| [linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **主路线**：**核心问题复盘**、**default-profile**、pro-audio、`50-kaisa`、一键脚本、**恢复 Ubuntu 重测**、基线 |
| [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/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2、HiFi、Jack-driven 端口、IEC958、安装/验收/排障 |
附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。

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

@@ -1,10 +0,0 @@
# 本文件已拆分（兼容旧链接）
原 **`OPERATION_PipeWire_Kaisa_HDMI.md`** 已拆成两篇，请直接打开：
| 文档 | 内容 |
|------|------|
| **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** | **主路线（已验证）**：PipeWire **pro-audio**、`50-kaisa-sof-rt5682-hdmi.conf`、默认 **`pro-output-0` / `pro-output-2`**、IEC958、一键脚本与基线（**deb 仅 §4.4 存档**） |
| **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** | **可选**：ALSA **UCM2**、**HiFi**、`60-kaisa-ucm.lua`、Jack 驱动端口、安装 / 验收 / 卸载 |
两路线 **互斥**。新读者请从 **ProAudio** 文档读起。

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

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

241
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
View File

@@ -1,127 +1,202 @@
# 操作：Kaisa（sof-rt5682）UCM2 + HiFi（可选路线）
# 操作：Kaisa（sof-rt5682）UCM2 + HiFi（主交付）
**适用**：与 **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** 相同机型（Google **Kaisa**、PipeWire + WirePlumber、**`sof-rt5682`**）。
**目标**：在 Google **Kaisa**（Chromebox 10 / `sof-rt5682`）+ Ubuntu + PipeWire + WirePlumber 上，让 **HDMI 只在插入时才作为可选输出出现**（Jack-driven ports），并能稳定出声。
**本文定位**：在需要 **Jack 驱动端口可用性**、**桌面「端口」模型**（未插线的 HDMI 尽量不表现为随意可选输出）时，使用 **ALSA UCM2** + PipeWire **HiFi** profile，配合 WirePlumber **`60-kaisa-ucm.lua`**。**与强制 pro-audio 的 `50-kaisa-sof-rt5682-hdmi.conf` 互斥**，勿与 ProAudio 主路线同时启用。
**适用**：PipeWire + WirePlumber（WirePlumber 0.4/0.5 均可），声卡为 `sof-rt5682`。
**相关**：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 特有** 现象。
**互斥**：本方案与仓库中「强制 pro-audio」的 WirePlumber 片段互斥（例如 `50-kaisa-sof-rt5682-hdmi.conf`）。启用 UCM/HiFi 时必须先禁用/移走 pro-audio 片段。
**相关源码**：UCM2 overlay 与说明见 **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**。
---
## 1. pro-audio 与 UCM 二选一
## 1. 方案组成（都与本仓库相关）
| 路线 | 做法 | 适用 |
|------|------|------|
| **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 卡入口 | [`reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`](../../reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf) | 将 UseCase `HiFi` 指向本仓库的 `GoogleKaisa/…/HiFi.conf` |
| UCM HiFi（Jack + IEC958） | [`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf) | 定义 Port1 + HDMI1/2/3，包含 `JackControl` 与 `IEC958` 开关序列 |
| WirePlumber 规则 | [`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua) | 对 `sof-rt5682` 启用 `api.alsa.use-ucm`、ACP auto-port，并用 `KAISA_WP_DEVICE_PROFILE` 控制默认 profile |
| 安装脚本 | [`scripts/disable-kaisa-pro-audio-wireplumber.sh`](../../scripts/disable-kaisa-pro-audio-wireplumber.sh)、[`scripts/install-kaisa-ucm-overlay.sh`](../../scripts/install-kaisa-ucm-overlay.sh) | 禁用 pro-audio 片段、安装 UCM overlay + `60-kaisa-ucm.lua` 到系统路径 |
**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若机器上仍有历史 deb 装入的片段，见 **[ProAudio §4.4](OPERATION_PipeWire_Kaisa_ProAudio.md)** 路径表）。改完后：
---
## 2. 可复现安装步骤（推荐顺序）
### 2.1 禁用 pro-audio 片段（必须）
```bash
systemctl --user restart wireplumber pipewire pipewire-pulse
./scripts/disable-kaisa-pro-audio-wireplumber.sh
# 若你曾在 /etc/wireplumber/ 下也装过 50-kaisa*：
./scripts/disable-kaisa-pro-audio-wireplumber.sh --system
```
从 **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`** 第二列为准）：
### 2.2 安装 UCM overlay + WirePlumber Lua（需 sudo）
```bash
pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
./scripts/install-kaisa-ucm-overlay.sh
```
**等价（按整数 profile 序号）**：**`wpctl status`** → **Audio → Devices** 找到 **`sof-rt5682`** 的 **Device id**，再 **`wpctl set-profile <id> <INDEX>`**（**`0` = off**；若仅 **off + pro-audio**，则 **pro-audio** 一般为 **`1`**）。勿用 **MIDI** 等其它对象的 id。
脚本会把文件安装到：
- `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`
- `/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`
- `/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`
并在可用时重启用户 PipeWire 栈。
---
## 3. HiFi 下 HDMI 无声（IEC958）
## 3. 验收（最短闭环）
与 **[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 文件：
### 3.1 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`**。
应能列出 `HiFi`（且不应出现 parse 错误）。
### 4.2 安装（在仓库根目录，需 sudo）
### 3.2 PipeWire 已注册 `HiFi:` profile
```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/
pactl list cards
```
### 4.3 验收清单
在声卡的 **「配置文件：」** 下应能看到 **`HiFi:`**。
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 驱动的可用性**。
若 `pactl` 里已有 `HiFi:`，但活动配置仍不是 `HiFi`，手动切一次：
### 4.4 PipeWire 日志中的 UCM 设备失败
```bash
pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
```
若 **`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)**。
### 3.3 插线才出现 HDMI 输出
插入 HDMI 后：
- GNOME 输出列表应出现 HDMI（例如 `HDMI1`/`HDMI2`），拔出后该项应消失或变为不可用（桌面实现细节可能不同，但应能反映 Jack 可用性）。
### 3.4 出声测试（走 PipeWire）
```bash
speaker-test -D pulse -c2 -t sine -f 440 -l 3
```
若你想强制把测试音打到某一路（避免默认 sink 干扰），先取出 sink 名：
```bash
pactl list short sinks
```
再指定 sink：
```bash
paplay -d "$SINK" /usr/share/sounds/alsa/Front_Center.wav
```
---
## 5. 卸载 / 回退 UCM overlay
## 4. IEC958 与 device 对照（HiFi 模式）
UCM 的 `HiFi.conf` 约定：
- Port1（模拟）：`hw:0,0`
- HDMI1：`hw:0,2` 对应 `IEC958',0`（numid=14）
- HDMI2：`hw:0,3` 对应 `IEC958',1`（numid=20）
- HDMI3：`hw:0,4` 对应 `IEC958',2`（numid=26）
开关检查（一般建议三路全开，避免误判）：
```bash
sudo apt install --reinstall alsa-ucm-conf # 恢复 vendor conf.d/sof-rt5682/
amixer -c0 sget 'IEC958',0; amixer -c0 sget 'IEC958',1; amixer -c0 sget 'IEC958',2
amixer -c0 sset 'IEC958',0 on
amixer -c0 sset 'IEC958',1 on
amixer -c0 sset 'IEC958',2 on
```
---
## 5. 排障（只覆盖 UCM 主线）
### 5.1 `alsaucm` 有 HiFi，但 `pactl` 没有 `HiFi:`
这是 **ACP 未把 UCM HiFi 注册成 EnumProfile** 的典型表现。优先核对：
- [`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf) 是否包含：
- `SectionVerb { Value { TQ "HiFi" } }`
- **且不要**在 verb 内使用 `disdevall`
然后重新安装并重启栈：
```bash
./scripts/install-kaisa-ucm-overlay.sh
systemctl --user restart wireplumber pipewire pipewire-pulse
```
仍无时看日志：
```bash
journalctl --user -u pipewire -u wireplumber -b --no-pager | grep -iE 'ucm|acp|alsa'
```
### 5.2 `pactl` 有 `HiFi:`，但活动配置卡在 `off`
WirePlumber 的 profile 策略会按设备属性 `device.profile` 在 `EnumProfile` 里匹配同名 profile；若 `60-kaisa-ucm.lua` 强制 `device.profile = "HiFi"` 但 `EnumProfile` 里还没有 `HiFi`，就可能把活动配置留在 `off`。
仓库版 [`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua) 提供变量：
- `KAISA_WP_DEVICE_PROFILE = "pro-audio"`（过渡，避免卡死）
- `KAISA_WP_DEVICE_PROFILE = "HiFi"`（当 `pactl` 已有 `HiFi:` 后建议切回）
改动后记得重启用户栈：
```bash
systemctl --user restart wireplumber pipewire pipewire-pulse
```
### 5.3 `set_hw_params: 输入/输出错误` / `suspended -> error`
这表示 PipeWire 在打开对应 `hw:0,N` 时失败，常见原因：
- **该 device 当前不可用**（例如 `aplay -l` 中某路为 `子设备: 0/1`）
- HDMI 热插拔/EDID 状态未就绪
- 你在 PipeWire 运行时尝试对 `hw:0,N` 直连试声导致资源争用与状态混乱
建议检查：
```bash
aplay -l
```
并避免在 PipeWire 运行时执行 `speaker-test -D hw:0,N`。若要直连 ALSA 试声，需先停用户栈：
```bash
systemctl --user stop wireplumber pipewire pipewire-pulse
speaker-test -D hw:0,3 -c2 -r48000 -t sine
systemctl --user start pipewire pipewire-pulse wireplumber
```
---
## 6. 卸载 / 回退 UCM overlay
```bash
sudo apt install --reinstall alsa-ucm-conf
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 # 若曾改名保留
sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua.disabled
systemctl --user restart wireplumber pipewire pipewire-pulse
```
然后 **`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. 参考链接
## 7. 附录：与 pro-audio（仓库内遗留）互斥关系
若你仍保留或曾启用 `50-kaisa*`（用户级 `~/.config/wireplumber/wireplumber.conf.d/` 或系统级 `/etc/wireplumber/wireplumber.conf.d/`），它可能会强制 profile/优先级，破坏 UCM 的 Jack-driven 端口模型；启用本方案前必须先运行：
```bash
./scripts/disable-kaisa-pro-audio-wireplumber.sh
```
仓库仍保留相关 pro-audio 脚本仅供对照与临时排障；仓库主交付以本文为准。
- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
- **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**

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

@@ -1,159 +0,0 @@
# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现）
**状态（当前）**：**不作为维护中的交付路径**；仓库**放弃 deb 工作**，仅作**未来计划**。本文与下文「打包前」表述保留为**存档**，便于日后若恢复 **`kaisa-hdmi-pipewire-fix`** 时对照。日常请直接用 **`scripts/apply-kaisa-pro-audio.sh`**（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md)）。
**目的（存档）**：在真机上**不依赖**写死的 `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**（输出）、**Sources**（输入）、默认 sink 标记 `*` | `wpctl status` |
| 某条 sink 详情（含 `node.name`、`device.profile.name`） | `wpctl inspect <sink 数字 id>`，如 `wpctl inspect @DEFAULT_AUDIO_SINK@` |
| 若已安装 **pulseaudio-utils** | `pactl list short sinks`、`pactl get-default-sink`、`pactl list cards` |
说明：**Sinks** 前的数字 id **重启栈后会变**，以当次 `wpctl status` 为准；**`wpctl set-default <id>`** 只填 **Sink** 的 id，**不要**与 **Devices**（声卡）混淆。
---
## 0. 可选：回到安装 deb / 改配置前的基线
若曾运行过 `capture-ubuntu-audio-baseline.sh`：
```bash
cd /path/to/chromebox_10th_audio_driver
./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/
```
或仅在本机清掉用户片段后重启栈（自行备份）：
```bash
mv -f ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf \
~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf.disabled 2>/dev/null || true
systemctl --user restart pipewire pipewire-pulse
sleep 1
systemctl --user restart wireplumber
```
---
## 1. 与 deb 一致：安装 WirePlumber 片段
**deb 安装位置**：`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`（需 root）。
**手动复现（二选一）**：
**A. 系统级（与 deb 完全一致）**
```bash
sudo mkdir -p /etc/wireplumber/wireplumber.conf.d
sudo cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
/etc/wireplumber/wireplumber.conf.d/
```
**B. 用户级（与当前调试习惯一致，不 sudo）**
```bash
mkdir -p ~/.config/wireplumber/wireplumber.conf.d
cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
~/.config/wireplumber/wireplumber.conf.d/
```
若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md) §2）。
---
## 2. 重启 PipeWire 栈（推荐顺序）
与「空 Audio 列表」排障一致：**先 PipeWire，再 WirePlumber**。
```bash
systemctl --user restart pipewire pipewire-pulse
sleep 1
systemctl --user restart wireplumber
```
再等 1～2 秒。
### 已复制 `50-kaisa-…conf` 但仍只有一条「立体声」sink？
在 **WirePlumber 0.4.x**（Ubuntu 24.04 常见）上，仓库里的 **`monitor.alsa.rules`** 片段**可能不会**自动把卡切到 **pro-audio**，`pactl list cards` 里**活动配置**仍为 **`output:stereo-fallback+input:…`**。这**不代表**片段装错路径，而是**会话管理器版本**与 **0.5+** 行为不同。
**验收与 deb 交付仍成立**：必须再执行下面 §3 的 **`pactl set-card-profile … pro-audio`**。**deb（≥0.3.0）仍包含该 conf**（未来 **0.5+** 或更易合并 drop-in 的环境上可能单独生效）；**不**再随包提供 `kaisa-restore-pipewire-hdmi`，请用本手顺 **`pactl`**/**`amixer`**。
---
## 3. 验证：是否已 `pro-audio`（勿写死 46 / 4）
**稳定标识**是 **声卡名** + **profile 名**，不是数字 id。
```bash
# 若已安装 pulseaudio-utils：
pactl list cards | grep -A2 'alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def' -A30
```
或：
```bash
wpctl status
wpctl inspect <Devices 里该卡的 id> | grep -E 'name|profile'
```
若 **活动配置**仍是 **`stereo-fallback`**，执行：
```bash
pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-audio
```
**实机结论（WirePlumber 0.4.x）**：仅把 **`50-kaisa-…conf`** 放到 **`/etc/wireplumber/...`** 或 **`~/.config/...`** 并重启栈后，**`wpctl status` → Sinks** 往往仍只有一条「立体声」；**执行上列 `pactl set-card-profile … pro-audio` 之后**，才会出现多条 **Pro / Pro 2 / Pro 3 / Pro 4**（或等价 **`pro-output-*`**）。因此 **0.4 验收以本 `pactl` 命令为「多出 sinks」的分界**，而非单靠 conf。
**说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。
**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` 第二列**实际卡名**替换上面长名。
- **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。
- **WirePlumber 0.4.x**：多数情况下**必须**执行本步 `pactl`；见上文「已复制 conf 但仍只有立体声」。
---
## 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`**），并按 [ProAudio §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md) 打开对应 **`IEC958',N`**。
若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 [ProAudio §4.1](OPERATION_PipeWire_Kaisa_ProAudio.md)），再 **`amixer`** 开 IEC958。
---
## 5. 验收标准（打包前勾选）
| 检查项 | 命令 / 预期 |
|--------|-------------|
| 卡 profile | `pactl list cards` 中该卡 **活动配置** 含 **pro-audio**（或等价描述） |
| 多 sink | `pactl list short sinks` 或 `wpctl status` 出现 **pro-output-*** 或 **Pro 2/3/4** |
| 默认输出 | `pactl get-default-sink` 指向 **pro-output-2**（或当前接线对应路） |
| IEC958 | `amixer -c0 sget 'IEC958'` 对应路为 **on** |
| 试声 | `pw-play /usr/share/sounds/alsa/Front_Center.wav` 或 `paplay`（走默认 sink） |
---
## 6. 手顺小节索引
| 步骤 | 本文 |
|------|------|
| 片段 + 清无扩展名 | §1–2 |
| 重启栈 | §3 |
| `pactl` / `amixer`（§4） | §4 |
| 验收 / 试声 | §5 |
---
## 7. deb 打包前建议（存档；当前不执行）
若**未来**恢复 **`kaisa-hdmi-pipewire-fix`** 打包，可参考：
1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。
2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。
3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 [UCM 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)「互斥」一致）。

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

@@ -1,26 +0,0 @@
# 登录会话：在 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 桌面音频）
**权威操作与交付**：**[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)**。
**权威操作与交付**：**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**（UCM2 + HiFi 主交付）、**[reference/ucm2/README.md](reference/ucm2/README.md)**（UCM2 源码说明）。
在此目标下，BMad 更偏 **棕地攻关 + 文档/交付对齐**。常用下一步：

86
next.md
View File

@@ -1,13 +1,83 @@
# next
## LiveCD 验证：UCM（HiFi / Jack-driven）方案
[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)
目标：在 Ubuntu Live 环境里验证 **本仓库的 UCM2 + HiFi** 是否能实现：
- **安装 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 / 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)。
- HDMI **插入才显示为输出**
- HDMI **测试音正常**、切换正常
### 1) Live 原生基线（不装任何东西）
目的：确认 Live 的内核/驱动本身没把 HDMI 搞死（排除“纯驱动级”问题）。
```bash
cd /path/to/chromebox_10th_audio_driver
./scripts/capture-ubuntu-audio-baseline.sh
# … 做改动 / 装 deb …
./scripts/restore-ubuntu-audio-baseline.sh
uname -a
aplay -l
amixer -c0 sset 'IEC958',0 on
amixer -c0 sset 'IEC958',1 on
amixer -c0 sset 'IEC958',2 on
speaker-test -D pulse -c2 -t sine -f 440 -l 2
```
说明：
- 若 `-D pulse` 不通，再用 ALSA 直连（例如 `speaker-test -D hw:0,3 ...`），但**不要在 PipeWire 运行时**直连 `hw:0,N`，否则会遇到 `EBUSY` 或把状态搅乱。
### 2) 在 Live 里临时安装本仓库 UCM 方案
有两种方式，选你方便的：
- **方式 A（推荐）**：把仓库放到另一只 U 盘/同一只启动盘的可写分区里，Live 启动后挂载再执行脚本
- **方式 B**：Live 里 `git clone` 仓库（需要网络）
在仓库根目录执行：
```bash
./scripts/install-kaisa-ucm-overlay.sh
systemctl --user restart wireplumber pipewire pipewire-pulse
```
说明：
- Live 环境通常**没有**你的 pro-audio 方案，所以一般**不需要**跑 `disable-kaisa-pro-audio-wireplumber.sh`（跑了也多半是空操作）。
### 3) 验收 UCM 是否真的生效（关键）
```bash
alsaucm -c sof-rt5682 list _verbs
pactl list cards
```
预期：
- `alsaucm` 应列出 `HiFi`
- `pactl list cards` 的 **配置文件** 里应出现 `HiFi:`
若 `HiFi:` 已出现但活动配置不是 HiFi，手动切一次：
```bash
pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
```
### 4) 验收“插线才出现 HDMI” + 出声
- **拔掉 HDMI**：GNOME 输出列表应只剩模拟（或 HDMI 变不可用）
- **插上 HDMI**：应出现 HDMI1/HDMI2（以及显示器名），并可用测试音验证
终端验收（可选）：
```bash
pactl list short sinks
speaker-test -D pulse -c2 -t sine -f 440 -l 3
```
### 5) 常见坑（Live 特有）
- **user systemd 不完整**：`systemctl --user restart ...` 失败时，注销/重登 Live 会话再试一次
- **误用 ALSA 直连**：PipeWire 运行时对 `hw:0,N` 直连会 `EBUSY`；优先 `-D pulse`
---
如果需要我远程判定“Live 是否真正验证了 UCM 方案”，请贴：
- `pactl list cards`（包含“配置文件”那段）
- 插拔 HDMI 前后 `pactl list short sinks` 的变化

13
reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf
View File

@@ -1,8 +1,17 @@
# Google Kaisa — sof-rt5682 / Intel Kabylake HDMI
# 本文件由 SectionUseCase."HiFi" 引用；须使用顶层 SectionDevice（勿再包一层 SectionVerb），
# 否则 alsaucm 报「no use case device defined」，PipeWire 不会出现 HiFi profile。
# 本文件由 conf.d/sof-rt5682/sof-rt5682.conf 中 SectionUseCase."HiFi" 引用。
# 须有 SectionVerb + Value.TQ（与上游 ucm2 中 Intel/*/HiFi.conf 一致），PipeWire/ACP 才会把
# 「HiFi」注册为 pactl 可见的 card profile；仅有顶层 SectionDevice 时 alsaucm 可能仍列出
# HiFi，但活动配置会卡在 off、配置列表只剩 off + pro-audio。
# HDMI：device 2/3/4；JackControl + IEC958 numid 与本机 amixer 对齐。
# SectionVerb 内勿使用 disdevall：部分 SOF 卡会导致 PipeWire 不把 HiFi 注册进 EnumProfile。
SectionVerb {
Value {
TQ "HiFi"
}
}
SectionDevice."Port1" {
Comment "Analog (Port1)"

8
reference/ucm2/README.md
View File

@@ -1,15 +1,15 @@
# Kaisa UCM2 overlay（`sof-rt5682`）
本目录为 **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)**）。
本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同；主交付文档见 **[UCM 操作文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）。
## 布局
| 路径（相对 `ucm2/` 根） | 说明 |
|-------------------------|------|
| `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：**`SectionVerb` + `Value.TQ "HiFi"`** + **`Port1` / HDMI1/2/3**，**JackControl** + **`IEC958',N`**（供 PipeWire 注册 **`HiFi:`** profile） |
上游 **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)）。
上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与 **本 overlay** 可能冲突 — 优先 **合并上游** 或 **改名/拆包**（与 [UCM 文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) 的互斥说明一致）。
## 手工安装（调试）
@@ -46,7 +46,7 @@ alsaucm -c sof-rt5682 set _verb HiFi list _devices
插拔 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)「一键环境验证」。
（可选）环境采集脚本已从仓库移除；建议直接按 **[UCM 操作文档](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 的验收命令（`alsaucm` / `pactl` / `wpctl` / `amixer`）逐项核对。
## 实机验收表（勾选）

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

@@ -1,240 +0,0 @@
#!/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: 完成。"

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

@@ -1,128 +0,0 @@
#!/usr/bin/env bash
# 在安装 kaisa-hdmi-pipewire-fix 或其它大改前，采集「Ubuntu / 当前机」音频基线并落盘。
# 输出目录默认：audio_topology/baseline-stash/<时间戳>_<hostname>/
# 用法：./scripts/capture-ubuntu-audio-baseline.sh [输出目录]
# 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md「基线备份与恢复」
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
STAMP="$(date +%Y%m%d_%H%M%S)_$(hostname)"
if [[ -n "${1:-}" ]]; then
STASH="$(realpath "$1")"
else
STASH="${REPO_ROOT}/audio_topology/baseline-stash/${STAMP}"
fi
mkdir -p "$STASH/backup/root"
write_manifest() {
local mf="$STASH/manifest.txt"
{
echo "# capture-ubuntu-audio-baseline"
echo "created_iso: $(date -Iseconds)"
echo "hostname: $(hostname)"
echo "stash_dir: $STASH"
echo ""
echo "## uname"
uname -a
echo ""
echo "## dpkg (相关包)"
dpkg -l 2>/dev/null | grep -E '^(ii|rc)\s+(alsa-ucm-conf|wireplumber|pipewire|pipewire-pulse|kaisa-hdmi-pipewire-fix)\s' || true
echo ""
if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
echo "## kaisa-hdmi-pipewire-fix: installed"
dpkg -s kaisa-hdmi-pipewire-fix 2>/dev/null | grep -E '^(Package|Version|Status):' || true
else
echo "## kaisa-hdmi-pipewire-fix: not installed"
fi
echo ""
echo "## deb 相关路径（存在性与 sha256）"
} >"$mf"
local paths=(
/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf
/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf
/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf
)
local p
for p in "${paths[@]}"; do
if [[ -e "$p" ]]; then
echo "PATH $p exists=yes" >>"$mf"
if [[ -f "$p" ]]; then
sha256sum "$p" >>"$mf" 2>/dev/null || echo "(sha256sum failed)" >>"$mf"
fi
else
echo "PATH $p exists=no" >>"$mf"
fi
done
echo "" >>"$mf"
echo "## /usr/share/doc/kaisa-hdmi-pipewire-fix/" >>"$mf"
if [[ -d /usr/share/doc/kaisa-hdmi-pipewire-fix ]]; then
ls -la /usr/share/doc/kaisa-hdmi-pipewire-fix >>"$mf" 2>&1 || true
else
echo "(目录不存在)" >>"$mf"
fi
}
backup_vendor_ucm() {
local src="/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf"
if [[ -f "$src" ]]; then
install -D -m0644 "$src" "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf"
echo "已备份 vendor UCM: $src -> backup/root/..."
fi
}
backup_user_wireplumber() {
local d="${HOME}/.config/wireplumber/wireplumber.conf.d"
local names=()
if [[ -d "$d" ]]; then
shopt -s nullglob
local f
for f in "$d"/*; do
[[ -e "$f" ]] || continue
local b
b="$(basename "$f")"
if [[ "$b" == *kaisa* ]] || [[ "$b" == 50-kaisa* ]]; then
names+=("$b")
fi
done
fi
if ((${#names[@]} > 0)); then
tar -C "$d" -czf "$STASH/user-wireplumber-conf.tar.gz" "${names[@]}"
echo "已打包用户 WirePlumber 片段: ${names[*]} -> user-wireplumber-conf.tar.gz"
else
echo "(未找到 ~/.config/wireplumber/... 下含 kaisa 的片段，跳过 user-wireplumber-conf.tar.gz)"
fi
}
pack_system_overlay() {
if [[ -f "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" ]]; then
tar -C "$STASH/backup/root" -czf "$STASH/system-overlay.tar.gz" \
usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf
echo "已生成 system-overlay.tar.gz（可配合 restore 还原安装 deb 前的 vendor sof-rt5682.conf）"
else
echo "(未备份 vendor sof-rt5682.conf，不生成 system-overlay.tar.gz)"
fi
}
write_manifest
backup_vendor_ucm
backup_user_wireplumber
pack_system_overlay
TOPO="$STASH/topology.txt"
echo "正在调用 collect_linux_audio_topology.sh -> $TOPO"
bash "${REPO_ROOT}/audio_topology/collect_linux_audio_topology.sh" "$TOPO"
echo ""
echo "========== 基线已写入: $STASH =========="
echo " manifest.txt — 包状态与 deb 路径清单"
echo " topology.txt — 完整音频拓扑"
echo " system-overlay.tar.gz — 若存在：vendor sof-rt5682.conf 快照"
echo " user-wireplumber-conf.tar.gz — 若存在：用户 kaisa WirePlumber 片段"
echo ""
echo "恢复至「尽量接近本次采集时」的系统文件状态："
echo " ./scripts/restore-ubuntu-audio-baseline.sh $STASH"
echo ""
echo "若曾启用 §4.3 user systemd 自动 restore，恢复基线前可先禁用该 user 单元（见 OPERATION）。"

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

@@ -1,51 +0,0 @@
#!/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
View File

@@ -1,52 +0,0 @@
#!/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"

4
scripts/remove-kaisa-ucm-overlay.sh
View File

@@ -2,7 +2,7 @@
# 卸载本仓库安装的 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
@@ -51,5 +51,5 @@ fi
echo "完成。sof-rt5682 将不再使用本仓库的 HiFi UCM（HDMI1/2/3 等端口名来自该 overlay）。"
if [[ "$removed" -eq 1 ]]; then
echo "建议：走 pro-audio 时在仓库根执行 ./scripts/apply-kaisa-pro-audio.sh"
echo "提示：卸载后将回到发行版默认音频配置；如需继续使用 HDMI，请按 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md 重新安装。"
fi

80
scripts/restore-ubuntu-audio-baseline.sh
View File

@@ -1,80 +0,0 @@
#!/usr/bin/env bash
# 将系统尽量恢复到某次 capture-ubuntu-audio-baseline 采集时的「安装 deb 前」文件状态。
# 典型：purge kaisa-hdmi-pipewire-fix → reinstall alsa-ucm-conf → 可选解压备份 tar。
# 用法：./scripts/restore-ubuntu-audio-baseline.sh [基线目录]
# 若不传参数，使用 audio_topology/baseline-stash/ 下最近修改的子目录。
# 需要：sudo（apt、解压到 /）；建议在桌面会话下执行以便重启 PipeWire。
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
resolve_stash() {
if [[ -n "${1:-}" ]]; then
realpath "$1"
return
fi
local latest
latest="$(ls -td "${REPO_ROOT}/audio_topology/baseline-stash"/*/ 2>/dev/null | head -1 || true)"
if [[ -z "$latest" ]]; then
echo "未找到基线目录。请先运行: ${REPO_ROOT}/scripts/capture-ubuntu-audio-baseline.sh" >&2
exit 1
fi
realpath "${latest%/}"
}
STASH="$(resolve_stash "${1:-}")"
if [[ ! -f "$STASH/manifest.txt" ]]; then
echo "不是有效基线目录（缺少 manifest.txt）: $STASH" >&2
exit 1
fi
echo "========== 使用基线: $STASH =========="
echo "manifest 创建于:"
head -5 "$STASH/manifest.txt"
echo ""
if ! command -v sudo &>/dev/null; then
echo "需要 sudo 以执行 apt。" >&2
exit 1
fi
if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
echo ">>> apt purge kaisa-hdmi-pipewire-fix"
sudo apt purge -y kaisa-hdmi-pipewire-fix
else
echo "(未安装 kaisa-hdmi-pipewire-fix，跳过 purge)"
fi
echo ">>> apt install --reinstall alsa-ucm-conf"
sudo apt install --reinstall -y alsa-ucm-conf
if [[ -f "$STASH/system-overlay.tar.gz" ]]; then
echo ">>> 解压 system-overlay.tar.gz -> /（覆盖 vendor sof-rt5682.conf，与 reinstall 通常等价）"
sudo tar -xzf "$STASH/system-overlay.tar.gz" -C /
else
echo "(无 system-overlay.tar.gz，仅依赖 alsa-ucm-conf reinstall)"
fi
if [[ -f "$STASH/user-wireplumber-conf.tar.gz" ]]; then
echo ">>> 解压 user-wireplumber-conf.tar.gz -> ${HOME}/.config/wireplumber/wireplumber.conf.d/"
mkdir -p "${HOME}/.config/wireplumber/wireplumber.conf.d"
tar -xzf "$STASH/user-wireplumber-conf.tar.gz" -C "${HOME}/.config/wireplumber/wireplumber.conf.d"
echo "已恢复用户 WirePlumber 片段。"
else
echo "(无 user-wireplumber-conf.tar.gz，跳过用户配置)"
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 2>/dev/null || {
echo "（user 会话重启 pipewire 失败，请手动重登或重启）" >&2
}
else
echo "（无可用 user systemd 会话，请登录图形界面后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）"
fi
echo ""
echo "========== 恢复步骤已完成 =========="
echo "若曾启用登录自动 restore（user systemd），恢复前可先禁用 kaisa-hdmi-iec958-pipewire 单元（见 OPERATION §4.3 / §4.5）。"
echo "建议核对: pactl list cards | head -40 ; aplay -l"

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

@@ -1,21 +0,0 @@
#!/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
View File

@@ -1,287 +0,0 @@
#!/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
View File

@@ -1,108 +0,0 @@
#!/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

10
wireplumber/main.lua.d/60-kaisa-ucm.lua
View File

@@ -2,7 +2,13 @@
-- WirePlumber 0.4.x: appended after stock alsa rules.
--
-- 若仅启用 use-ucm 而不固定 profile，栈常会默认选 stereo-fallback，界面只剩模拟/耳机，HDMI 消失。
-- 固定为 UCM 中 SectionUseCase 名 "HiFi"；并关闭 auto-profile，避免抢回 stereo-fallback。
--
-- 重要（policy-device-profile.lua / findBestProfile）：若下面 KAISA_WP_DEVICE_PROFILE 设为 "HiFi"，
-- 但 PipeWire 的 EnumProfile 里还没有名为 HiFi 的条目（pactl「配置文件」仅有 off / pro-audio），
-- WirePlumber 无法匹配 device.profile，最终会把活动配置留在 off，且 pactl set-card-profile HiFi
-- 报「无此实体」。此时请保持 "pro-audio" 先恢复输出；待 install-kaisa-ucm-overlay + 重启后 pactl 已出现
-- HiFi: 时，再把本变量改为 "HiFi" 并重启用户 pipewire 栈。
local KAISA_WP_DEVICE_PROFILE = "pro-audio" -- 或 "HiFi"
table.insert(alsa_monitor.rules, {
matches = {
@@ -15,6 +21,6 @@ table.insert(alsa_monitor.rules, {
["api.alsa.use-ucm"] = true,
["api.acp.auto-profile"] = false,
["api.acp.auto-port"] = true,
["device.profile"] = "HiFi",
["device.profile"] = KAISA_WP_DEVICE_PROFILE,
},
})