# MacTouchBarLyrics

**Repository Path**: cc-2018_admin/mac-touch-bar-lyrics

## Basic Information

- **Project Name**: MacTouchBarLyrics
- **Description**: 一个模仿网易云风格的 macOS 悬浮歌词小工具。

它会读取 Music.app 当前播放曲目的信息，自动到 LRCLIB 搜索歌词，然后把当前行歌词显示在桌面悬浮窗里；如果设备带 Touch Bar，还会同步显示到 Touch Bar。
- **Primary Language**: Swift
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Swift, macOS, Xcode, AppleMuSic

## README

# MacTouchBarLyrics

一个模仿网易云风格的 macOS 悬浮歌词小工具。

它会读取 `Music.app` 当前播放曲目的信息，自动到 [LRCLIB](https://lrclib.net/) 搜索歌词，然后把当前行歌词显示在桌面悬浮窗里；如果设备带 Touch Bar，还会同步显示到 Touch Bar。

## 功能

- 读取 `Music.app` 当前歌曲的歌名、歌手、专辑、时长、播放进度
- 自动从 `LRCLIB` 搜索歌词并挑选最匹配结果
- 支持解析带时间轴的 `.lrc` 歌词并按播放进度同步
- 自动把繁体歌词转换为简体中文显示
- 桌面悬浮窗同时显示上一句 / 当前句 / 下一句
- 支持窗口置顶、锁定位置、最小化、手动刷新、退出
- 支持 Touch Bar 显示歌词，并在控制条提供入口和刷新按钮

## 运行环境

- macOS 13.0 及以上
- 可编译 Swift 5.9 的 Xcode
- 本机已安装并可正常打开 `Music.app`
- 能访问 `https://lrclib.net/`

## 运行方式

### 用 Xcode 运行

推荐直接打开工程：

1. 打开 [MacTouchBarLyrics.xcodeproj](./MacTouchBarLyrics.xcodeproj)
2. 选择 `My Mac`
3. `Command + R`

也可以直接打开 [Package.swift](./Package.swift) 作为 Swift Package 运行。

### 用命令行构建

```bash
swift build
```

我已在当前仓库里验证过这条命令可以通过。

## 首次运行权限

应用需要通过 Apple Events 读取 `Music.app` 当前播放信息，第一次启动通常会弹出系统授权框。

如果没有弹窗，可以手动到：

`系统设置 -> 隐私与安全性 -> 自动化`

确认当前应用被允许控制 `Music`。

## 工作原理

Apple Music 的官方逐字滚动歌词没有公开接口可直接读取，所以这个项目采用的是“曲目信息匹配歌词源”的方案：

1. 通过 AppleScript 从 `Music.app` 读取当前曲目和播放进度
2. 用 `歌手 + 歌名 + 专辑` 请求 `LRCLIB` 搜索结果
3. 结合标题、歌手、时长等信息挑选最合适的一条歌词
4. 如果拿到的是时间轴歌词，就按当前播放进度同步显示
5. 如果只有纯文本歌词，则退化为显示首个有效文本行，不做逐行同步

## 界面说明

桌面悬浮窗右上角按钮从左到右分别是：

- 最小化
- 置顶 / 取消置顶
- 锁定位置 / 解除锁定
- 手动刷新歌词

左上角 `x` 按钮用于退出应用。

## 项目结构

- [Sources/MacTouchBarLyrics/AppMain.swift](./Sources/MacTouchBarLyrics/AppMain.swift)
  应用入口和悬浮窗 UI
- [Sources/MacTouchBarLyrics/LyricsController.swift](./Sources/MacTouchBarLyrics/LyricsController.swift)
  播放轮询、歌词状态管理、窗口交互
- [Sources/MacTouchBarLyrics/LyricService.swift](./Sources/MacTouchBarLyrics/LyricService.swift)
  LRCLIB 请求、候选结果评分、LRC 解析、繁转简
- [Sources/MacTouchBarLyrics/MusicScriptBridge.swift](./Sources/MacTouchBarLyrics/MusicScriptBridge.swift)
  通过 `osascript` 读取 `Music.app` 当前曲目信息
- [Sources/MacTouchBarLyrics/TouchBarHostView.swift](./Sources/MacTouchBarLyrics/TouchBarHostView.swift)
  Touch Bar 展示和交互
- [Sources/TouchBarHelper/TouchBarSystemModalController.swift](./Sources/TouchBarHelper/TouchBarSystemModalController.swift)
  Touch Bar 系统模态展示封装
- [Sources/DFRPrivate](./Sources/DFRPrivate)
  Touch Bar 私有接口桥接代码

## 已知限制

- 不能直接读取 Apple Music 官方滚动歌词，只能依赖外部歌词源匹配
- `LRCLIB` 没有收录、匹配不准、或纯音乐曲目时，可能搜不到歌词
- 如果只搜到纯文本歌词，当前版本不会做逐句同步，而是退化显示首个有效文本行
- Touch Bar 功能依赖私有 `DFR` 接口，只适用于仍支持 Touch Bar 的设备/系统环境，后续 macOS 版本兼容性没有保证

## 后续可扩展方向

- 增加多歌词源回退
- 支持手动搜索和手动偏移校准
- 支持自定义字体、主题、透明度和窗口尺寸
- 支持菜单栏常驻和开机自启
- 给歌词加内存/磁盘缓存