Files

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

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

2026-04-08 15:22:45 +08:00

3.4 KiB

Raw Blame History

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）

检查与打开（建议三路全开，避免误判）：

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

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

3.4 KiB Raw Blame History Unescape Escape