LyricsX macOS 桌面歌词应用完全指南:安装、核心功能与 LRCX 歌词格式详解
LyricsX macOS 桌面歌词应用完全指南:安装、核心功能与 LRCX 歌词格式详解
LyricsX 是一款面向 macOS 的桌面歌词应用,它能够在你常用的音乐播放器(Apple Music、Spotify、Vox、Audirvana、Swinsian 等)播放歌曲时,自动从多个歌词源搜索并获取歌词,以桌面歌词、菜单栏歌词、歌词窗口、Touch Bar 等形态实时展示。本文以仓库 README 为骨架,结合 LyricsX 工程源码,完整介绍其安装方式、核心功能、LRCX 自定义歌词格式、偏好设置参数以及底层实现原理,帮助你快速上手使用,并为二次开发或贡献代码提供索引。
一、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() 会按以下顺序尝试获取歌词:
- 旁加载本地歌词:若开启"加载同名歌词"(
LoadLyricsBesideTrack),会先在音乐文件同目录查找同名.lrcx/.lrc文件。 - 读取歌词保存目录:默认目录为
~/Music/LyricsX,文件命名规则为标题 - 艺术家.lrcx(路径中的/会被替换为:,见 Extension.swift)。若使用自定义保存路径,则以安全作用域书签(Security-Scoped Bookmark)方式访问。 - 多源在线搜索:以上都未命中时,构造
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 |
九、工程结构速览与开源依赖
如果你打算阅读或二次开发,可以按以下线索快速定位:
- 入口与生命周期:AppDelegate.swift(启动、快捷键、菜单动作、UserDefaults 注册)
- 核心状态机:AppController.swift(当前歌词、当前行、偏移、搜索)
- 播放器抽象:SelectedPlayer.swift
- 展示层:Controller(桌面/菜单栏/Touch Bar/HUD/搜索歌词)、View(KaraokeLabel、ScrollLyricsView 等)
- 辅助进程:LyricsXHelper
- 配置与本地化:UserDefaults.plist、zh-Hans.lproj 等 20 余种语言的 Localizable.strings
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 只负责搜索、展示与本地管理歌词文件,使用时请遵守所在地区的版权法规,不要将获取的歌词用于商业分发。

