Initial commit
This commit is contained in:
jack
9
docs/INDEX.md
Normal file
9
docs/INDEX.md
Normal file
@@ -0,0 +1,9 @@
|
||||
# 文档索引
|
||||
|
||||
与根 [README.md](../README.md) 相同：**仅**下列为当前维护文档。
|
||||
|
||||
| 文档 | 说明 |
|
||||
| ---- | ---- |
|
||||
| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | 主操作文档 |
|
||||
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 复现与验收 |
|
||||
| [README.md](README.md) | 本目录说明 |
|
||||
12
docs/README.md
Normal file
12
docs/README.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# `docs/` 说明
|
||||
|
||||
本目录仅保留 **已实机验证** 的 PipeWire / deb 技术路线：
|
||||
|
||||
| 文档 | 内容 |
|
||||
| ---- | ---- |
|
||||
| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | WirePlumber、`50-kaisa-sof-rt5682-hdmi.conf`、pro-audio / UCM、deb、基线采集 |
|
||||
| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 安装与手动验收 |
|
||||
|
||||
附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。
|
||||
|
||||
仓库根 [README.md](../README.md) · 路径表 [REPO_INDEX.md](../REPO_INDEX.md)。
|
||||
292
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
Normal file
292
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 操作：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，先选哪条）
|
||||
|
||||
| 目标 | 做法 |
|
||||
|------|------|
|
||||
| **先确认 HDMI 能否出声（对照实验）** | **pro-audio**：把 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/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** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
|
||||
| **`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`](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)。
|
||||
|
||||
### 与系统「声音设置」里输出列表的预期
|
||||
|
||||
本文 **`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](../../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/](../../reference/ucm2/README.md)** 至 **`/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. 验证
|
||||
|
||||
```bash
|
||||
pactl list cards
|
||||
```
|
||||
|
||||
**活动配置** 应为 **`pro-audio`**。
|
||||
|
||||
```bash
|
||||
pactl get-default-sink
|
||||
pactl list short sinks
|
||||
```
|
||||
|
||||
插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。
|
||||
|
||||
**出声测试（推荐）**：桌面默认用 PipeWire 时，声卡常被其占用；此时 **`speaker-test -D plughw:0,2`** 会报 **打开错误: -16（设备或资源忙，EBUSY）**，属正常现象。请先 **`pactl set-default-sink`** 指到目标 HDMI sink，再经 **Pulse 兼容设备** 测试：
|
||||
|
||||
```bash
|
||||
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`** 的排障会话）：
|
||||
|
||||
```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 …`）作次级方案。
|
||||
|
||||
### 4.1 重启后又没声
|
||||
|
||||
WirePlumber 片段若仍在，常见原因不是 profile 丢失，而是 **GNOME/会话记住了旧的默认 sink**、**冷启动时 HDMI Jack 尚未就绪**、或 **应用仍指向已不存在的 sink**。
|
||||
|
||||
**先快速自检：**
|
||||
|
||||
```bash
|
||||
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`** 是否仍存在，然后：
|
||||
|
||||
```bash
|
||||
systemctl --user restart wireplumber pipewire pipewire-pulse
|
||||
```
|
||||
|
||||
若已是 **`pro-audio`** 但仍无声，可 **手动** 设默认 sink 并开 IEC958（卡名、sink 名以本机为准）：
|
||||
|
||||
```bash
|
||||
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`](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）；部分显示器会把当前选中输入的声音播出来，容易混淆。
|
||||
|
||||
**建议自检**
|
||||
|
||||
```bash
|
||||
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`** 为准）：
|
||||
|
||||
```bash
|
||||
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）：
|
||||
|
||||
```bash
|
||||
amixer -c0 sget 'IEC958',0
|
||||
```
|
||||
|
||||
若为 **`[off]`**，执行：
|
||||
|
||||
```bash
|
||||
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](../../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](../../next.md)**（单命令：安装 + 诊断）。
|
||||
|
||||
### 4.3 登录自动恢复（规划中）
|
||||
|
||||
**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为稳定工具随 **`kaisa-hdmi-pipewire-fix`** 发布。
|
||||
|
||||
**当前**：请用 §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 包（系统级交付）
|
||||
|
||||
仓库 **`debian/`** 提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建：
|
||||
|
||||
```bash
|
||||
./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`** 无法遍历家目录）：
|
||||
|
||||
```bash
|
||||
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](../../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`**，避免大块采集误入版本库）：
|
||||
|
||||
```bash
|
||||
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 的片段）。
|
||||
|
||||
**一键恢复**（不传参数时使用 **最近**一次基线目录）：
|
||||
|
||||
```bash
|
||||
./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。
|
||||
|
||||
---
|
||||
|
||||
## 5. 参考链接
|
||||
|
||||
- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
|
||||
- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority)
|
||||
155
docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
Normal file
155
docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现）
|
||||
|
||||
**目的**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」，用于打包前验收。
|
||||
|
||||
**相关**：deb 安装内容见 [OPERATION_PipeWire_Kaisa_HDMI.md](OPERATION_PipeWire_Kaisa_HDMI.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。
|
||||
|
||||
### 常用检查（sinks / 设备，不依赖 pulseaudio-utils）
|
||||
|
||||
| 用途 | 命令 |
|
||||
|------|------|
|
||||
| **总览**：声卡、**Sinks**（输出）、**Sources**（输入）、默认 sink 标记 `*` | `wpctl status` |
|
||||
| 某条 sink 详情（含 `node.name`、`device.profile.name`） | `wpctl inspect <sink 数字 id>`，如 `wpctl inspect @DEFAULT_AUDIO_SINK@` |
|
||||
| 若已安装 **pulseaudio-utils** | `pactl list short sinks`、`pactl get-default-sink`、`pactl list cards` |
|
||||
|
||||
说明：**Sinks** 前的数字 id **重启栈后会变**，以当次 `wpctl status` 为准；**`wpctl set-default <id>`** 只填 **Sink** 的 id，**不要**与 **Devices**（声卡）混淆。
|
||||
|
||||
---
|
||||
|
||||
## 0. 可选：回到安装 deb / 改配置前的基线
|
||||
|
||||
若曾运行过 `capture-ubuntu-audio-baseline.sh`：
|
||||
|
||||
```bash
|
||||
cd /path/to/chromebox_10th_audio_driver
|
||||
./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/
|
||||
```
|
||||
|
||||
或仅在本机清掉用户片段后重启栈（自行备份）：
|
||||
|
||||
```bash
|
||||
mv -f ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf \
|
||||
~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf.disabled 2>/dev/null || true
|
||||
systemctl --user restart pipewire pipewire-pulse
|
||||
sleep 1
|
||||
systemctl --user restart wireplumber
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 与 deb 一致：安装 WirePlumber 片段
|
||||
|
||||
**deb 安装位置**：`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`（需 root）。
|
||||
|
||||
**手动复现（二选一）**：
|
||||
|
||||
**A. 系统级（与 deb 完全一致）**
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /etc/wireplumber/wireplumber.conf.d
|
||||
sudo cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
|
||||
/etc/wireplumber/wireplumber.conf.d/
|
||||
```
|
||||
|
||||
**B. 用户级（与当前调试习惯一致，不 sudo）**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/wireplumber/wireplumber.conf.d
|
||||
cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
|
||||
~/.config/wireplumber/wireplumber.conf.d/
|
||||
```
|
||||
|
||||
若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [OPERATION](OPERATION_PipeWire_Kaisa_HDMI.md) §2）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 重启 PipeWire 栈（推荐顺序）
|
||||
|
||||
与「空 Audio 列表」排障一致：**先 PipeWire，再 WirePlumber**。
|
||||
|
||||
```bash
|
||||
systemctl --user restart pipewire pipewire-pulse
|
||||
sleep 1
|
||||
systemctl --user restart wireplumber
|
||||
```
|
||||
|
||||
再等 1～2 秒。
|
||||
|
||||
### 已复制 `50-kaisa-…conf` 但仍只有一条「立体声」sink？
|
||||
|
||||
在 **WirePlumber 0.4.x**（Ubuntu 24.04 常见）上，仓库里的 **`monitor.alsa.rules`** 片段**可能不会**自动把卡切到 **pro-audio**，`pactl list cards` 里**活动配置**仍为 **`output:stereo-fallback+input:…`**。这**不代表**片段装错路径，而是**会话管理器版本**与 **0.5+** 行为不同。
|
||||
|
||||
**验收与 deb 交付仍成立**：必须再执行下面 §3 的 **`pactl set-card-profile … pro-audio`**。**deb（≥0.3.0）仍包含该 conf**（未来 **0.5+** 或更易合并 drop-in 的环境上可能单独生效）；**不**再随包提供 `kaisa-restore-pipewire-hdmi`，请用本手顺 **`pactl`**/**`amixer`**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证：是否已 `pro-audio`（勿写死 46 / 4）
|
||||
|
||||
**稳定标识**是 **声卡名** + **profile 名**，不是数字 id。
|
||||
|
||||
```bash
|
||||
# 若已安装 pulseaudio-utils：
|
||||
pactl list cards | grep -A2 'alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def' -A30
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```bash
|
||||
wpctl status
|
||||
wpctl inspect <Devices 里该卡的 id> | grep -E 'name|profile'
|
||||
```
|
||||
|
||||
若 **活动配置**仍是 **`stereo-fallback`**，执行：
|
||||
|
||||
```bash
|
||||
pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-audio
|
||||
```
|
||||
|
||||
**实机结论（WirePlumber 0.4.x）**：仅把 **`50-kaisa-…conf`** 放到 **`/etc/wireplumber/...`** 或 **`~/.config/...`** 并重启栈后，**`wpctl status` → Sinks** 往往仍只有一条「立体声」；**执行上列 `pactl set-card-profile … pro-audio` 之后**，才会出现多条 **Pro / Pro 2 / Pro 3 / Pro 4**（或等价 **`pro-output-*`**）。因此 **0.4 验收以本 `pactl` 命令为「多出 sinks」的分界**，而非单靠 conf。
|
||||
|
||||
**说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。
|
||||
|
||||
**GUI 试声后 Pro sinks 消失**：在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出时，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」。属 **Pro-audio 与桌面会话抢 profile** 的常见现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 OPERATION §2「测试扬声器」说明）。
|
||||
|
||||
- **PCI 路径不同**的机器：用 `pactl list cards short` 第二列**实际卡名**替换上面长名。
|
||||
- **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。
|
||||
- **WirePlumber 0.4.x**：多数情况下**必须**执行本步 `pactl`；见上文「已复制 conf 但仍只有立体声」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 默认 sink + IEC958
|
||||
|
||||
**≥0.3.0** 的 deb **不**包含 **`kaisa-restore-pipewire-hdmi`**。请在本机用 **`pactl`**（需 **`pulseaudio-utils`**）完成与 §3 同源的 profile 切换，再 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应 **`pro-output-N`**），并按 [OPERATION §4.2](OPERATION_PipeWire_Kaisa_HDMI.md) 打开对应 **`IEC958',N`**。
|
||||
|
||||
若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 OPERATION §4.1），再 **`amixer`** 开 IEC958。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准（打包前勾选）
|
||||
|
||||
| 检查项 | 命令 / 预期 |
|
||||
|--------|-------------|
|
||||
| 卡 profile | `pactl list cards` 中该卡 **活动配置** 含 **pro-audio**（或等价描述） |
|
||||
| 多 sink | `pactl list short sinks` 或 `wpctl status` 出现 **pro-output-*** 或 **Pro 2/3/4** |
|
||||
| 默认输出 | `pactl get-default-sink` 指向 **pro-output-2**（或当前接线对应路） |
|
||||
| IEC958 | `amixer -c0 sget 'IEC958'` 对应路为 **on** |
|
||||
| 试声 | `pw-play /usr/share/sounds/alsa/Front_Center.wav` 或 `paplay`（走默认 sink） |
|
||||
|
||||
---
|
||||
|
||||
## 6. 手顺小节索引
|
||||
|
||||
| 步骤 | 本文 |
|
||||
|------|------|
|
||||
| 片段 + 清无扩展名 | §1–2 |
|
||||
| 重启栈 | §3 |
|
||||
| `pactl` / `amixer`（§4） | §4 |
|
||||
| 验收 / 试声 | §5 |
|
||||
|
||||
---
|
||||
|
||||
## 7. deb 打包前建议
|
||||
|
||||
1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。
|
||||
2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。
|
||||
3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 OPERATION「互斥」一致）。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 示例：登录后执行「pro-audio + 默认 sink + IEC958」——需自备可执行文件（deb ≥0.3.0 不随包提供脚本）。
|
||||
# 将 @@HOME@@ 换为 $HOME；ExecStart 可指向你自己写的 shell，内嵌 §4.1/§4.2 的 pactl/amixer 命令。
|
||||
[Unit]
|
||||
Description=Kaisa SOF rt5682: PipeWire pro-audio + IEC958 (HDMI)
|
||||
After=pipewire-pulse.service
|
||||
Wants=pipewire-pulse.service
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStartPre=/bin/sleep 2
|
||||
ExecStart=@@HOME@@/.local/bin/kaisa-restore-pipewire-hdmi
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
Reference in New Issue
Block a user