kmgcc/kmgccc_player
kmgcc/kmgccc_player has 225 GitHub stars and 14 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 23:54 UTC. Last push 2026-10-28.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
一个开源 macOS 本地音乐播放器,支持 AMLL 歌词、实时音频可视化,可选接入 Apple Music 等外部播放源,并提供各种艺术风格的播放界面。
Creative & MediaREADME.md
Original
kmgccc_player
面向 macOS 26 的本地音乐播放器。
原生开发,注重美学与沉浸式体验。
[!WARNING] kmgccc_player 是个人项目,可能存在缺陷、未完成特性或行为变动。不建议在重要环境中作为唯一播放器使用。欢迎通过官网或 Issue 反馈问题。
作为喜欢音乐,绘画多年的枸,我想为音乐播放器添加一份随性与独特的美感。感谢你的使用和喜欢!
主要功能
- 现代本地曲库:支持多资料库独立管理与原位目录引用,无需移动或复制音频文件即可直接映射既有文件夹,并提供专辑、艺人与文件夹层级平行的双轴浏览体验。
- 原生 Swift 歌词:采用纯原生 Core Text 排版与 Core Animation 动效管线,紧随音频硬件时钟起伏实现细腻的逐字呼吸与弹簧滚动,能耗与发热显著降低,并完美支持 ProMotion 120Hz 高刷新率。
- 外部播放协同:无缝读取 Apple Music 及系统全局媒体的正在播放状态,自动关联高精度歌词与高清封面。
- 多元视听皮肤:内置多款精心调校的 Now Playing 与全屏皮肤,支持随乐曲脉动的多形态实时音频频谱与波形可视化。
- 动态色彩系统:从专辑封面中提炼具有视觉张力的 OKLCH 语义色,自适应生成舒适通透的视窗质感与高可读性歌词配色。
- 纯粹本地优先:全部元数据解析、全文搜索索引与偏好统计皆在 Mac 本地无声运行,无需注册账号,零网络依赖,尊重听者的隐私与数据掌控。
系统要求
- macOS 26.0 或更新版本
- Apple Silicon Mac
从源码构建
git clone --recurse-submodules https://github.com/kmgcc/kmgccc_player.git
cd kmgccc_player
./scripts/bootstrap.sh
./scripts/verify.sh
open kmgccc_player.xcodeproj
如果已经用普通 git clone 下载,先补齐 submodule:
git submodule update --init --recursive
bootstrap.sh 会下载并构建 AMLL、LDDC Fetch Core、QQ Music Helper、MediaRemoteAdapter 和 SACAD 五个外部运行组件。首次运行需要下载依赖并编译多个 ARM64 产物,耗时较长;之后会比对源码和工具链状态,未变化的组件直接复用缓存。
verify.sh 在提交改动前运行,依次执行 bootstrap、ARM64 Debug 构建、LRC 回归测试、单元测试和 App bundle 检查。
构建并运行 Debug App:
./scripts/build_and_run.sh
验证 Release 构建及 App bundle 完整性:
./scripts/build_app.sh Release
本机可选构建输入通过 Config/LocalOverrides.xcconfig 配置;可从同目录的 .example 复制。该文件缺失时工程照常构建,verify.sh 与 build_app.sh 会显式禁用本机构建扩展,确保结果可由 clean clone 复现。
开发环境需要:
- Xcode 26.2 或更新版本(Swift 6)
- Node.js 22(含 Corepack)
- ARM64 Python 3.12
- CMake 3.15 或更新版本
- Git、curl 和 Xcode Command Line Tools
外部组件的详细说明见 docs/dependencies.md。
技术文档
我们在 docs/README.md 中系统梳理了应用的架构理念、核心算法与工程实现,文档面向开源贡献者与对实现细节感兴趣的开发者:
- 应用架构:应用组合根、资料库 Session 隔离、本地与外部播放主链路及统一展示模型;
- 原生 Swift 歌词系统:Core Text 字体排版度量、Core Animation 遮罩动效、弹簧物理滚动与硬件时钟同步;
- 现代本地音乐资料库体系:原位引用与托管双模式、多资料库隔离、标签与目录双轴浏览哲学;
- 色彩系统:基于 OKLCH 与 Display P3 的封面取色、语义映射与局部可读性算法;
- 曲库搜索 与 偏好随机播放:基于 SQLite FTS5 的本地检索以及结合听觉行为的探索衰减模型;
- 实现约束与坑:关键业务逻辑中生效的硬性约束与避坑备忘录。
常见问题
- AMLL submodule 缺失或 commit 不一致:运行
git submodule sync --recursive,再git submodule update --init --recursive。 - 找不到 node 或 corepack:安装 Node.js 22,确认两个命令都在 PATH 中。
- Python 版本或架构不符:安装 ARM64 Python 3.12,或用
KMGCCC_ARM_PYTHON=/path/to/python3.12 ./scripts/bootstrap.sh指定。 - 找不到 CMake:安装 CMake 3.15 或更新版本(MediaRemoteAdapter 需要)。
- Xcode 报外部组件产物缺失:回到仓库根目录运行
./scripts/bootstrap.sh。 - 产物被判定为 stale:用
./scripts/bootstrap.sh --force --component <name>重建对应组件。失败时查看.build/logs/。 - Swift Package 解析失败:确认网络可访问 GitHub 后重试。
参与贡献
缺陷和功能建议可提交到 GitHub Issues。请先搜索已有 Issue,附上 macOS 版本、Mac 架构、复现步骤和预期结果。安全问题不要发公开 Issue,请按 SECURITY.md 的私密渠道报告。
贡献代码前请阅读 CONTRIBUTING.md。
致谢
本项目在开发过程中使用并修改了以下开源项目:
- applemusic-like-lyrics (AMLL) — 歌词背景网格动效,通过项目维护的 integration fork 集成
- MelismaKit — 原生 Swift 歌词排版与动效渲染引擎
- LDDC — 歌词获取与匹配
- apple-audio-visualization — 音频频谱分析与可视化算法
- ncmdump — NCM 格式解密
- sacad — 专辑封面搜索与下载
- QQMusicApi — QQ 音乐元数据与封面查询
- MediaRemote Adapter — macOS 外部播放状态读取与控制
- WhatsNewKit — 应用更新说明展示
- PLCrashReporter — 主 App 进程崩溃报告捕获
- Sparkle — 软件自动更新检查与交付框架
美术素材版权声明
除代码及另有说明的第三方内容外,本项目相关的美术素材(包括界面插画、UI 装饰、贴图、角色设计、图形元素及其他视觉素材)均为作者原创作品,著作权及相关权利均由作者保留。未经作者事先书面授权,不得复制、转载、分发、修改、改编、商用、二次创作、提取,或用于机器学习与生成式 AI 相关用途。
保留一切权利。Copyright © kmg. All rights reserved.
许可证
代码基于 GNU Affero General Public License v3.0 (AGPL-3.0) 发布。第三方组件遵循各自的开源许可证,详见应用内 About 页面及 Licenses 目录。