Search packages, repositories and app categories

GitHub repositoryumr-xiaomai/kgka_Music_hl

kgka_Music_hl

Flutter 开发的酷狗音乐客户端

kgka_Music_hl project cover
Stars
546
Forks
40
Last push (UTC)
Sep 17, 2026
Project status
Active

Original README

English project snapshot. Visit GitHub for the latest content.

KA Music Logo

KA Music

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

Flutter Dart Version License

Android iOS Windows macOS Linux Web


📖 简介

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

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


📸 预览

功能截图

首页推荐 播放器 歌词
首页 播放器 歌词
个人库 搜索页 歌单详情
我的 搜索 歌单

✨ 核心功能

🎵 音乐播放
  • 多音质切换 — 标准 (128K) / 高品质 (320K) / 无损 (FLAC) 三种音质
  • 智能降级 — 播放失败时自动降级到更低音质重试,保证播放连续性
  • 后台播放 — 支持 Android 通知栏控制及锁屏播放
  • 播放模式 — 列表循环 / 随机播放 / 单曲循环
  • 倍速播放 — 支持 0.5x ~ 3.0x 变速播放
  • 音频均衡器 — 7 种预设音效(流行、摇滚、人声、低音、古典、电子、平板)
  • 低音增强 — 0~100% 强度可调
  • 定时停止 — 支持按时间或当前歌曲播放完毕后自动停止
🎤 歌词
  • 逐字歌词 — 支持 KRC 格式的逐字高亮歌词
  • 歌词翻译 — 支持翻译和罗马音显示
  • 桌面歌词 — 桌面端悬浮歌词窗口
  • 歌词交互 — 双击跳转进度 / 长按复制 / 字体大小可调
🔍 搜索与发现
  • 多平台搜索 — 支持酷狗 + 网易云音乐双源搜索
  • 搜索建议 — 实时搜索联想
  • 热搜关键词 — 分类展示热门搜索
  • 搜索历史 — 本地保存,支持标签式快捷搜索
  • 每日推荐 — 个性化歌曲推荐
  • 推荐歌单 — 热门歌单浏览
  • FM 电台 — 推荐电台 + 分类电台
📚 音乐库管理
  • 歌单管理 — 创建 / 收藏 / 重命名 / 排序 / 批量删除
  • 歌单分享 — 一键复制歌单歌曲列表到剪贴板
  • 歌单导入 — 通过 ID 导入他人歌单
  • 歌单内搜索 — 快速查找歌单中的歌曲
  • 收藏歌曲 — 我喜欢 / 收藏管理
  • 云盘 — 个人云盘音乐存储
  • 专辑商店 — 新专辑浏览
📥 下载与缓存
  • 下载管理 — 支持并发下载、断点续传、进度追踪
  • 播放缓存 — 自动缓存播放过的歌曲,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
编译环境变量
变量 说明 默认值
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

XiaoMai GitHub avatar
GitHub author

XiaoMai ↗

LanguagesDartKotlinC++CMakeSwiftRubyHTMLCObjective-C

Dependencies used

Dependency list 18 items

Rankings

How do I choose a repository?

Start with your use case, compare repository activity, and check the original project before adopting it.

  1. Search by repository name, owner or description, then narrow the results by topic.
  2. Compare stars, forks and recent pushes. Stars show community interest, not a guarantee of quality.
  3. Read the README, license and issues on GitHub before using a project.

Sources and maintenance

“A repository is the most basic element of GitHub.”

GitHub Docs — About repositories ↗