Music 音乐使用说明
Music 是本地音乐播放器，播放时不需要联网。 应用扫描设备上的音频文件，并通过系统的 mpv 输出声音。
使用前准备
- 在设备上安装 Music 和 mpv，确保默认音频输出可用。
- 将歌曲复制到运行用户的
$HOME/Music，应用需要文件及目录读取权限。 - 也会检查
/root/music、/mnt/sdcard/music、/mnt/music、/media/music等默认位置。 - 支持 MP3、WAV、FLAC、M4A、AAC、OGG、Opus、AIFF/AIF、AC3、MP4、TS 和 WMA 扩展名；能否解码取决于设备的 mpv。
文件夹会递归扫描，最多深入 8 层、收录 2,048 首歌曲。 默认位置都没有音乐时，应用会提供内置示例曲目。
播放第一首歌
- 从启动器打开 Music，等待媒体库扫描完成。
- 竖屏时进入 Library；宽屏布局会同时显示媒体库和播放器。
- 点击歌曲行开始播放，竖屏可切换到 Now Playing 查看播放器。
- 使用播放/暂停按钮控制当前歌曲，使用上一首/下一首按钮切歌。
- 拖动时间轴跳到所需位置，拖动音量滑块调整音量。
将新歌曲复制到目录后，点击 Library 标题旁的刷新图标重新扫描。 文件列表不会因为复制完成就自动更新。
搜索与收藏
在 Search songs or artists 中输入关键词，按歌名、歌手或专辑过滤结果。 All Songs 显示全部歌曲，Favorites 仅显示收藏。 点击播放器中的爱心可以收藏或取消收藏当前歌曲。 搜索和收藏筛选不会把完整播放队列替换成当前显示的列表。
当前歌曲信息主要来自文件名和文件夹名，不是在线音乐资料库。 文件名使用 歌手 - 歌名 时可拆分歌手和标题，父文件夹名用作专辑。 WAV 时长可在扫描时读取，其他格式通常在开始播放后才显示准确时长。
随机与重复播放
- 点击随机播放图标切换 shuffle。
- 点击重复图标循环切换关闭、列表循环和单曲循环。
- 这些模式影响播放队列；筛选 Library 不会丢弃当前队列。
- 音量、随机模式、重复模式和收藏会保存，重新打开应用后恢复。
应用没有在线播放服务登录、歌曲下载或音频编辑功能。
文件与配置
可由管理员在启动前设置 LILYGO_MUSIC_DIR，只扫描一个指定目录，例如：
sh
LILYGO_MUSIC_DIR="$HOME/Music" lilygo-ui-music这个设置属于启动环境，应用内没有文件夹选择菜单。 显式指定的目录为空或不存在时，媒体库保持为空，不会回退到示例音乐。 使用启动器时，变量需传给启动器启动的进程，单独在其他终端设置不会自动影响它。
偏好保存位置为 $XDG_CONFIG_HOME/lilygo-ui-music/preferences； 未设置 XDG_CONFIG_HOME 时使用 $HOME/.config/lilygo-ui-music/preferences。 要保留收藏和模式设置，该配置目录必须可写。
常见问题
| 现象 | 处理方法 |
|---|---|
No songs yet 或媒体库为空 | 检查运行用户、扫描目录、文件扩展名与读取权限，然后刷新。 |
| 只看到示例曲目 | 默认目录没有找到音乐；把歌曲放入 Music 后刷新。 |
Playback unavailable | 查看页面错误，检查 mpv 是否安装并可被应用启动、文件是否有效。 |
| 有播放进度但无声音 | 检查应用音量、系统音量和默认音频输出。 |
| 歌名或专辑不准确 | 检查文件名和父文件夹名；应用不会在线补全元数据。 |
| 收藏重启后丢失 | 检查配置目录权限，并确认前后由同一个系统用户启动。 |