KA Music

一个精致的第三方音乐客户端
基于 Flutter 构建 · 支持多平台 · Material You 设计

---

📖 简介

KA Music 是一个功能丰富的 第三方音乐播放器，使用 Flutter 框架构建，支持 Android、iOS、Windows、macOS、Linux 及 Web 六大平台。它提供跨平台音乐搜索、在线播放、歌词展示、下载缓存等完整的音乐体验，并采用 Material You 设计语言，支持深色模式和高度自定义主题。

🔌 该项目通过第三方 API 获取音乐数据，仅供学习交流使用。

---

📸 预览

功能截图

首页推荐	播放器	歌词

个人库	搜索页	歌单详情

---

✨ 核心功能

🎵 音乐播放

• 多音质切换 — 标准 (128K) / 高品质 (320K) / 无损 (FLAC) 三种音质
• 智能降级 — 播放失败时自动降级到更低音质重试，保证播放连续性
• 后台播放 — 支持 Android 通知栏控制及锁屏播放
• 播放模式 — 列表循环 / 随机播放 / 单曲循环
• 倍速播放 — 支持 0.5x ~ 3.0x 变速播放
• 音频均衡器 — 7 种预设音效（流行、摇滚、人声、低音、古典、电子、平板）
• 低音增强 — 0~100% 强度可调
• 定时停止 — 支持按时间或当前歌曲播放完毕后自动停止

🎤 歌词

• 逐字歌词 — 支持 KRC 格式的逐字高亮歌词
• 歌词翻译 — 支持翻译和罗马音显示
• 桌面歌词 — 桌面端悬浮歌词窗口
• 歌词交互 — 双击跳转进度 / 长按复制 / 字体大小可调
• 本地歌曲歌词 — 优先读取同名 LRC 和内嵌时间歌词，缺失时自动联网匹配并缓存，后续可离线显示

本地歌曲如何显示歌词

1. 在 Android 的「我的 → 本地音乐」中授权读取音频并扫描歌曲。
2. 播放歌曲时，先尝试读取可访问的同名 .lrc / .LRC 文件和音频内嵌时间歌词；LRC 支持 UTF-8、带 BOM 的 UTF-16 和 GBK 编码。
3. 没有可用时间歌词时，先读取已缓存的匹配结果，再按歌曲名、歌手和时长联网查找歌词。成功匹配后自动保存，下次播放无需再次联网。

匹配依赖音频标签；标签缺失时会尝试从文件名识别。信息不足或找不到对应录音时不会强行套用其他版本的歌词。网络请求失败不会缓存为空结果，下次播放会重试；只有普通文本内嵌歌词时，会在没有匹配结果的情况下展示该文本。Android 的文件访问权限可能影响同目录 LRC 的读取。

🔍 搜索与发现

• 多平台搜索 — 支持酷狗 + 网易云音乐双源搜索
• 搜索建议 — 实时搜索联想
• 热搜关键词 — 分类展示热门搜索
• 搜索历史 — 本地保存，支持标签式快捷搜索
• 每日推荐 — 个性化歌曲推荐
• 推荐歌单 — 热门歌单浏览
• FM 电台 — 推荐电台 + 分类电台

📚 音乐库管理

• 歌单管理 — 创建 / 收藏 / 重命名 / 排序 / 批量删除
• 歌单分享 — 一键复制歌单歌曲列表到剪贴板
• 歌单导入 — 通过 ID 导入他人歌单
• 跨平台歌单导入 — 在「我的」粘贴 QQ 音乐 / 网易云歌单分享链接，可新建或选择目标歌单，查看导入进度和未匹配结果
• 歌单内搜索 — 快速查找歌单中的歌曲
• 收藏歌曲 — 我喜欢 / 收藏管理
• 云盘 — 个人云盘音乐存储
• 专辑商店 — 新专辑浏览

导入 QQ 音乐自建歌单

1. 在 QQ 音乐中把要导入的歌单设为公开，使用「分享」复制歌单链接或整段分享文本。
2. 登录 KA Music 的酷狗账号，打开「我的 → 导入 QQ / 网易云歌单」，粘贴内容后点击「解析歌单」。
3. 确认歌单名称和歌曲数量，选择新建歌单或已有的自建歌单，再点击「开始导入」。
4. 完成后查看新增、已存在、未匹配及请求失败的数量；未匹配和失败歌曲可以展开查看。可停止导入，也可重新导入以重试失败项。

QQ 导入支持短链接和歌单详情链接，直接读取公开歌单并分页获取歌名、歌手和时长，再匹配到当前曲库。目标歌单已有歌曲按 hash 跳过，源歌单中同名但不同歌手的歌曲会分别匹配。私密、失效或不可读取的歌单会提示错误；部分歌曲不可读取时会显示原始数量与可读取数量的差异。网易云分享链接继续使用服务器解析。

📥 下载与缓存

• 下载管理 — 支持并发下载、断点续传、进度追踪
• 播放缓存 — 自动缓存播放过的歌曲，LRU 策略上限 300MB
• 数据缓存 — SWR（Stale-While-Revalidate）策略，分级 TTL
• 缓存可视化 — 数据缓存 / 下载 / 播放缓存大小查看与清理

🎨 个性化

• Material You — 支持 Dynamic Color，8 种预设种子色
• 深色模式 — 跟随系统或手动切换
• 自定义背景 — 支持从相册选取图片作为全局背景，可调透明度
• 自定义 API — 支持配置自定义 API 地址

📊 数据统计

• 播放历史 — 最近播放歌曲记录（最近 500 首）
• 播放统计 — 累计播放次数、听歌时长
• Top 榜单 — 最常听歌手 / 歌曲 Top 10

---

🏗️ 技术栈

类别	技术
框架	Flutter (SDK ^3.11.5)
语言	Dart
音频播放	just_audio — 低延迟音频引擎
后台播放	audio_service — 通知栏控制 & 后台保活
音频焦点	audio_session — 系统级音频焦点管理
HTTP	http (API 请求) + dio (文件下载)
持久化	shared_preferences — 设置 & 缓存
状态管理	ChangeNotifier + AnimatedBuilder（原生方案）
路由	Navigator 1.0
设计系统	Material 3 (Material You)
代码规范	flutter_lints

---

📐 架构设计

┌─────────────────────────────────────┐
│              UI Layer               │
│   Pages · Widgets · AppTheme        │
├─────────────────────────────────────┤
│           Controllers               │
│   Auth · Player · Download · Theme  │  ← ChangeNotifier
├─────────────────────────────────────┤
│            Services                 │
│   MusicApi · CacheService           │
│   DownloadService · AudioHandler    │
├─────────────────────────────────────┤
│              Core                   │
│   ApiClient (HTTP + 重试 + Session) │
├─────────────────────────────────────┤
│             Config                  │
│   AppConfig · Models                │
└─────────────────────────────────────┘

• 分层清晰 — UI → Controller → Service → Core，单向依赖
• 手动 DI — 构造函数注入，无第三方 DI 框架
• SWR 缓存 — 先返回缓存数据，后台刷新，失败回退缓存
• 自动重试 — 网络请求指数退避重试（2 次，500ms/1s）
• Session 管理 — X-Kg-Session-Id 持久化，自动恢复登录

---

🚀 快速开始

环境要求

• Flutter SDK >= 3.11.5
• Dart SDK >= 3.11.5
• Android Studio / VS Code
• 目标平台对应的 SDK

安装与运行

# 克隆仓库
git clone <repo-url>
cd kgka_music_hl

# 安装依赖
flutter pub get

# 运行（选择目标平台）
flutter run          # 自动检测设备
flutter run -d android
flutter run -d ios
flutter run -d windows
flutter run -d macos
flutter run -d linux
flutter run -d chrome

本地歌词回归测试

flutter test test/local_lyrics_test.dart

覆盖 LRC 编码、MP3 / FLAC 内嵌歌词、联网匹配、缓存离线复用、文件替换后缓存失效，以及同名翻唱和不同录音版本的排除。测试夹具为生成的短音频，不依赖个人音乐文件。

歌单导入回归测试

flutter test test/playlist_import_test.dart

覆盖 QQ 短链接跳转、分页、同名不同歌手、重复歌曲、停止导入、写入失败，以及新建歌单到显示导入结果的界面流程。自动化测试使用模拟服务，不会修改真实账号的歌单。

编译环境变量

变量	说明	默认值
KA_MUSIC_API_BASE_URL	自定义默认 API 地址	https://music.api.hoilai.cn
KA_MUSIC_DEBUG_LYRICS	启用歌词调试日志	true

# 编译时指定环境变量示例
flutter run --dart-define=KA_MUSIC_API_BASE_URL=https://your-api.com

---

📁 项目结构

lib/
├── main.dart                 # 应用入口
├── assets/
│   └── logo.jpg              # App Logo
├── config/
│   └── app_config.dart       # 全局配置（API 地址、缓存大小等）
├── core/
│   └── api_client.dart       # HTTP 客户端（重试、Session）
├── controllers/
│   ├── auth_controller.dart  # 登录认证
│   ├── player_controller.dart# 播放引擎
│   ├── download_controller.dart # 下载管理
│   └── theme_controller.dart # 主题管理
├── models/
│   ├── music_models.dart     # 音乐领域模型
│   └── app_version.dart      # 版本更新模型
├── services/
│   ├── music_api.dart        # API 接口封装
│   ├── cache_service.dart    # 数据缓存（SWR）
│   ├── download_service.dart # 文件下载服务
│   ├── music_audio_handler.dart # 后台音频服务
│   └── ...                   # 其他服务
└── ui/
    ├── app_theme.dart        # 主题定义
    ├── adaptive_layout.dart  # 响应式布局
    ├── pages/                # 页面
    │   ├── home_page.dart    # 首页
    │   ├── player_page.dart  # 播放器
    │   ├── library_page.dart # 我的
    │   ├── search_page.dart  # 搜索
    │   └── ...               # 其他页面
    └── widgets/              # 可复用组件
        ├── mini_player.dart  # 迷你播放栏
        ├── artwork.dart      # 封面组件
        └── ...               # 其他组件

---

📝 更新日志

详细的版本更新日志请查看 update.md。

v2.0.5 主要更新：

• 播放历史 & 统计页面
• 搜索历史、缓存管理可视化
• 歌单排序 & 批量删除 & 分享 & 导入
• 智能音质降级 & 网络自动重试
• 封面加载 Shimmer 动画

---

📄 许可证

本项目仅供学习交流使用，请勿用于商业用途。

---

_{Made with XiaoMai and Flutter}