From b8d4fc413007c1d83fc1494a34b1f95d12f372aa Mon Sep 17 00:00:00 2001 From: Zhe Fang Date: Sun, 11 Jan 2026 20:03:12 -0500 Subject: [PATCH] chores: refactor folder structure --- README.CN.md | 2 +- README.md | 2 +- docs/USER_GUIDE.CN.md | 164 ++++++++++++++++++ docs/USER_GUIDE.md | 164 ++++++++++++++++++ .../assets/promotion}/banner.png | Bin .../assets/promotion}/banner_fade.png | Bin {Promotion => docs/assets/promotion}/en.txt | 0 {Promotion => docs/assets/promotion}/ja.txt | 0 {Promotion => docs/assets/promotion}/ko.txt | 0 .../assets/promotion}/zh-CN.txt | 0 .../assets/promotion}/zh-TW.txt | 0 11 files changed, 330 insertions(+), 2 deletions(-) create mode 100644 docs/USER_GUIDE.CN.md create mode 100644 docs/USER_GUIDE.md rename {Promotion => docs/assets/promotion}/banner.png (100%) rename {Promotion => docs/assets/promotion}/banner_fade.png (100%) rename {Promotion => docs/assets/promotion}/en.txt (100%) rename {Promotion => docs/assets/promotion}/ja.txt (100%) rename {Promotion => docs/assets/promotion}/ko.txt (100%) rename {Promotion => docs/assets/promotion}/zh-CN.txt (100%) rename {Promotion => docs/assets/promotion}/zh-TW.txt (100%) diff --git a/README.CN.md b/README.CN.md index 62f217b..78f26cf 100644 --- a/README.CN.md +++ b/README.CN.md @@ -20,7 +20,7 @@
- Banner + Banner diff --git a/README.md b/README.md index 553dbe2..e1e1169 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@
- Banner + Banner diff --git a/docs/USER_GUIDE.CN.md b/docs/USER_GUIDE.CN.md new file mode 100644 index 0000000..0640ab3 --- /dev/null +++ b/docs/USER_GUIDE.CN.md @@ -0,0 +1,164 @@ +[**English**](USER_GUIDE.md) | **中文** + +# ❓ 常见问题解答 (FAQ) + +## 🎵 播放与连接 + +### 🤔 我在使用网易云音乐作为音乐播放器 + +强烈建议首先浏览 [此处](#已知支持的音乐播放器配置指南) 的配置指南。 + +### 🤔 显示没有音乐正在播放 + +部分播放器需要额外配置，请查看 [此处](#已知支持的音乐播放器配置指南)。 + +### 🤔 怎么通过本软件播放本地歌曲？ + +1. 请确保本地歌曲文件夹已添加到软件内（参考 [如何设置本地歌词源？](#-如何设置本地歌词源) 中的第一步） +2. 打开 `音乐库` + - 可通过歌词窗口左上区域的图书按钮打开 + - 或在系统托盘右键本软件，选择打开音乐库 + +## 🪟 窗口与交互 + +### 🤔 如何移动和调整窗口大小？ + +如果您无法选择和移动窗口，请检查 `歌词窗口管理` 的 `窗口` 设置中，`可拖动区域` 的选项是否误设为 `无`。 + +### 🤔 我看不到任何按钮 / 底部命令栏被隐藏了 + +**顶部与底部命令栏：** + +- 默认情况下，当鼠标移出顶部命令栏和底部命令栏（播放控制面板）区域时，它们会自动隐藏。只需将鼠标悬停在这些区域即可再次显示它们。 +- 如果窗口已锁定，悬浮到窗口上放即可显示解锁按钮。 + +**无法唤出底部面板：** +当窗口太小无法显示该面板时，只有将鼠标悬停在歌词窗口底部并单击白线，才能显示播放控制面板。 + +### 🤔 软件有哪些默认快捷键？ + +- `Ctrl + Alt + H`：显示/隐藏歌词窗口 +- `Ctrl + Alt + S`：切换歌词窗口状态 +- `Ctrl + Alt + P`：播放/暂停当前曲目 +- `Ctrl + Alt + Right`：下一曲目 +- `Ctrl + Alt + Left`：上一曲目 + +> 可前往 `设置` -> `应用外观与行为` 更改上述快捷键 + +## 📃 歌词显示 + +### 🤔 歌词显示错误（匹配错误） + +- 请前往 `设置` -> `播放源` -> `歌词搜索策略` 选择 `最佳匹配` +> 注意：对于每首歌曲，首次使用最佳匹配时将耗时 10 秒左右，请耐心等待 + +- 或打开歌词搜索窗口手动搜索正确的歌词。 + +> 歌词搜索窗口可通过下述一种方式打开： +> - 将鼠标移至窗口靠下区域，直至底部控制栏出现，点击右下侧放大镜图标（🔍）以打开歌词搜索窗口 +> - 右键系统托盘内本软件的图标，选择 “打开歌词窗口” + +### 🤔 歌词一直在来回移动（时间轴跳动） + +前往 `设置` > `播放源` > 禁用 `歌词时间轴同步` 或提高 `歌词时间轴同步阈值`。 + +### 🤔 如何设置本地歌词源？ + +**第一步：添加文件夹** +前往 `设置` -> `媒体库`，点击 `添加` 按钮，将您存放歌词（或包含内嵌歌词的音乐文件）的文件夹添加进去，并确保右侧开关为 **“开启”** 状态。 + +**第二步：准备文件** +软件支持两种方式： + +1. **外挂歌词文件 (.lrc/.eslrc/.ttml)** + 软件进行比对时，**不区分词语顺序**，且**自动忽略标点符号**。 + * **推荐命名：** `歌手名 - 歌名.lrc` + * **也支持：** `歌名 歌手名.lrc` + * **同样支持：** `歌名 (Live) - 歌手名.lrc` + * *例：播放 Taylor Swift 的 "Love Story" 时，文件名为 `love_story_taylor_swift.lrc` 也能被精准识别。* + +2. **内嵌歌词** + 如果您的本地音乐文件（.mp3/.flac等）标签中已写入歌词，软件也会自动读取。 + +> 推荐下述几种方式检查音乐文件的标签信息： +> - [音乐标签](https://www.cnblogs.com/vinlxc/p/11347744.html)：可浏览本地歌曲元信息 +> - 在 **第一步：添加文件夹** 已完成的情况下可前往 BetterLyrics 软件 `音乐库` 单击音乐条目的右侧三个点图标（···）显示解析的元信息（可能与实际信息有出入） + +> 为了确保 **内嵌歌词** 方式的顺利匹配，推荐下述工具： +> - [音乐标签](https://www.cnblogs.com/vinlxc/p/11347744.html)：可批量将 **所有元信息** 写入本地音乐文件标签 +> - [LDDC](https://github.com/chenmozhijin/LDDC)：可批量将 **逐字歌词** 写入本地音乐文件标签 + +### 🤔 歌词显示部分乱码 + +一般情况是默认字体设置问题，前往 `设置` -> `歌词窗口管理` -> `歌词样式` -> `歌词字体` -> 键入 `Arial` 以获得最稳妥的展示效果 + +## 🎨 模式与外观 + +### 🤔 如何添加更多模式？ + +软件初始已为您添加了所有预设的模式。 + +您可以导入他人与您分享的窗口状态文件：转到 `设置` -> `歌词窗口管理` -> 导入（向下箭头图标） -> 选择需要导入的文件（`.json` 格式） + +> 要导出窗口状态，请右键窗口状态，选择 `导出` + +### 🤔 如何切换模式？ + +- 按下默认快捷键 `Ctrl + Alt + S`，然后选择屏幕上显示的模式来切换模式。（按 `Esc` 键关闭选择窗口） +- 在歌词窗口左上区域找到双向箭头图标，点按即可唤出歌词窗口切换器 + +## 📂 数据与反馈 + +### 🤔 歌词缓存在哪里？ + +`%LocalAppData%\Packages\37412.BetterLyrics_rd1g0rsrrtxw8\LocalCache\lyrics` + +### 🤔 如何反馈问题？（日志位置） + +反馈时请附带软件日志，日志位置如下： +`%LocalAppData%\Packages\37412.BetterLyrics_rd1g0rsrrtxw8\LocalCache\logs` + +# 已知支持的音乐播放器（配置指南） + +使用方法：找到音乐播放器，安装表格中所列出的 `插件`。 + +> 支持的音乐播放器包括但不限于下述列表，请以实际体验为准。 + +> 凡是接入了 [SMTC](https://learn.microsoft.com/zh-cn/windows/uwp/audio-video-camera/integrate-with-systemmediatransportcontrols) 的媒体播放器均受支持。 + +| 音乐播放器 | 插件 | 注意事项 | +| :--- | :--- | :--- | +| [AIMP](https://www.aimp.ru) | [插件](https://www.aimp.ru/?do=catalog&rec_id=1097) | - | +| [AMLL Player](https://github.com/Steve-xmh/applemusic-like-lyrics/blob/full-refractor/packages/player/README.md) | - | - | +| [Apple Music](https://music.apple.com) | - | - | +| [BetterLyrics](https://github.com/jayfunc/BetterLyrics) | - | - | +| [foobar2000](https://www.foobar2000.org/windows) | [插件](https://github.com/dumbie/foo_mediacontrol) | 时间轴有问题 | +| [Google Chrome](https://www.google.com/chrome) | - | - | +| [HyPlayer](https://github.com/HyPlayer/HyPlayer) | - | - | +| [iTunes](https://apps.microsoft.com/detail/9pb2mz1zmb1s) | [插件](https://github.com/thewizrd/iTunes-SMTC) | - | +| [酷狗音乐](https://www.kugou.com) | - | ![](https://github.com/jayfunc/BetterLyrics/blob/dev/FAQ/Snipaste_2025-11-01_12-51-44.png?raw=true) 时间轴有问题 | +| [Listen 1](https://listen1.github.io/listen1) | - | - | +| [LX Music](https://github.com/lyswhut/lx-music-desktop) | - | 在 LX Music 设置 “开放 API” 中勾选 “启用开放 API 服务”；
在 BetterLyrics 设置 “播放源” 板块下的 “LX 音乐服务器” 中输入 LX Music 服务器地址。 | +| [Microsoft Edge](https://www.microsoft.com/edge) | - | - | +| [MoeKoe Music](https://github.com/MoeKoeMusic/MoeKoeMusic) | - | - | +| [MusicBee](https://getmusicbee.com) | [插件](https://github.com/HenryPDT/mb_MediaControl) | - | +| [MusicPlayer2](https://github.com/zhongyang219/MusicPlayer2) | - | - | +| [PlanetMusic](https://apps.microsoft.com/detail/9nt5122pwqb8) | - | - | +| [PotPlayer](https://potplayer.daum.net) | - | - | +| [QQ 音乐](https://y.qq.com) | - | 确保使用较新版本，并在 QQ 音乐设置中启用 “显示系统媒体传输控制 (SMTC)”。 | +| [Salt Player for Windows](https://moriafly.com/program/spw.html) | - | - | +| [Spotify](https://open.spotify.com) | - | - | +| [网易云音乐](https://music.163.com) | [BetterNCM](https://microblock.cc/betterncm)
[InfLink-rs](https://github.com/apoint123/inflink-rs) | ![](https://github.com/jayfunc/BetterLyrics/blob/dev/FAQ/Snipaste_2025-11-01_19-25-56.png?raw=true) | +| [Windows Media Player](https://apps.microsoft.com/detail/9wzdncrfj3pt) | - | - | +| ... | ... | ... | + +# 歌词源配置 + +## Apple Music + +- 打开 [Apple Music 网站](https://music.apple.com/) 和开发者工具窗口。 +- 登录您的帐户。 +- 刷新页面。 +- 返回开发者工具窗口，选择 `Fetch/XHR`，选择一个请求，在请求头中找到 `media-user-token` 标头，并复制其值。 +- 打开 BetterLyrics 并转到 `播放源` 设置。 +- 将复制的值输入到 `Apple Music media-user-token` 设置中，然后点击右侧的接受图标。 \ No newline at end of file diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..9729ebe --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,164 @@ +**English** | [**中文**](USER_GUIDE.CN.md) + +# ❓ Frequently Asked Questions (FAQ) + +## 🎵 Playback & Connection + +### 🤔 I use Netease Cloud Music as my music player + +It is strongly recommended to first browse the configuration guide [here](#known-supported-music-players-configuration-guide). + +### 🤔 Shows "No music playing" + +Some players require extra configuration. Please check [here](#known-supported-music-players-configuration-guide). + +### 🤔 How to play local songs via this software? + +1. Ensure the local songs folder has been added to the software (Refer to Step 1 in [How to set up local lyrics sources?](#-how-to-set-up-local-lyrics-sources)). +2. Open `Music Library`. + - Can be opened via the book button in the top-left area of the lyrics window. + - Or by right-clicking the software icon in the system tray and selecting "Open Music Library". + +## 🪟 Window & Interaction + +### 🤔 How to move and resize the window? + +If you cannot select or move the window, please check if you have set the `Draggable Area` option to `None` by mistake in the `Window` settings under `Lyrics Window Management`. + +### 🤔 I can't see any buttons / The bottom command bar is hidden + +**Top & Bottom Command Bars:** + +- By default, when the mouse moves out of the top command bar and bottom command bar (playback control panel) areas, they automatically hide. Simply hover your mouse over these areas to show them again. +- If the window is locked, just hover over the window, and you'll see the unlock button. + +**Cannot summon bottom panel:** +When the window is too small to display the panel, you can only show the playback control panel by hovering over the bottom of the lyrics window and clicking the white line. + +### 🤔 What are the default shortcuts? + +- `Ctrl + Alt + H`: Show/Hide lyrics window +- `Ctrl + Alt + S`: Switch lyrics window status (mode) +- `Ctrl + Alt + P`: Play/Pause current track +- `Ctrl + Alt + Right`: Next track +- `Ctrl + Alt + Left`: Previous track + +> You can go to `Settings` -> `App Appearance & Behavior` to change the above shortcuts. + +## 📃 Lyrics Display + +### 🤔 Incorrect lyrics displayed (Mismatch) + +- Please go to `Settings` -> `Playback Sources` -> `Lyrics Search Strategy` and select `Best Match`. +> Note: For each song, the first time using Best Match will take about 10 seconds. Please be patient. + +- Or open the lyrics search window to manually search for the correct lyrics. + +> The lyrics search window can be opened in one of the following ways: +> - Move the mouse to the lower area of the window until the bottom control bar appears, then click the magnifying glass icon (🔍) on the bottom right to open the search window. +> - Right-click the software icon in the system tray and select "Open Lyrics Window". + +### 🤔 Lyrics keep moving back and forth (Timeline jumping) + +Go to `Settings` > `Playback Sources` > Disable `Lyrics Timeline Sync` or increase the `Lyrics Timeline Sync Threshold`. + +### 🤔 How to set up local lyrics sources? + +**Step 1: Add Folder** +Go to `Settings` -> `Media Library`, click the `Add` button, add the folder where you store lyrics (or music files containing embedded lyrics), and ensure the switch on the right is set to **"On"**. + +**Step 2: Prepare Files** +The software supports two methods: + +1. **External Lyrics Files (.lrc/.eslrc/.ttml)** + When comparing, the software **does not distinguish word order** and **automatically ignores punctuation**. + * **Recommended Naming:** `Artist - Title.lrc` + * **Also Supports:** `Title Artist.lrc` + * **Also Supports:** `Title (Live) - Artist.lrc` + * *Example: When playing Taylor Swift's "Love Story", the filename `love_story_taylor_swift.lrc` can also be accurately identified.* + +2. **Embedded Lyrics** + If lyrics are already written into the tags of your local music files (.mp3/.flac, etc.), the software will also automatically read them. + +> We recommend the following ways to check music file tag information: +> - [Music Tag](https://www.cnblogs.com/vinlxc/p/11347744.html): Browse local song metadata. +> - If **Step 1: Add Folder** is completed, go to the BetterLyrics `Music Library` and click the three dots icon (···) on the right of a music entry to show parsed metadata (may differ from actual info). + +> To ensure smooth matching for the **Embedded Lyrics** method, the following tools are recommended: +> - [Music Tag](https://www.cnblogs.com/vinlxc/p/11347744.html): Batch write **all metadata** into local music file tags. +> - [LDDC](https://github.com/chenmozhijin/LDDC): Batch write **verbatim lyrics** into local music file tags. + +### 🤔 Partial garbled text in lyrics + +This is usually a default font setting issue. Go to `Settings` -> `Lyrics Window Management` -> `Lyrics Style` -> `Lyrics Font` -> Type `Arial` to get the most stable display effect. + +## 🎨 Modes & Appearance + +### 🤔 How to add more modes? + +The software has initially added all preset modes for you. + +You can import window status files shared by others: Go to `Settings` -> `Lyrics Window Management` -> Import (Down Arrow Icon) -> Select the file to import (`.json` format). + +> To export window status, right-click the window status and select `Export`. + +### 🤔 How to switch modes? + +- Press the default shortcut `Ctrl + Alt + S`, then select the mode displayed on the screen to switch. (Press `Esc` to close the selection window). +- Find the double-headed arrow icon in the top-left area of the lyrics window and click it to summon the lyrics window switcher. + +## 📂 Data & Feedback + +### 🤔 Where are lyrics cached? + +`%LocalAppData%\Packages\37412.BetterLyrics_rd1g0rsrrtxw8\LocalCache\lyrics` + +### 🤔 How to report issues? (Log location) + +Please attach software logs when reporting issues. The log location is as follows: +`%LocalAppData%\Packages\37412.BetterLyrics_rd1g0rsrrtxw8\LocalCache\logs` + +# Known Supported Music Players (Configuration Guide) + +Usage: Find your music player and install the `Plugin` listed in the table. + +> Supported music players include, but are not limited to, the list below. Please refer to your actual experience for confirmation. + +> All media players that have integrated with [SMTC](https://learn.microsoft.com/en-us/windows/uwp/audio-video-camera/integrate-with-systemmediatransportcontrols) are supported. + +| Music Player | Plugin | Notes | +| :--- | :--- | :--- | +| [AIMP](https://www.aimp.ru) | [Plugin](https://www.aimp.ru/?do=catalog&rec_id=1097) | - | +| [AMLL Player](https://github.com/Steve-xmh/applemusic-like-lyrics/blob/full-refractor/packages/player/README.md) | - | - | +| [Apple Music](https://music.apple.com) | - | - | +| [BetterLyrics](https://github.com/jayfunc/BetterLyrics) | - | - | +| [foobar2000](https://www.foobar2000.org/windows) | [Plugin](https://github.com/dumbie/foo_mediacontrol) | Timeline issues | +| [Google Chrome](https://www.google.com/chrome) | - | - | +| [HyPlayer](https://github.com/HyPlayer/HyPlayer) | - | - | +| [iTunes](https://apps.microsoft.com/detail/9pb2mz1zmb1s) | [Plugin](https://github.com/thewizrd/iTunes-SMTC) | - | +| [Kugou Music](https://www.kugou.com) | - | ![](https://github.com/jayfunc/BetterLyrics/blob/dev/FAQ/Snipaste_2025-11-01_12-51-44.png?raw=true) Timeline issues | +| [Listen 1](https://listen1.github.io/listen1) | - | - | +| [LX Music](https://github.com/lyswhut/lx-music-desktop) | - | Check "Enable Open API Service" in LX Music Settings "Open API";
Input LX Music server address in BetterLyrics Settings under "Playback Sources" -> "LX Music Server". | +| [Microsoft Edge](https://www.microsoft.com/edge) | - | - | +| [MoeKoe Music](https://github.com/MoeKoeMusic/MoeKoeMusic) | - | - | +| [MusicBee](https://getmusicbee.com) | [Plugin](https://github.com/HenryPDT/mb_MediaControl) | - | +| [MusicPlayer2](https://github.com/zhongyang219/MusicPlayer2) | - | - | +| [Netease Cloud Music](https://music.163.com) | [BetterNCM](https://microblock.cc/betterncm)
[InfLink-rs](https://github.com/apoint123/inflink-rs) | ![](https://github.com/jayfunc/BetterLyrics/blob/dev/FAQ/Snipaste_2025-11-01_19-25-56.png?raw=true) | +| [PlanetMusic](https://apps.microsoft.com/detail/9nt5122pwqb8) | - | - | +| [PotPlayer](https://potplayer.daum.net) | - | - | +| [QQ Music](https://y.qq.com) | - | Ensure you are using a newer version, and enable "Show System Media Transport Controls (SMTC)" in QQ Music settings. | +| [Salt Player for Windows](https://moriafly.com/program/spw.html) | - | - | +| [Spotify](https://open.spotify.com) | - | - | +| [Windows Media Player](https://apps.microsoft.com/detail/9wzdncrfj3pt) | - | - | +| - | - | - | + +# Lyrics Source Configuration + +## Apple Music + +- Open the [Apple Music website](https://music.apple.com/) and the Developer Tools window. +- Log in to your account. +- Refresh the page. +- Return to the Developer Tools window, select `Fetch/XHR`, choose a request, find the `media-user-token` header in the request headers, and copy its value. +- Open BetterLyrics and go to `Playback Sources` settings. +- Input the copied value into the `Apple Music media-user-token` setting, then click the accept icon on the right. \ No newline at end of file diff --git a/Promotion/banner.png b/docs/assets/promotion/banner.png similarity index 100% rename from Promotion/banner.png rename to docs/assets/promotion/banner.png diff --git a/Promotion/banner_fade.png b/docs/assets/promotion/banner_fade.png similarity index 100% rename from Promotion/banner_fade.png rename to docs/assets/promotion/banner_fade.png diff --git a/Promotion/en.txt b/docs/assets/promotion/en.txt similarity index 100% rename from Promotion/en.txt rename to docs/assets/promotion/en.txt diff --git a/Promotion/ja.txt b/docs/assets/promotion/ja.txt similarity index 100% rename from Promotion/ja.txt rename to docs/assets/promotion/ja.txt diff --git a/Promotion/ko.txt b/docs/assets/promotion/ko.txt similarity index 100% rename from Promotion/ko.txt rename to docs/assets/promotion/ko.txt diff --git a/Promotion/zh-CN.txt b/docs/assets/promotion/zh-CN.txt similarity index 100% rename from Promotion/zh-CN.txt rename to docs/assets/promotion/zh-CN.txt diff --git a/Promotion/zh-TW.txt b/docs/assets/promotion/zh-TW.txt similarity index 100% rename from Promotion/zh-TW.txt rename to docs/assets/promotion/zh-TW.txt