# 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 可用性生成端口/路由

不同桌面版本的展示可能略有差异，但 **“插入才可用/可选”** 是此路线的核心目标。