docs(op): refine pro-audio verification + snapshot guidance
Clarify sink/ELD/Jack mapping pitfalls, add drain-timeout troubleshooting, and document a baseline snapshot workflow for repeatable HDMI audio verification. Debian packaging is explicitly deferred until validation is complete. Made-with: Cursor
This commit is contained in:
@@ -2,6 +2,8 @@
|
||||
|
||||
**适用**：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，先选哪条）
|
||||
@@ -23,7 +25,7 @@
|
||||
|------|------|
|
||||
| 设置里只有 **「立体声」**、**`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** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
|
||||
| **`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`**。 |
|
||||
|
||||
---
|
||||
@@ -115,10 +117,18 @@ pactl get-default-sink
|
||||
pactl list short sinks
|
||||
```
|
||||
|
||||
插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。
|
||||
插入 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 设备：
|
||||
|
||||
```bash
|
||||
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` / 输入输出错误**。
|
||||
|
||||
```bash
|
||||
speaker-test -D pulse -c2 -t sine -f 440 -l 3
|
||||
```
|
||||
@@ -215,13 +225,15 @@ amixer -c0 sset 'IEC958',0 on
|
||||
|
||||
### 4.3 登录自动恢复（规划中）
|
||||
|
||||
**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为稳定工具随 **`kaisa-hdmi-pipewire-fix`** 发布。
|
||||
**根因**：**`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`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 结构，**`ExecStart`** 指向你本机的 shell 片段或脚本）。
|
||||
|
||||
### 4.4 Debian 包（系统级交付）
|
||||
### 4.4 Debian 包（系统级交付，暂缓）
|
||||
|
||||
仓库 **`debian/`** 提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
|
||||
**说明**：在技术验证未收尾前，**不必**关注本节；优先完成 §1–§3、UCM 与基线脚本。**验证稳定后**再决定是否维护 **`debian/`** 与 **`kaisa-hdmi-pipewire-fix`**。
|
||||
|
||||
仓库 **`debian/`** 可提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
|
||||
|
||||
```bash
|
||||
./scripts/build-deb.sh
|
||||
@@ -284,6 +296,24 @@ cd /path/to/chromebox_10th_audio_driver
|
||||
|
||||
**若曾自建** §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 可出声）”（勿入库）**：
|
||||
|
||||
- 基线目录：`audio_topology/baseline-stash/20260407_235227_jack-Kaisa/`
|
||||
- 采集时间：`2026-04-07T23:52:31+08:00`
|
||||
- 采集命令：`./scripts/capture-ubuntu-audio-baseline.sh`
|
||||
- 快速锚点（供对照）：`IEC958 numid=14/20/26 = on`；ELD/Jack/默认 sink 等以该基线的 `topology.txt` 与采集时现场为准（建议同时记录 `pactl get-default-sink` 与 `wpctl inspect @DEFAULT_AUDIO_SINK@`）
|
||||
|
||||
---
|
||||
|
||||
## 5. 参考链接
|
||||
|
||||
Reference in New Issue
Block a user