# 操作：Kaisa（sof-rt5682）Ubuntu 上 HDMI 出声与 WirePlumber 固化

**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。

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

**相关**：内核侧 HDMI / SOF 层次见 [CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md](CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md)。

---

## 1. 现象与原因（摘要）

| 现象 | 说明 |
|------|------|
| 设置里只有 **「立体声」**、**`pactl list short sinks` 仅 1 个** | 声卡 profile 为 **`stereo-fallback`**，未暴露多路 HDMI PCM。 |
| GNOME **「测试扬声器」** 无图标 | HDMI / Pro Audio 常无 Front L/R 声道名，**界面不可用**不代表 ALSA 无声；用 **`speaker-test` / `paplay`** 测。 |
| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
| **`IEC958',N` 与 `amixer sget 'IEC958 Playback Switch'`** | 本机简单控件名为 **`IEC958',0`** 等；用 **`scontrols \| grep IEC958`** 核对。 |

---

## 2. 固化方案：WirePlumber `wireplumber.conf.d`

在 **`~/.config/wireplumber/wireplumber.conf.d/`** 下放片段（**文件名以 `.conf` 结尾**），实现：

1. **强制 `device.profile = pro-audio`**：始终暴露 **Pro / Pro 2 / Pro 3 / Pro 4**（与 `aplay -l` 中 **Port1 / HDMI1/2/3** 对应）。
2. **`monitor.alsa.rules` 提高 HDMI 相对模拟口的 `priority.session`**：HDMI sink **可用且优先级更高** 时，WirePlumber 倾向将其设为 **默认输出**；拔出后回退到模拟（以本机行为为准）。

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

- [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)

安装命令示例：

```bash
mkdir -p ~/.config/wireplumber/wireplumber.conf.d
cp /path/to/chromebox_10th_audio_driver/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
   ~/.config/wireplumber/wireplumber.conf.d/
systemctl --user restart wireplumber pipewire pipewire-pulse
```

**优先级（示例文件内）**：`pro-output-0`（模拟）**1000**；`pro-output-3` **1090**；`pro-output-4` **1095**；`pro-output-2`（HDMI1）**1100**。多路 HDMI 同时存在时 **HDMI1 优先**；若你常接 **HDMI2/3**，可把对应 `node.name` 的优先级调到 **高于 1100**。

**PCI 路径变化**：若 `lspci` 中音频 BDF 不是 **`0000:00:1f.3`**，用以下命令查看实际 **`device.name` / `node.name`** 并替换 conf 中的字符串：

```bash
pactl list cards
pactl list short sinks
```

**WirePlumber 大版本升级**：语法可能变化，见 [WirePlumber migration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html)。

---

## 3. 验证

```bash
pactl list cards
```

**活动配置** 应为 **`pro-audio`**。

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

插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。

ALSA 直连测试（不经过 PipeWire 策略）：

```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 …`）作次级方案。

---

## 5. 参考链接

- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority)