LyricsX macOS 桌面歌词应用完全指南:安装、核心功能与 LRCX 歌词格式详解

原创2026-10-14 13:22:081,916 阅读
文章标签:桌面应用

LyricsX macOS 桌面歌词应用完全指南:安装、核心功能与 LRCX 歌词格式详解

LyricsX 是一款面向 macOS 的桌面歌词应用,它能够在你常用的音乐播放器(Apple Music、Spotify、Vox、Audirvana、Swinsian 等)播放歌曲时,自动从多个歌词源搜索并获取歌词,以桌面歌词、菜单栏歌词、歌词窗口、Touch Bar 等形态实时展示。本文以仓库 README 为骨架,结合 LyricsX 工程源码,完整介绍其安装方式、核心功能、LRCX 自定义歌词格式、偏好设置参数以及底层实现原理,帮助你快速上手使用,并为二次开发或贡献代码提供索引。

LyricsX 界面效果预览

一、LyricsX 是什么:macOS 歌词应用的功能全景

仓库 README 将 LyricsX 定位为 "Ultimate lyrics app for macOS"(macOS 终极歌词应用)。围绕"让歌词跟着音乐走"这一核心目标,它提供了以下关键能力:

  • 播放器联动:与主流 macOS 音乐播放器完美配合,自动感知当前播放曲目。
  • 歌词自动获取:根据歌曲标题、艺术家与时长,自动从多个歌词源搜索并下载实时歌词。
  • 多形态歌词展示:桌面(Desktop)歌词、菜单栏(Menubar)歌词、歌词窗口(HUD)与 Touch Bar 歌词,且可自定义字体、颜色、位置。
  • 歌词偏移调整:在状态菜单上直接调整歌词时间偏移,解决歌词与音乐不同步的问题。
  • 歌词导航:在歌词窗口双击任意一行,即可将播放器跳转到对应的时间位置。
  • 拖拽导入导出:支持把歌词文件直接拖进窗口导入,也可把搜索到的歌词拖出保存。
  • 随播放器启动与退出:开启后,LyricsX 会随音乐播放器的启动而启动、随其退出而退出。
  • 简繁中文自动转换:基于 OpenCC 实现简体中文与繁体中文的自动互转。

从工程结构看,本仓库是一个典型的 macOS AppKit 应用,包含两个 target:

目录 / 文件 作用
LyricsX 主应用源码(AppKit + Swift),包含控制器、视图、组件与偏好设置
LyricsXHelper 登录项辅助程序,用于实现"随播放器启动/退出"
LyricsX.xcodeproj Xcode 工程与共享 Scheme
Cartfile Carthage 依赖声明(SnapKit、MASShortcut、Sparkle、AppCenter 等)
docs/img README 使用的效果截图与图标

主应用的核心调度中心是 AppController.swift,它订阅播放器状态变化、发起歌词搜索、维护当前歌词与当前行号;歌词的解析、搜索与过滤能力则依赖外部的 LyricsKit / LyricsService / MusicPlayer 组件。

二、安装指南与系统要求

README 提供了三种官方安装途径,以及一条明确的系统要求。

1. Homebrew(推荐)

$ brew install --cask lyricsx

Homebrew Cask 方式会安装最新发布版,适合大多数用户。

2. Mac App Store

在 Mac App Store 中搜索 "LyricsX" 即可下载(README 中提供了官方应用商店徽标链接)。MAS 版本与 GitHub 发布版存在差异,这一点在源码中有多处体现:

  • MAS 版本不集成 Sparkle 自动更新,改用 App Store 通道;非 MAS 版本则通过 Sparkle 检查更新(见 AppDelegate.swift 中的 #if IS_FOR_MAS 分支)。
  • Touch Bar 歌词在 MAS 版本中不可用,偏好设置中会弹出提示(见 PreferenceLabViewController.swift)。

3. 手动安装

从 GitHub Releases 页面下载最新的 .app 包,解压后拖入"应用程序"文件夹即可。仓库根目录还提供了 ExportOptions.plist,供自行打包导出时使用。

系统要求

  • macOS 10.11+:README 明确标注的最低系统版本。Touch Bar 相关功能额外要求 macOS 10.12.2+(源码中以 @available(OSX 10.12.2, *) 标记)。

需要说明的是,源码中的 Info.plist 显示应用以 LSUIElement(Agent 模式)运行,即不占用 Dock 图标,只通过状态栏图标与用户交互;主程序在沙盒环境中运行(见 LyricsX.entitlements),而 Helper 使用 App Group 与主程序共享偏好设置。

三、支持的播放器与歌词源

播放器支持

README 声称"与你的最爱音乐播放器完美配合",并指向了维护中的支持列表。结合本仓库源码,可以直接确认的播放器支持如下:

  • Apple Music / iTunes(com.apple.Music、com.apple.iTunes)
  • Spotify(com.spotify.client)
  • Vox(com.coppertino.Vox)
  • Audirvana(含 Audirvana Studio / Audirvana Plus)
  • Swinsian(com.swinsian.Swinsian)

以上 Bundle ID 列表可在 LyricsXHelper/AppDelegate.swift 中看到;主应用中播放器的枚举与图标映射在 Extension.swift。

播放器的选择策略由 SelectedPlayer.swift 实现,对应偏好设置中的"首选播放器"选项:

  • PreferredPlayerIndex 为 -1 时是自动模式:若开启 UseSystemWideNowPlaying(实验功能),使用 macOS 系统级 Now Playing 信息;否则在已安装的 Scriptable 播放器中自动探测当前正在播放的那一个。
  • 为 0~4 时,直接绑定到对应播放器(Apple Music、Spotify、Vox、Audirvana、Swinsian)。

播放器状态(当前曲目、播放进度)通过 Scripting Bridge 轮询获得,SelectedPlayer.swift 中以约 1 秒的间隔调用 updatePlayerState() 刷新状态。

歌词源

歌词的搜索与解析由 LyricsKit 组件(本仓库外部的依赖)提供,主应用通过 LyricsService 框架发起聚合搜索请求(见 AppController.swift)。从主应用 Info.plist 的 NSAppTransportSecurity 异常域名配置可以推断,历史上接入过包括网易(126.net / 163.com)、QQ、酷狗(kugou.com)、虾米(xiami.com / xiami.net)、TTPod、ViewLyrics、syair.info、gecimi 等在内的多个歌词站点。由于这些源由 LyricsKit 统一封装,LyricsX 侧无需关心各源的具体协议。

四、核心功能与源码级解析

4.1 歌词自动获取:本地优先,多源搜索兜底

当播放曲目变化时,AppController.swift 中的 currentTrackChanged() 会按以下顺序尝试获取歌词:

  1. 旁加载本地歌词:若开启"加载同名歌词"(LoadLyricsBesideTrack),会先在音乐文件同目录查找同名 .lrcx / .lrc 文件。
  2. 读取歌词保存目录:默认目录为 ~/Music/LyricsX,文件命名规则为 标题 - 艺术家.lrcx(路径中的 / 会被替换为 :,见 Extension.swift)。若使用自定义保存路径,则以安全作用域书签(Security-Scoped Bookmark)方式访问。
  3. 多源在线搜索:以上都未命中时,构造 LyricsSearchRequest(searchTerm: .info(title:artist), duration, limit: 5) 发起聚合搜索,10 秒超时(.timeout(.seconds(10)))。

搜索结果会做质量比较(lyrics.quality),只有质量高于当前歌词时才会替换(AppController.swift)。每次拿到新歌词后都会依次执行 filtrate()(过滤垃圾行)与 recognizeLanguage()(识别语言),并在 needsPersist 标记下写入本地缓存目录,供下次播放时直接命中。

4.2 歌词过滤与"不要搜索"黑名单

自动获取的歌词常常混有"作词 / 作曲 / 专辑"等元信息行或乱码行。LyricsX 提供了一套可编辑的过滤关键词表 LyricsFilterKeys,默认值定义在 UserDefaults.plist 中,包括:

  • 正则类(以 / 开头):/(by|title|song|album|artist|singer|lyrics)\s*[::∶]、/\w+(\.\w+){2}(疑似文件名/网址)、/^\s*//\s*$、/\d{8}(疑似日期)、/^\.$/ 等;
  • 关键词类:作詞、作词、作曲、編曲、编曲、収録、收录、演唱、歌手、歌曲、制作、製作、歌词、歌詞、翻譯、翻译、插曲、插入歌、主题歌、主題歌、片頭曲、片头曲、片尾曲、SoundTrack、アニメ 等。

过滤规则的编译与匹配逻辑位于 Extension.swift:以 / 开头的条目按正则表达式编译,其余按字面量(忽略元字符)匹配;命中规则的行会被从歌词中剔除。

此外,状态菜单提供"歌词错误"与"此专辑不再搜索"两个动作,分别把曲目 ID 写入 NoSearchingTrackIds、把专辑名写入 NoSearchingAlbumNames 黑名单,后续播放时直接跳过自动搜索(见 AppDelegate.swift)。

4.3 桌面歌词(Karaoke 窗口)

桌面歌词是 LyricsX 最直观的形态,对应源码中的 KaraokeLyricsWindowController(KaraokeLyricsController.swift)。其核心特性与实现:

  • 无边框透明浮动窗口:styleMask = .borderless、level = .floating、collectionBehavior = [.canJoinAllSpaces, .stationary],可跟随所有 Space 并固定在屏幕任意位置。
  • 自定义字体与颜色:文字色、进度色、阴影色、背景色均可在偏好设置中调整;字体名称与字号通过 DesktopLyricsFontName / DesktopLyricsFontSize 配置,还支持字体回退(Fallback,见 PreferenceDisplayViewController.swift)。
  • 鼠标经过隐藏 / 截图隐藏 / 暂停隐藏:HideLyricsWhenMousePassingBy、DisableLyricsWhenSreenShot、DisableLyricsWhenPaused 三个开关控制(截图隐藏通过把窗口 sharingType 设为 .none 实现)。
  • 逐字卡拉OK进度:KaraokeLabel 使用 CoreText 的 CTFrame 渲染,配合 LRCX 的逐词时间标签(timetag)驱动 CALayer 蒙版动画,实现逐字高亮(见 KaraokeLabel.swift)。
  • 单行/双行与双语模式:DesktopLyricsOneLineMode 切换单行;PreferBilingualLyrics 开启后,第二行显示翻译,否则显示下一句歌词。
  • 竖排与假名注音:DesktopLyricsVerticalMode 支持竖排显示;DesktopLyricsEnableFurigana 为日文歌词绘制注音假名(Ruby Annotation)。
  • 拖拽定位:开启 DesktopLyricsDraggable 后可直接拖动歌词调整屏幕位置,位置以 0~1 的比例因子 DesktopLyricsXPositionFactor / DesktopLyricsYPositionFactor 持久化(默认 0.5 / 0.9)。

桌面歌词动态效果演示

4.4 菜单栏歌词

MenuBarLyricsController(MenuBarLyricsController.swift)负责状态栏歌词。它提供两种展示方式:

  • 独立歌词项(CombinedMenubarLyrics 关闭):在状态栏额外创建一个 NSStatusItem 显示当前行歌词,原图标保留;
  • 合并显示(开启):把歌词文本直接作为图标按钮的 title,并在空间不足时按单词截断,追加 "..." 后缀。

默认的歌词文本显示前同样会经过简繁转换与暂停隐藏逻辑。

4.5 歌词窗口(HUD)与双击跳转

从状态菜单或快捷键唤出的歌词窗口(LyricsHUDViewController,LyricsHUDViewController.swift)是一块完整的滚动歌词面板:

  • 当前行自动居中并高亮(highlightColor),上下行使用普通文字色;
  • 双击任意歌词行,播放器立即跳转到该行时间点:ScrollLyricsView 捕获双击后回调 doubleClickLyricsLine(at:),最终执行 selectedPlayer.playbackTime = pos(见 ScrollLyricsView.swift);
  • 手动滚动窗口时会暂停自动跟踪(isTracking),恢复后自动回到当前行;
  • 标题栏附带锁按钮,可将窗口层级提升为 modalPanel 防止被其他窗口遮挡;
  • 窗口同时是拖拽导入歌词的落点。

4.6 Touch Bar 歌词

在支持 Touch Bar 的 MacBook 上(macOS 10.12.2+,且非 MAS 版本),TouchBarLyricsController(TouchBarLyricsController.swift)会在触控栏上展示封面、播放控制与逐字高亮歌词,并支持系统 Touch Bar 自定义面板调整布局。它使用 TouchBarSystemModalController,可在任意应用前台时通过 Control Strip 图标唤出。

4.7 歌词偏移调整

歌词与音乐不同步时,可通过状态菜单中的偏移控件或快捷键微调:

  • 每个偏移单位对应 100 毫秒(increaseOffset / decreaseOffset 中 lyricsOffset ±= 100,见 AppDelegate.swift);
  • 偏移分为两层:单曲偏移(写入歌词文件元数据,needsPersist = true)与全局偏移 GlobalLyricsOffset(对所有歌曲生效)。二者叠加得到 adjustedOffset,再除以 1000 转为秒级 adjustedTimeDelay 参与播放时间换算(见 Extension.swift)。

4.8 随播放器启动与退出

开启 LaunchAndQuitWithPlayer 后:

  • 启动联动:LyricsX 主程序退出时会通过 App Group 写入 launchHelperTime,并启动登录项 LyricsXHelper.app(见 AppDelegate.swift);Helper 启动后监听目标播放器的启动事件,一旦发现播放器运行就拉起主程序并自行退出(见 LyricsXHelper/AppDelegate.swift)。
  • 退出联动:主程序订阅 NSWorkspace.didTerminateApplicationNotification,当被选播放器退出时自动终止自身(AppController.swift)。

注意:自动模式(PreferredPlayerIndex == -1)下此功能不可用,因为无法确定要跟随哪个播放器(见 PreferenceGeneralViewController.swift)。

4.9 简繁中文自动转换

LyricsX 内置了基于 OpenCC 的中文转换能力(ChineseConverter,见 ChineseConverter+Singleton.swift):

  • ChineseConversionIndex:0 关闭转换;1 统一转简体;2 统一转繁体;
  • 首次启动时会根据系统语言自动决定默认值:中文系统默认开启,且 zh-Hant / zh-HK 环境默认转繁体(见 AppDelegate.swift);
  • 转换应用于桌面歌词、菜单栏歌词、Touch Bar 歌词以及写回播放器的歌词,且仅当歌词识别语言以 zh 开头时执行,避免误转日文歌词中的汉字(见 MenuBarLyricsController.swift)。

歌词语言识别由 Lyrics+Language.swift 中的 recognizeLanguage() 完成,它会统计歌词正文与翻译文本的主导语言,并把翻译文本挂到对应的语言标签(如 tr:en)下。

4.10 将歌词写回 Apple Music

选中 Apple Music 曲目时,状态菜单提供"写入 iTunes"动作(writeToiTunes),把当前歌词以纯文本形式写回曲目的 lyrics 字段,覆盖旧内容;若开启 WriteiTunesWithTranslation,还会把第一语言的翻译逐行附在原文之后。开启 WriteToiTunesAutomatically 后,每次自动搜索到歌词并结束请求时都会自动执行写回(AppController.swift)。

4.11 手动搜索歌词窗口

当自动搜索未命中或想更换歌词时,可打开"搜索歌词"窗口(SearchLyricsViewController,SearchLyricsViewController.swift):

  • 默认以当前曲目的标题/艺术家为关键词,可手工修改后回车或点击搜索;
  • 结果按质量排序展示标题、艺术家、来源,选中后可预览全文与封面;
  • 选中一条后点击"使用",立即替换当前歌词,并同时清除该曲目/专辑的黑名单标记;
  • 支持把搜索结果直接拖出窗口保存为 .lrc 文件(namesOfPromisedFilesDroppedAtDestination)。

五、LRCX 歌词格式与编辑器生态

普通 LRC 只能表达"整行时间标签",无法表达逐字时间与多语言。LyricsX 为此定义了扩展格式 LRCX,README 明确指出其能力:

  • 逐词时间标签(word time tag):用于桌面歌词 / Touch Bar 的逐字卡拉OK高亮;
  • 多语言翻译(multi-language translation):同一行可挂多种语言的翻译文本,实现"原文 + 翻译"双语显示;
  • 更多扩展属性:统一封装在 LyricsLine.Attachments 中(见 LyricsMetadata+Extension.swift),翻译标签形如 tr:语言代码。

兼容性:LRCX 与 LRC 兼容——LRCX 文件在普通 LRC 编辑器中仍可按 LRC 阅读编辑;LyricsX 的保存目录中也总是优先写入 .lrcx、其次回退 .lrc(AppController.swift)。主应用在 Info.plist 中导出了 org.lyricsx.lrcx 统一类型标识(UTI),同时声明 lrcx 与 lrc 两种文件扩展名,使系统能够识别这类歌词文件。

编辑器现状:README 说明目前没有官方 LRCX 编辑器。社区已有第三方工具(如 Lrcx_Creator)可用于创建 LRCX 文件;在日常场景下,也可以直接使用普通 LRC 编辑器,因为 LRCX 完全兼容 LRC。导入时歌词内容会被解析、过滤、识别语言并关联到当前曲目(importLyrics,见 AppController.swift)。

六、歌词文件管理:保存路径、命名与导入导出

  • 默认保存目录:~/Music/LyricsX(用户主目录下的 Music/LyricsX);可在偏好设置中改为自定义目录(使用带安全作用域的 Bookmark 持久化授权,见 Extension.swift)。
  • 文件命名:标题 - 艺术家.lrcx,文件名中的 / 替换为 :。
  • 导入:将歌词文本或 .lrc / .lrcx 文件直接拖入歌词窗口即可;DragNDropView(DragNDropView.swift)同时接受纯文本与文件两种拖拽类型。
  • 导出:搜索窗口中拖出保存;或通过状态菜单"在 Finder 中显示"直接定位已保存的歌词文件(未持久化时会先写入磁盘)。

七、全局快捷键一览

LyricsX 使用 MASShortcut 注册全局快捷键(见 AppDelegate.swift),可在偏好设置中自定义:

快捷键配置项 对应动作
ShortcutToggleMenuBarLyrics 开关菜单栏歌词
ShortcutToggleKaraokeLyrics 开关桌面歌词
ShortcutShowLyricsWindow 显示歌词窗口(HUD)
ShortcutOffsetIncrease / ShortcutOffsetDecrease 歌词偏移 +100ms / -100ms
ShortcutWriteToiTunes 将歌词写入 Apple Music 当前曲目
ShortcutWrongLyrics 标记歌词错误(加入黑名单并清除)
ShortcutSearchLyrics 打开搜索歌词窗口

八、偏好设置与 UserDefaults 参数速查

偏好设置共五个标签页(General / Display / Filter / Shortcut / Lab,对应 Controller/Preferences 下的视图控制器)。常用键与语义整理如下(默认值来源为 UserDefaults.plist 与 registerUserDefaults()):

配置键 含义 默认值
PreferredPlayerIndex 首选播放器(-1 自动 / 0~4) -1
LaunchAndQuitWithPlayer 随播放器启动/退出 false
LoadLyricsBesideTrack 加载音乐同目录同名歌词 false
LyricsSavingPathPopUpIndex 歌词保存位置(0 默认目录 / 自定义) 0
DesktopLyricsEnabled 桌面歌词开关 true
MenuBarLyricsEnabled / TouchBarLyricsEnabled 菜单栏 / Touch Bar 歌词开关 true / false
DesktopLyricsOneLineMode 桌面歌词单行模式 false
DesktopLyricsVerticalMode 桌面歌词竖排模式 false
DesktopLyricsDraggable 允许拖动桌面歌词 false
HideLyricsWhenMousePassingBy 鼠标经过时隐藏 true
DisableLyricsWhenPaused 暂停时隐藏歌词 true
DisableLyricsWhenSreenShot 截图时隐藏歌词 true
DesktopLyricsFontName / FontSize 桌面歌词字体 / 字号 Optima-Regular / 24
DesktopLyricsEnableFurigana 日文假名注音 false
GlobalLyricsOffset 全局歌词偏移(毫秒) 0
PreferBilingualLyrics 优先显示双语(原文+翻译) 随系统语言
ChineseConversionIndex 简繁转换(0 关 / 1 简 / 2 繁) 随系统语言
StrictSearchEnabled 严格匹配才采用搜索结果 false
CombinedMenubarLyrics 菜单栏歌词合并到图标 false
LyricsFilterEnabled / LyricsSmartFilterEnabled 歌词过滤开关 true / true
LyricsFilterKeys 过滤关键词/正则表 见上文列表
WriteToiTunesAutomatically 自动写回 Apple Music false
WriteiTunesWithTranslation 写回时附带翻译 false
UseSystemWideNowPlaying 使用系统级 Now Playing(实验) false

九、工程结构速览与开源依赖

如果你打算阅读或二次开发,可以按以下线索快速定位:

README 同时致谢了两大核心组件与若干开源库:LyricsKit(歌词解析与多源搜索)、MusicPlayer(播放器抽象),以及 SwiftyOpenCC、GenericID、SwiftCF、Regex、Semver、TouchBarHelper、CombineX、SnapKit、MASShortcut、Sparkle、Then 等(完整清单见 README.md 的 Credit 小节)。这些依赖声明在 Cartfile 与 Cartfile.resolved 中。

十、免责声明与版权说明

README 明确声明:所有歌词均归其版权所有者所有(All lyrics are property and copyright of their owners)。LyricsX 只负责搜索、展示与本地管理歌词文件,使用时请遵守所在地区的版权法规,不要将获取的歌词用于商业分发。

登录后查看全文
LyricsX