Halcyon

一款贴近 MIUI / HyperOS 体验的 Android 音乐播放器

本地音乐 · 在线曲库 · 动态播放页 · 逐字歌词 · 桌面歌词 · 状态栏歌词 · 多语言界面

Halcyon 是一款基于 Jetpack Compose、Miuix 和 AndroidX Media3 构建的 Android 本地音乐播放器。

它以本地音乐和歌词体验为核心，提供 MIUI / HyperOS 风格界面、Compose 逐字歌词、桌面歌词、状态栏歌词、动态封面、应用内均衡器、Monet 动态取色、在线歌词匹配、WebDAV / Navidrome / Emby 远程曲库、LX Music API 在线音源、Last.fm 听歌历史、音乐库统计、完整应用数据备份和高度可定制的播放页体验。

• 支持本地媒体库与自定义文件夹扫描，提供专辑、艺术家、文件夹、流派、年份、作曲家和作词家等多维度浏览；重构音乐库两阶段极速扫描机制：Stage 1 零开销浅层扫描数秒内呈现歌曲与封面，Stage 2 后台多协程并发补全深度标签，支持下拉刷新与文件夹管理联动自动扫描。
• 首次扫描前会询问是否启用全标签搜索：启用后可搜索作曲、作词、注释、别名和自定义标签；关闭后使用更快的基础媒体库扫描，仅搜索歌名、艺术家、专辑等基本信息。
• 音乐库来源可在本地、Navidrome 和 Emby 间切换，切换后会刷新当前来源，避免继续显示上一来源的歌曲。
• 提供独立音乐库搜索页，支持歌曲、专辑、歌手、歌词、重复歌曲和全标签搜索，支持搜索历史、批量选择和范围选择。
• 支持本地歌单、收藏歌单、五星歌曲、歌单导入 / 导出、桌面快捷方式和自定义拖拽排序。
• 歌单与文件夹歌单可分别显示星级 / 红心筛选；音乐库支持列表、双列/多列与封面网格布局，可双指切换并在切换时尽量保持当前位置，侧边快速定位条支持拖动。
• 专辑识别会同时考虑专辑名与专辑艺术家，避免不同艺术家的同名专辑互相合并。
• 艺术家匹配与多源信息：支持自定义本地艺术家文件夹匹配，自动关联图片与视频背景；支持自定义艺术家分割符号（如 /、;、&、、 等），精确拆分与聚合合作曲目；支持从 Wikipedia、Last.fm、网易云等多数据源并发拉取艺术家简介与多语言信息，内置 Cloudflare 验证交互 Sheet 以便安全重试。
• 艺术家静态封面与动态背景按自定义资源、独占/合作专辑艺术家、独占/合作歌曲艺术家的优先级智能匹配；支持多张封面轮播与 MP4/MKV/WebM/MOV 视频背景，同时包含图片与视频时优先播放视频。
• 专辑详情页支持独立的专辑介绍页面和手动编辑，支持一键从网易云拉取专辑介绍；本地专辑优先写入同目录 album.nfo 的 <review>，目录不可写时自动保存到应用内。
• 支持音乐库统计分析、听歌日历、播放次数排行、听歌时长排行、格式分布和音质分布。
• 听歌统计可自定义计次所需的播放比例和播放时长；分析图表支持长按条目查看对应歌曲。
• 支持 Last.fm 授权、完整历史同步、自动 Scrobble 与本地 / Last.fm / 合并听歌历史视图；记录可逐项删除，Last.fm 缓存记录可仅在本地隐藏；敏感凭据由 Android Keystore 加密且不会写入备份。
• 音乐库分析支持缓存与扫描后预热，较大的本地曲库也能更快打开统计页面。

• 提供可指定的横屏播放样式，并支持分别显示或隐藏状态栏、导航栏以及保留被隐藏系统栏的布局占位，兼顾手机、平板、车机和超宽屏；ColorOS 手势栏场景也会保持底栏抬高。
• 新安装默认使用非沉浸圆角封面播放页；非 1:1 封面会按实际图片边界应用圆角。
• 支持动态视频封面，可按歌曲、专辑或全局 fallback 匹配视频封面。
• 支持自定义艺术家封面文件夹与多张封面轮播；长按艺术家封面进入画廊式全屏大图预览，支持左右滑动翻页检视多张封面、底部保存/分享药丸栏与 3 列缩略图画廊抽屉选择。
• 艺术家封面支持 MP4/MKV/WebM/MOV 本地视频作为动态背景，同时包含图片与视频时优先播放视频；长按预览页始终以视频作为首项（1/xxx），支持点击播放/暂停。
• 艺术家静态封面按自定义资源、独占/合作专辑艺术家、独占/合作歌曲艺术家的顺序选择。
• Apple Music 沉浸播放页支持「1:1 沉浸」正方形封面切换；MV 沉浸歌词模式支持进入时默认隐藏系统状态栏与导航栏。
• 支持全局自定义壁纸、开屏海报、自定义 Hi-Res 标识和播放页按钮轮廓。
• 支持 Beautiful Lyrics 风格动态背景，可应用于歌词页、平板横屏播放页和横屏封面页，并提供速度、模糊和亮度调节。
• Compose 歌词页支持 Apple Music 风格动态背景、逐词羽化上浮、弹簧换行与平滑重排，并保持沉浸式歌词 / 非沉浸播放页之间的一致过渡。
• Apple Music 流光支持独立速度调节；当前歌曲流光可统一延伸到首页、音乐库和各列表页，并与沉浸播放页 / 歌词页保持同一坐标与动画状态。
• 支持 Monet 动态取色，可从系统壁纸或当前歌曲封面生成全局强调色。
• 非沉浸播放页可为 Hi-Res / MQ 音质歌曲显示封面角标。
• 播放页支持跟手下拉关闭、动态背景、模糊背景、封面左右滑切歌和横屏队列封面切换；平板横屏可在底部播放条和紧凑导航条显示当前歌词，底栏可在普通、悬浮和液态玻璃样式间切换并自定义圆角/效果参数。
• 播放页提供流光、波形和分段刻度三种进度条，以及流光曲线 / RawS 镜像频谱可视化；音质、音频信息、回放增益和输出设备胶囊可分别配置。
• 支持本地 MV 与网易云 MV：本地视频支持 MP4、MKV、WebM 和 MOV，可在播放页同步静音播放并在详情页独立有声播放；163 key 含 mvid 时，详情页会额外显示明确标注的“网易云 MV”跳转。两者可以同时存在。
• 信息页打开本地 MV 默认直接进入横屏，并支持手动/后台自动画中画、辉光进度条、截图分享、半透明可滚动字幕设置侧栏、可拖动/锁定字幕、KTV 歌词、伴奏测试以及 LunaBeat mv_offsets.json 字幕偏移。
• 新安装默认开启 Apple Music 背景流动、播放控制按钮轮廓、进度条总时长和同步播放无声 MV；升级用户已保存的选择不会被覆盖。
• 长按播放页封面可预览原图，支持双击缩放、单指拖动、分享和保存。
• 封面按歌曲而非仅按专辑解析，同一专辑包含多张内嵌封面时，播放页、迷你播放条、更多菜单、媒体通知和锁屏仍会使用当前歌曲的正确封面与取色。

• 支持 LRC、增强 LRC、ELRC、TTML、AMLL TTML 和 Lyricify 歌词解析。
• 支持逐字 / 逐词歌词、逐行 TTML、翻译、罗马音 / 注音、背景人声、TTML 对唱和 ELRC V1/V2 对唱。
• 歌词页更多菜单将字号、缩放和透视角度等滑动条收纳到二级「歌词样式」页，减少一级菜单长度。
• 支持外置歌词和内嵌歌词读取，并可从同名 .lrc、.ttml、.elrc 文件自动匹配。
• 支持本地歌曲在线匹配歌词：全面兼容 Lyrico Plugin API 5 规范插件，支持从 zip 合集批量导入或删除歌词源插件；支持多插件并发检索、匹配度打分与专辑封面辨识预览；支持独立插件参数配置与持久化；匹配结果可一键写回音频文件内嵌标签（TTMLLYRIC、USLT 等）或外部 .lrc / .ttml。
• 内置 LunaBeat TTML Hub 歌词源，可搜索高精度逐拍 TTML；Lyrico 匹配结果会显示歌曲封面以便辨认。
• 提供桌面歌词悬浮窗、状态栏歌词、媒体通知歌词、词幕、小米 HyperOS 超级小岛 / 焦点通知歌词、SuperLyricApi 和 Lyric Getter API 集成。
• 状态栏歌词的长文本会带间隔连续循环，避免滚动结束时闪跳。
• 可按需隐藏歌词中的作词、作曲及简写“词 / 曲”等额外信息；MV 字幕可独立控制是否显示歌词翻译。
• 歌词分享卡片升级为 Apple Music 贴纸样式与流光磨砂下巴；支持字体导入与系统字体选择器、歌词偏移、歌词点击跳转和副行内容配置。
• 播放页迷你歌词拥有独立缩放、字号、行距和对齐设置；歌词点击支持逐字精确定位、连续时间跳转和可关闭的扩散轮廓反馈，非沉浸模式也保留当前词的羽化推进效果。
• 可在第一句歌词前按模板显示歌曲名、艺术家、专辑等信息；暂停时可仅高亮当前歌词，沉浸模式歌词区域也可按开关启用横滑切歌。
• 内置全屏歌词打轴器：支持逐行 / 逐词打点、固定底部传输控制、撤销 / 重做、V1 / V2 / V1000 对唱角色、翻译、音译、x-bg 背景人声，并可内嵌或导出 LRC、ELRC、TTML。

• 支持 WebDAV 远程曲库，提供连接测试、Digest 认证、远程目录浏览和远程音频播放。
• 支持 Navidrome / Subsonic 与 Emby 音乐库入口，使用和 WebDAV 一致的目录浏览式体验与输入框样式。
• Navidrome / Emby 远程音乐库支持分页加载和整库缓存，Navidrome 超过 500 首的曲库会继续翻页加载。
• 支持 LX Music API 音源导入、在线搜索、在线播放、封面 / 歌词获取和下载到本地。
• LX 搜索可在网易云、QQ 音乐、酷狗和咪咕音乐间横向切换，并支持加密 LX 用户源运行时。
• 提供局域网 Web 音乐服务 Beta，可在可信局域网内通过浏览器浏览、播放和上传音乐。当前版本没有访问密码，请勿在公共网络或端口映射环境中开启。

• 提供应用内软件 10 段参数均衡器，不依赖系统 Equalizer，并根据设备能力显示低音增强和虚拟化选项。
• 均衡器提供独立总增益，可在全部软件音效之后统一增减音量，并对正增益峰值给出削波风险提示。
• 支持原生 Oboe 音频输出和 USB DAC 独占模式；交叉淡入淡出支持恒定响度、线性、平滑和保持原音量曲线。
• 播放页可查看音源、实际播放链、重采样状态和输出设备等实时音频输出信息；交叉淡入淡出会提前交接下一首界面，并保持暂停状态切歌语义。
• 本地音频标签读取使用 lyrico-audiotag 主路径，支持常见音频格式的封面、基础标签、内嵌歌词和多值标签读取。
• 内置独立分卡片标签编辑器，支持编辑基础标签、音轨信息、创作信息、歌词、歌曲封面和交互式星级评分。
• 提供系统解码、FFmpeg 解码和自动解码模式，提升 ALAC / AAC / M4A 等格式兼容性。
• 支持 ReplayGain、随机队列恢复、音质标签展示和 24-bit / 96 kHz 等规格识别。
• 支持 163 key 读取，可从独立 tag、Comment 和 Description 中提取歌曲、专辑、歌手与 mvid，并跳转对应的网易云歌曲页、专辑页、歌手页和 MV 页。
• 提供本地音频工具，可进行格式转换、多音频流导出和 CUE 整轨分轨；内置频谱查看器也可直接跳转 Aspect Pro 或 Kaspek。
• 投放设备页统一提供系统音频输出、Chromecast 和 DLNA MediaRenderer；DLNA 通过应用内局域网媒体服务投放当前歌曲。

• 基于 Miuix 0.9.3 构建 MIUI / HyperOS 风格界面，包含悬浮底部导航、迷你播放器、模糊 / 液态玻璃效果和统一的弹窗样式；底栏支持普通、悬浮与 iOS 风格液态玻璃样式，固定页面支持左右滑动切换，支持搜索栏合并至底栏自定义入口并使收缩态迷你播放条拉满显示歌词；深色系统下启动界面保持深色，避免启动遮罩闪白。
• 支持 10 种界面语言（新增土耳其语与阿拉伯语，完整适配 RTL 镜像排版布局）、应用内语言切换；全局字体与歌词西文字体默认内置 Inter Bold，中日韩补缺内置 MiSans Bold；支持应用字体大小与整体界面缩放、GitHub 更新页、应用日志、完整应用数据备份 / 恢复和 Prism Music 听歌历史导出；日志导出会附带设备属性、getprop 与可读取的 build.prop。
• 备份可包含艺术家 / 专辑置顶等音乐库展示设置；WebDAV 会提示较新的云端自动备份，并可预设手动与自动恢复时默认导入的分类。
• 支持切换应用图标、配置长按桌面图标的快捷方式、在首页分类卡片创建快捷方式，以及紧凑 / 扩展两种桌面播放小组件；小组件显示持久化封面、封面取色模糊背景、实时播放时间和控制按钮，并提供防止非 4×6 桌面网格裁切的兼容布局开关。
• 支持歌曲信息查看、标签编辑、歌词打轴软件跳转、外部标签编辑器适配和通用 AI 歌曲解读。
• 播放页与列表的「更多操作」可分别排序或隐藏；点击媒体通知进入播放页、搜索结果入队方式等行为也可单独设置。
• 支持 MediaSession 自定义命令，通知 / 控制中心可显示收藏和播放模式按钮；蓝牙音频断开时可按设置暂停播放，连接后可自动播放。

• AI 歌曲解读升级为通用 AI 供应商配置，默认支持 DeepSeek 与 Anthropic 协议，支持自定义 Base URL、模型并一键拉取模型列表；支持曲库听歌助手：可根据本地曲库、最近播放和听歌统计生成推荐歌单、回答音乐偏好；只会读取曲库并播放本地歌曲，不会删除或修改文件。
• 首页 AI 播放助手入口默认开启，并会显示当前实际曲库歌曲数量；可在设置中关闭。
• 内置 MCP 服务器，基于官方 Kotlin SDK、Ktor CIO 和 Streamable HTTP，可让 Claude Desktop 等 MCP Host 控制 Halcyon 播放。
• 开启路径：设置 → MCP 服务器 → 开启；连接地址：http://<设备IP>:8384/mcp。
• 当前提供 10 个 tools：play_song、search_music、get_now_playing、skip_next、skip_previous、toggle_play_pause、toggle_shuffle、seek_to、get_queue、get_library_stats。
• 当前提供 2 个只读 resources：halcyon://playback/current、halcyon://library/stats。
• MCP 服务器以 Android Foreground Service 运行；关闭设置开关后会停止监听。

请从 Releases 下载最新版本。

首次使用建议流程：

1. 安装 Halcyon。
2. 授予音乐文件访问权限，并选择扫描模式（媒体库扫描或自定义文件夹扫描）。
3. 扫描完成即可使用。 如需在其他页面上显示歌词，请前往设置页面开启。
4. 如使用远程曲库，请自行配置 WebDAV。

动态视频封面用于播放页封面区域。推荐使用专辑级配置：

Music/
├── 专辑名.mp4
├── 歌曲A.flac
├── 歌曲B.flac
└── 歌曲C.flac

或

Music/专辑名文件夹/
├── cover.mp4
├── 歌曲A.flac
├── 歌曲B.flac
└── 歌曲C.flac

同一专辑中的所有歌曲可以共用同一个视频，避免为每首歌曲重复存放视频文件。

支持集中管理：

Movies/Halcyon/DynamicCovers/
├── Album/
│   └── Album Name.mp4
├── Song/
│   └── Artist - Title.mp4
└── cover.mp4

也支持单文件配置：

Music/歌曲文件名.m4a
Music/歌曲文件名.mp4

实际匹配顺序以实现为准：通常会先检查歌曲所在本地文件夹，再检查 DynamicCovers 下的歌曲 / 专辑视频，最后使用全局 fallback 视频。

前往「设置 → 外观 → MV 文件夹」选择一个或多个只存放 MV 的目录。独立 MV 文件夹支持：

• 容器格式：.mp4、.mkv、.webm、.mov。
• 文件名：歌手 - 歌名、歌手-歌名、歌名 - 歌手 或音频文件名。
• 多歌手歌曲会同时尝试完整艺术家字符串和拆分后的首位艺术家。
• 文件名可以直接使用，也可以追加 _MV 或 -MV。

示例：

Movies/My Music Videos/
├── Charlie Puth - Attention.mkv
├── Charlie Puth-We Don't Talk Anymore.mp4
├── See You Again - Wiz Khalifa.webm
└── 01 One Call Away-MV.mov

为避免把普通动态封面误判成 MV，歌曲同目录和传统 DynamicCovers 目录中的 MV 必须带 _MV 或 -MV 后缀：

Music/Nine Track Mind/
├── 01 One Call Away.flac
├── 01 One Call Away_MV.mkv
├── 02 Dangerously.flac
└── Charlie Puth - Dangerously-MV.mp4

匹配优先级为：独立 MV 文件夹 → 歌曲同目录 → 传统动态封面目录。普通动态视频封面仍只使用 MP4，不会把 MKV MV 当作循环封面。

播放页左侧信息页会分别显示：

• MV 分类 → 本地 MV：显示视频缩略图与时长，点击后使用 Halcyon 内置播放器有声播放。
• 网易云分类 → 网易云 MV：当歌曲的 163 key 含非零 mvid 时显示，点击跳转 https://y.music.163.com/m/mv?id=<mvid>。

若两者都存在，会在各自分类中同时显示；网易云 MV 不会挤占或替代本地 MV，也不会参与播放页静音同步。

Halcyon 支持 LunaBeat 的 mv_offsets.json。可以把文件放在本地 MV 同目录，或从「设置 → 音乐库 → 标签与刮削 → LunaBeat MV 偏移值」导入：

{
  "offsets": {
    "Charlie Puth - Attention.mkv": 1.25,
    "01 One Call Away_MV.mp4": -0.4
  }
}

键名是 MV 的完整文件名，数值单位为秒；正数让字幕/歌词更晚出现，负数让字幕/歌词提前出现。导入的文件同时适用于详情页 MV 与播放页横屏 MV。

MKV、WebM 和 MOV 是容器格式，能够识别文件不等于设备一定能够解码其中的视频与音频。常见 8-bit H.264、H.265 和 VP9 通常可以直接播放；H.264 High 10、部分 HEVC Main 10 以及 TrueHD 组合需要设备提供相应硬件解码能力。Halcyon 当前没有 FFmpeg 视频软解回退，不兼容时会播放失败。

git clone https://github.com/Kifranei/Halcyon.git
cd Halcyon
./gradlew :app:assembleDebug -PellaAbi=arm64-v8a

Windows PowerShell：

git clone https://github.com/Kifranei/Halcyon.git
cd Halcyon
.\gradlew.bat :app:assembleDebug -PellaAbi=arm64-v8a

Release 构建会优先读取以下环境变量：

RELEASE_STORE_FILE
RELEASE_STORE_PASSWORD
RELEASE_KEY_ALIAS
RELEASE_KEY_PASSWORD

如果未设置这些变量，会使用项目根目录下的 release.jks。如果没有可用的 release keystore，本地 release 构建默认失败；在 CI 或显式设置 ALLOW_DEBUG_SIGNED_RELEASE=true 时，会改用 debug 签名产出 release APK，便于 GitHub Actions 提供可测试安装包。

日常开发建议使用 assembleDebug 验证；fastRelease / release 构建仅在发版时使用。默认 native 库走预编译 .so 打包，如需更新 FFmpeg 或 lyrico-audiotag native，再手动运行对应脚本重新生成。发版后请同步推送 GitHub 与 GitLab 远端。

预编译的 FFmpeg 与 lyrico-audiotag native 库默认位于：

ffmpeg-decoder/src/main/jniLibs/arm64-v8a/libffmpegJNI.so
lyrico-audiotag/src/main/jniLibs/arm64-v8a/liblyrico_taglib.so

如需在 fresh clone 后恢复 FFmpeg 预编译输入，请先运行：

.\scripts\download_ffmpeg_prebuilt.ps1

如需在 Windows 上手动更新 FFmpeg native，请运行：

.\build_ffmpeg.ps1

如需更新 lyrico-audiotag / TagLib native 产物，请运行：

.\build_lyrico_taglib.ps1

普通 assembleDebug 不会默认重新编译 native；发版前确认 APK 内包含所需 arm64-v8a .so。如果只需要日常构建，无需拉取完整 FFmpeg 源码。

liblyrico_taglib.so 是 lyrico-audiotag 的 native 标签读写产物，用于本地音频文件的元数据读写。

Halcyon 主项目以 Apache-2.0 协议开源。第三方组件保留其各自许可证，详见 THIRD_PARTY_LICENSES.md。

• BetterLyrics — 为模糊封面背景和歌词展示提供视觉参考。
• Beautiful Lyrics — 为动态背景、全屏歌词与歌词视觉体验提供参考。
• LySy — 为内置原生 Kotlin / Compose 歌词打轴页提供交互与时间轴算法参考（MIT；不引入其 Web 源码或依赖）。
• Lyrico — 为外部标签编辑器适配、歌曲标签读取和日志页面交互提供参考。
• LX Music Mobile — 提供 LX Music API 兼容实现与测试参考。
• RawS Music — 为 10 段均衡器、BiQuad 参数均衡、360° 环绕 / 全景音、等响度、动态均衡/齿音抑制、Moog 梯形滤波器与峰值保护提供 Apache-2.0 的算法参考与 Kotlin 移植基础。
• 光锥音乐 — 界面设计与功能实现参考。
• 感谢 Halcyon 所使用的 Miuix、Media3、FFmpeg、Lyricon、SuperLyricApi、LyricGetter-API、lyrico-audiotag / Lyrico、TagLib、163KeyDecrypter、Coil、OkHttp、Reorderable、LySy、Beautiful Lyrics、RawS Music 以及其它开源项目。

• 以及感谢各位群友积极的测试反馈。Halcyon 的开发与测试过程，也离不开各位群友的支持与鼓励。

此项目确实让我感受到个人开发者的艰难。开发不易，且无偿开发4个月了。如果您觉得 Halcyon 对您有帮助，欢迎赞助支持，谢谢。

• Lyrico 强大的歌曲标签编辑工具，同样使用 Miuix 构建，支持匹配歌词、封面、ReplayGain、网易云注释等。

• RawS Music 一个支持 USB DAC 独占，且支持EQ、环绕音效等的开源本地播放器，同样使用 Miuix 构建，推荐试试。

• 词幕 为 Android 提供逐字和对唱显示的状态栏歌词插件。需要启用 Xposed 或 LSPosed 框架。

• 棱镜音乐 由 leguan 开发的本地播放器。播放页面等也非常美观，推荐一试。

• LunaBeat 可以在手机上实现歌词打轴，同时也是具有美观的播放和歌词页面的播放器。Halcyon 的歌词打轴界面参考了其设计。