chromebox_10th_audio_driver/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md

操作：Kaisa（sof-rt5682）ProAudio + HDMI（WirePlumber 固化）

主路线：PipeWire pro-audio；默认 pro-output-0（模拟） / pro-output-2（外接 HDMI）。UCM / HiFi 为 可选互斥路线，见 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 文档）。

主路线上的硬冲突（重点）：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 复制到 ~/.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	默认 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	仅卸载历史 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	删除 ~/.local/state/wireplumber/default-profile 里 cml_rt5682 行，避免 stereo-fallback 持久化顶掉 50-kaisa；apply 已内置调用，见 §4.1b。
scripts/kaisa-reapply-pro-audio-session.sh	先 strip 同上，再 pro-audio + 默认 sink + IEC958（登录 oneshot）；见 §4.1b、kaisa-pro-audio-reapply.service。
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。找不到则报错并列出现有目录。

示例（在仓库根、登录用户图形会话下）：

./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；不要与上表同时启用。

---

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

安装命令示例：

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 中的字符串：

pactl list cards
pactl list short sinks

WirePlumber 大版本升级：语法可能变化，见 WirePlumber migration。

与系统「声音设置」里输出列表的预期

本文 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），而非仅 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、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 文档 或自定义策略，而不是假定 单靠 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。

不要同时使用：走 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。

pactl list cards

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。

wpctl inspect @DEFAULT_AUDIO_SINK@ | grep -E 'api\.alsa\.path|node\.name|alsa\.device'

出声测试（推荐）：PipeWire 占用声卡时 speaker-test -D plughw:0,2 常 EBUSY (-16)，属正常。请经 Pulse 兼容 设备测试：

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 第二列）：

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

pw-play --target alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
  /usr/share/sounds/alsa/Front_Center.wav

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 的排障会话）：

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。

先快速自检：

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 是否仍存在，然后：

systemctl --user restart wireplumber pipewire pipewire-pulse

若已是 pro-audio 但仍无声，可 手动 设默认 sink 并开 IEC958（卡名、sink 名以本机为准）。已验证默认：HDMI 用 pro-output-2 + IEC958',0；仅模拟用 pro-output-0（无需 IEC958）。

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-* 像「出现一下又没了」。

当场核对：

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，然后 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	先 清 default-profile 中 cml_rt5682 行，再 pro-audio / 默认 sink / IEC958；约 6 秒后再执行一遍。
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 仍为占位示例（需自备 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）；部分显示器会把当前选中输入的声音播出来，容易混淆。

建议自检

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 为准）：

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）：

amixer -c0 sget 'IEC958',0

若为 [off]，执行：

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 与 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 结构，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（purge + reinstall alsa-ucm-conf）。

仓库 debian/ 中曾有原生包 kaisa-hdmi-pipewire-fix（Architecture: all）草稿。若日后恢复构建，在源码根目录可执行：

./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 无法遍历家目录）：

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）；依赖 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 移走 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，避免大块采集误入版本库）：

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 的片段）。

一键恢复（不传参数时使用 最近一次基线目录）：

./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
• 设备优先级示例（monitor.alsa.rules）