chromebox_10th_audio_driver/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

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

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

当前阶段：以 本机手工配置 + 文档/脚本复现 完成技术验证（pro-audio / UCM、插拔、多显示器等）。Debian 包（debian/、kaisa-hdmi-pipewire-fix）暂缓：待验证结论稳定后再考虑打包与分发，本文 §4.4 仅作预留参考。

---

路径选择（pro-audio 与 UCM，先选哪条）

目标	做法
先确认 HDMI 能否出声（对照实验）	pro-audio：把 50-kaisa-sof-rt5682-hdmi.conf 放到 ~/.config/wireplumber/wireplumber.conf.d/（文件名以 .conf 结尾），systemctl --user restart wireplumber pipewire pipewire-pulse，再 pactl set-card-profile <卡名> pro-audio、pactl set-default-sink 指到 pro-output-2（或当前 Jack 对应路），按 §4.2 打开对应 IEC958',N，最后 paplay / speaker-test -D pulse。
长期「无 Jack 不误导」、桌面端口模型	UCM：安装 overlay 后 移走 上述 WirePlumber 片段，依赖 WirePlumber 按 UCM 启用 HDMI1/2/3；与 pro-audio 互斥（见下 §2.3）。

建议顺序：先走 pro-audio 验证硬件与 PipeWire 路由；有声之后再决定继续 修 UCM（例如消除 Failed to enable ucm device HDMI*）或 长期保留 pro-audio。「自动屏蔽未插入的 HDMI」 依赖 UCM 或自写策略，见 §2.3，应在 HDMI 已能出声 之后再做。

若已安装 kaisa-hdmi-pipewire-fix 却未卸载：deb 会把 UCM2 装入 /usr/share/alsa/ucm2/（如 GoogleKaisa）。仅恢复 50-kaisa-…conf 时，WirePlumber 仍会按 UCM 做端口可用性，未插线的 HDMI 可能继续不可用 / 像被「隐藏」，与「全开 pro-audio 对照」不一致。要做干净 pro-audio 基线：先 sudo apt purge kaisa-hdmi-pipewire-fix，再按上文复制 WirePlumber 片段。系统自带的 alsa-ucm-conf 仍可能提供通用 sof-rt5682 配置；若仍异常，以本机 alsaucm / pactl list cards 为准。

---

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 提高 HDMI 相对模拟口的 priority.session：HDMI sink 可用且优先级更高 时，WirePlumber 倾向将其设为 默认输出；拔出后回退到模拟（以本机行为为准）。

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

• 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

优先级（示例文件内）：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 中的字符串：

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 查看与切换。若期望 插拔与可用性严格对应、并在设置里以「端口」形式出现，长期更依赖 ALSA UCM（alsa-ucm-conf 等） 与栈的集成，而非仅 WirePlumber 静态规则。

与「无 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 驱动路由，让 未接线的 HDMI 不成为可选输出（更接近 Windows/桌面对「无效口」的处理）；代价是与 强制 pro-audio 一次性拉满多路 的路线不同，需单独调通 Kaisa 的 UCM 与 IEC958（详见 reference/ucm2/README.md 与 §2.3 互斥说明）。
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 路线或自定义策略，而不是假定 单靠一个与当前 50-*.conf 同类的静态片段 即可覆盖。

UCM 模式 vs pro-audio 模式（互斥）

模式	做法	适用
pro-audio（§2 过渡）	50-kaisa-sof-rt5682-hdmi.conf 强制 device.profile = pro-audio + IEC958（pactl/amixer，§4.2）	快速多路 pro-output-*、先保证出声
UCM（产品目标）	安装 reference/ucm2/ 至 /usr/share/alsa/ucm2/（或 apt install kaisa-hdmi-pipewire-fix），让 ACP 按 JackControl 暴露路由	无 Jack 不误导、更接近桌面「端口」模型

不要同时使用：启用 UCM overlay 时，请 移走或禁用 ~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf 以及 系统级 /etc/wireplumber/... 中同类片段（若由 deb 安装，见 §4.4 UCM 优先时说明），否则 强制 pro-audio 仍会盖过 UCM 的 profile 语义。改完后 systemctl --user restart wireplumber pipewire pipewire-pulse。

验证 UCM 是否生效：pactl list cards 中活动配置宜为 HiFi 等 UCM 定义的 profile，而非长期锁在 pro-audio（以本机 pactl 为准）。

UCM 模式下 HDMI 无声（IEC958）：与 §4.2 相同根因——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. 再按 §4.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。

自动化（未随 deb 提供）：登录后自动 set-card-profile / set-default-sink / 开 IEC958、以及 按 Jack 轮询默认 sink 等，尚未在本仓库验证完毕，kaisa-hdmi-pipewire-fix ≥0.3.0 仅装 UCM2 + WirePlumber 片段。若你自行编写 user systemd，勿在 UCM 模式下执行会强制 pro-audio 的命令。插入 HDMI 时是否弹出输出选择 由 桌面/会话 决定。

---

3. 验证

pactl list cards

活动配置 应为 pro-audio。

pactl get-default-sink
pactl list short sinks

插入 HDMI 后，默认 sink 以本机为准：可能是 ...pro-output-2（界面常标 Pro 2 / HDMI1），也可能是 pro-output-3 / pro-output-4，取决于物理口、显示器与 PipeWire 优先级。不要仅凭 HDMI/DP,pcm=N Jack 或某条 eld#2.X 就断定必须用 pro-output-N；用下面命令确认当前默认输出实际绑定的 ALSA 设备：

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

例如 api.alsa.path = "hw:0,2" 即当前声音送往 ALSA device 2（常对应 Pro 2）。

出声测试（推荐）：桌面默认用 PipeWire 时，声卡常被其占用；此时 speaker-test -D plughw:0,2 会报 打开错误: -16（设备或资源忙，EBUSY），属正常现象。请先 pactl set-default-sink 指到目标 HDMI sink，再经 Pulse 兼容设备 测试：

若 paplay 报「排空流失败：超时」、且 pactl list short sink-inputs 为空：该路 sink 可能未能正常完成播放（或默认 sink 并非你以为的那路）。请依次 pactl set-default-sink …pro-output-2/3/4 配合 §4.2 打开对应 IEC958，并用 speaker-test -D pipewire 复测；同时查看 journalctl --user -u pipewire 是否出现 set_hw_params / 输入输出错误。

speaker-test -D pulse -c2 -t sine -f 440 -l 3

或 paplay /usr/share/sounds/alsa/Front_Center.wav（同样走当前默认 sink）。

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 片段若仍在，常见原因不是 profile 丢失，而是 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 名以本机为准）：

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   # 或按 §4.2 对 pcm=3/4 开 IEC958',1 / ',2

再用 speaker-test -D pulse（或 paplay）确认经 PipeWire 的默认 sink 是否有声；-D plughw:… 在 PipeWire 占用声卡时会出现 EBUSY (-16)。

登录自动执行（可选，自建）：自行编写 user systemd oneshot（pactl/amixer），After=pipewire-pulse.service，必要时 ExecStartPre=/bin/sleep 2。仓库 systemd-user/kaisa-hdmi-iec958-pipewire.service 仅为示例，需自备 ExecStart 所指可执行文件（deb 不提供）。

4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声

常见原因

1. 默认 sink 是「粘住」的：GNOME / 会话会记住 pactl get-default-sink；WirePlumber 又用 priority.session 把某一路（示例里是 pro-output-2）抬成首选。换线不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 pro-output-3 / pro-output-4。
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 的那一路。

另见：若 journalctl --user -u wireplumber 有 Failed to enable ucm device HDMI2（或 HDMI1 / HDMI3），且 pipewire 仅对 HiFi__hw_sofrt5682_3__sink（或 _2__ / _4__）报错，则为 UCM SectionDevice 启用失败（与 reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf 中 HDMI1/2/3 对应 device 2/3/4 一致）。宜 换插到另一 HDMI 物理口 或 alsaucm -c sof-rt5682 set _verb HiFi set _device … 单独验证；详见 next.md（单命令：安装 + 诊断）。

4.3 登录自动恢复（规划中）

根因：IEC958',0（pcm=2）被关 → HDMI 无声（PipeWire 可看似正常）；完整 「切 pro-audio + 默认 HDMI sink + 开 IEC958」 自动化尚未作为随仓库分发的稳定工具（deb 亦暂缓，见文首说明）。

当前：请用 §4.1 / §4.2 手动命令；需要登录自启时，自行编写 user systemd（可参考 systemd-user/kaisa-hdmi-iec958-pipewire.service 结构，ExecStart 指向你本机的 shell 片段或脚本）。

4.4 Debian 包（系统级交付，暂缓）

说明：在技术验证未收尾前，不必关注本节；优先完成 §1–§3、UCM 与基线脚本。验证稳定后再决定是否维护 debian/ 与 kaisa-hdmi-pipewire-fix。

仓库 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 说明；可选打包 OPERATION）。

0.2.x 及更早 曾附带 kaisa-restore-* 与 user systemd 单元；0.3.0 起移除，直至手工验证与自动化策略定型。

UCM 优先时：按上文 「UCM 模式 vs pro-audio 模式」 移走 50-kaisa-…，避免与 强制 pro-audio 叠用。发布前请改 debian/control、debian/changelog、debian/copyright 中的维护者与许可证说明。

说明

• 更广分发：可将该 deb 放入自建 APT 仓库 / PPA；更长远的修复仍是 ALSA UCM / 上游 在适用机型上 默认打开 IEC958（与发行版/上游沟通，不在本仓库另文维护）。

4.5 基线备份与恢复（Ubuntu 默认 / 安装 deb 前状态）

目的：在首次安装 kaisa-hdmi-pipewire-fix 或做大改之前，把当前机的音频相关路径与诊断落盘，并在后续工作中可尽量恢复到该状态。

为何 reinstall alsa-ucm-conf：本 deb 会向 /usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf 安装与 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

生成文件通常包括：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 / REPRO_*.md、UCM 与 WirePlumber 源码；在文档中写一句当时验证要点（例如 pro-audio + 默认 Pro 2、hw:0,2）。debian/** 待完整验证后再纳入常规提交	是（deb 相关目录暂缓）

建议在 OPERATION 或提交说明里记一行「事实锚点」（便于以后对照）：pactl get-default-sink 的 sink 名、wpctl inspect @DEFAULT_AUDIO_SINK@ 中的 api.alsa.path、以及 amixer -c0 cget numid=14,20,26 中对应 IEC958 是否为 on。

本机最新一次“技术验证过程快照（含已验证 Pro 2/Pro 3 HDMI 可出声）”（勿入库）：

• 当前冻结快照（推荐用于 ./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）
• 快速锚点（供对照）：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）