kmgccc_player：macOS 本地音乐播放器

项目简介

kmgccc_player 是一款面向 macOS 26 的本地音乐播放器，使用 Swift / SwiftUI 原生开发，注重美学与沉浸式体验。项目由个人维护，主页为 https://player.kmgccc.cn。

作者定位它为「喜欢音乐与绘画」的人做的一份随性美感：既有现代曲库管理，也有可看的歌词动效和音频可视化。

主要功能

• 现代本地曲库：支持多资料库独立管理与原位目录引用，无需移动或复制音频文件即可直接映射既有文件夹，并提供专辑、艺人与文件夹层级平行的双轴浏览体验。
• 原生 Swift 歌词：采用纯原生 Core Text 排版与 Core Animation 动效管线，随音频硬件时钟实现逐字呼吸与弹簧滚动，降低能耗与发热，并支持 ProMotion 120Hz。
• 外部播放协同：可读取 Apple Music 及系统全局媒体的正在播放状态，自动关联歌词与高清封面。
• 多元视听皮肤：内置多款 Now Playing 与全屏皮肤，支持随乐曲脉动的多形态实时音频频谱与波形可视化。
• 动态色彩系统：从专辑封面提炼 OKLCH 语义色，自适应生成视窗质感与歌词配色。
• 纯粹本地优先：元数据解析、全文搜索索引与偏好统计均在本地完成，无需注册账号，零网络依赖。

安装与使用

系统要求：macOS 26.0 或更新版本，Apple Silicon Mac。安装包可在 Releases 页面下载（DMG 为安装包）。

从源码构建：

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 五个外部运行组件，首次运行耗时较长，之后未变化的组件会复用缓存。

构建并运行 Debug App：

./scripts/build_and_run.sh

验证 Release 构建及 App bundle 完整性：

./scripts/build_app.sh Release

开发环境需要：Xcode 26.2 或更新版本（Swift 6）、Node.js 22（含 Corepack）、ARM64 Python 3.12、CMake 3.15 或更新版本，以及 Git、curl 和 Xcode Command Line Tools。

注意事项

• 项目为个人作品，可能存在缺陷、未完成特性或行为变动，不建议在重要环境中作为唯一播放器使用。
• 本机可选构建输入通过 Config/LocalOverrides.xcconfig 配置，可从同目录的 .example 复制。
• 常见问题：AMLL submodule 缺失或 commit 不一致时执行 git submodule sync --recursive 后再 git submodule update --init --recursive；Python 架构不符可用 KMGCCC_ARM_PYTHON=/path/to/python3.12 ./scripts/bootstrap.sh 指定；产物被判定为 stale 时用 ./scripts/bootstrap.sh --force --component <name> 重建，日志在 .build/logs/。
• 代码以 AGPL-3.0 发布；界面插画、UI 装饰、角色设计等美术素材为作者原创并保留全部权利，未经书面授权不得复制、转载、修改、商用或用于生成式 AI 相关用途。

---

本作品整理自 GitHub 开源项目 kmgcc/kmgccc_player，原作者 @kmgcc，许可证 AGPL-3.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。