在 Waybar / DMS / Noctalia 中显示同步歌词

基于 puszkarek/bard 精简而来。项目只读取本地音乐文件元数据中的同步 LRC，不请求在线歌词服务；无时间戳的纯文本歌词会被视为“无同步歌词”。

功能

• 通过 MPRIS D-Bus 协议跟踪播放器
• 从本地音频标签读取同步歌词
• 支持多时间戳、[offset:]、1～3 位小数及常见增强 LRC 逐词标签
• 同一时间戳的附加文本作为翻译/罗马音显示
• Waybar JSON-lines 输出
• DMS 桌面歌词插件
• Noctalia 桌面歌词部件

构建

需要 Rust 2024 edition 工具链：

git clone https://github.com/wind-mask/bard.git
cd bard
just build-waybar-bard
# 或
cargo build --release

完整本地验证：

just ci

just ci 会依次执行格式检查、所有目标的 check/test、严格 Clippy 和 release 构建。

命令行

waybar-bard [--offset-ms <MILLISECONDS>]

--offset-ms 是应用在 LRC 文件 [offset:] 之后的全局校准值，可以为负数，默认值为 100。例如提前 250ms 显示：

waybar-bard --offset-ms -250

Waybar 集成

在 ~/.config/waybar/config.jsonc 中加入持续运行的自定义模块：

{
  "custom/bard": {
    "exec": "/path/to/waybar-bard --offset-ms 100",
    "format": "{}\n<span font='11' fgalpha='50%' style='italic'>{alt}</span>",
    "return-type": "json",
    "restart-interval": 5,
    "tooltip": true,
    "escape": true,
    "hide-empty-text": true,
    "on-click": "pkill -USR1 -x waybar-bard"
  }
}

escape: true 会把歌词作为纯文本处理，避免音频标签中的 <、>、& 被解释为 Pango 标记。

Waybar 的 signal 配置表示 SIGRTMIN+N，不会把 SIGUSR1 发送给持续运行的子进程，因此不应使用旧的 "signal": 1 示例。上面的 on-click 会向所有名为 waybar-bard 的实例发送 SIGUSR1；Waybar 与 DMS 同时运行时，两者会一起切换隐藏状态。

示例 CSS：

#custom-bard {
  background-color: @surface_container;
  color: @on_surface_variant;
}

#custom-bard.hidden,
#custom-bard.no-player,
#custom-bard.paused {
  background: transparent;
}

JSON class 契约

class	含义	text
hidden	SIGUSR1 手动隐藏	空
no-player	没有可用播放器或 Position	空
paused	当前播放器暂停	空
no-lyrics	正在播放但无同步歌词	Artist - Title
has-lyrics	正在显示同步歌词	当前歌词

alt 优先输出当前行的翻译/罗马音；没有附加文本时输出下一句歌词。

DMS 集成

确保 waybar-bard 在 PATH 中，并将 dms-bard 目录复制到 DMS 插件目录，然后添加 Desktop Lyrics 桌面部件。

DMS 默认执行：

command: ["waybar-bard"]

如需校准偏移，可手工改为：

command: ["waybar-bard", "--offset-ms", "250"]

插件将歌词强制按纯文本显示。异常退出时采用 1、2、4、8、16、30 秒的指数退避重启；正常退出不会自动重启。

Noctalia 集成

Noctalia 插件位于 noctalia-bard/（插件 ID wind_mask/bard），数据来源与 DMS 版相同， 改用 Noctalia 的 Luau 插件系统与声明式 ui.* 界面树：

# 本地开发：软链到 Noctalia 的插件目录后启用
ln -sfn "$PWD/noctalia-bard" ~/.local/share/noctalia/plugins/bard
noctalia msg plugins enable wind_mask/bard

在桌面部件编辑器（noctalia msg desktop-widgets-edit）里添加 Bard 部件即可；偏移校准、字号、 最大行数、副行开关、背景/边框透明度、对齐方式都在部件设置里，不必再手改命令行。

播放时还会自动在屏幕顶部居中弹出一个歌词浮层（Top 层，普通窗口之上），播放结束后自动收起； 位置、层（top / overlay）与是否跟随点击的部件都是面板设置项，在 设置 → 插件 里改。 内部结构是一个 stream 服务供数、桌面部件与浮层两个渲染端共用 noctalia.state（官方 timer 插件同款）。

# 桌面部件显隐切换（替代 DMS 版的 SIGUSR1）
noctalia msg plugin wind_mask/bard:lyrics all toggle
# 补装 waybar-bard 或数据流消失后重新拉起
noctalia msg plugin wind_mask/bard:stream all retry
# 歌词浮层开关
noctalia msg panel-toggle wind_mask/bard:overlay

waybar-bard 异常退出时由 shell 循环在 1 秒后重启，并在歌词下方用红色小字提示一次退出码。注意 Noctalia 的桌面部件位于 layer-shell 的 Bottom 层（窗口之下），最大化的窗口会盖住它；要一直看得见就用 上面的歌词浮层。详见 noctalia-bard/README.md。

从旧 class 迁移

0.10.0 的输出 class 有破坏性调整：

no-song  -> no-player / paused
has-song -> no-lyrics

hidden 与 has-lyrics 保持不变。

开发

just fmt       # 格式化
just check     # 全目标检查
just test      # 全目标测试
just clippy    # 严格 Clippy
just ci        # 完整本地验证

许可证

MIT License