kumone README

The project's README from github.com/missuo/kumone. As one markdown file: README.md.

English | 简体中文

Kumone

Kumone

雲の音 — Native macOS client for NetEase Cloud Music

Built with SwiftUI · Talks directly to NetEase's real API · Sparkle auto-updates

Platform Swift License

Home Now Playing
Daily Recommendations Lyrics Panel

About the Name

Kumone comes from the Japanese 雲の音 (kumo no ne, "the sound of clouds"), contracted into one word — 雲音 (くもね, kumone). It is a nod to the "cloud" in NetEase Cloud Music: the music drifting down to you from the cloud.

Features

Installation

Requires macOS 15+ (Universal: Apple Silicon and Intel).

Homebrew

brew install owo-network/brew/kumone --cask

Manual download

Download the latest Kumone-x.y.z.zip from Releases, unzip, and drag it into Applications.

The app is signed with a Developer ID certificate and notarized by Apple, with built-in Sparkle automatic updates (menu bar: Kumone → Check for Updates…).

iOS / iPadOS (sideload)

Every release ships an unsigned Kumone-iOS-x.y.z.ipa (iOS 16+). Kumone is an unofficial client and will not be on the App Store or TestFlight, so install it with a sideloading tool that signs the IPA with your own Apple ID — AltStore, SideStore, Sideloadly or Xcode all work. On iOS 26+ the tab bar is the system’s native Liquid Glass; on iOS 16–25 it falls back to a simulated glass bar.

Updating: iOS apps can't replace themselves. Settings → About → Check for Updates tells you when a newer release exists and links to it; download the new IPA and reinstall with the same tool — sign-in state and settings are kept. AltStore / SideStore can also track the release automatically via a source.

In-app auto-update (TrollStore only)

On a device with TrollStore (巨魔), Kumone updates itself: Settings → About → Check for Updates (it also checks on launch) downloads the new IPA with a progress ring and hands it to TrollStore via apple-magnifier://install?url=… for a one-tap, fully automatic install — the same mechanism Dopamine uses. This works only under TrollStore: a plain AltStore/SideStore sideload is signed with a personal certificate and has no way to install an IPA on-device, so there it degrades to opening the release page for a manual re-sideload.

Enabling CarPlay (iOS)

CarPlay support is fully implemented in Sources/Kumone/Core/CarPlay/, but the default build ships none of it: no com.apple.developer.carplay-audio entitlement, no UISupportsCarPlay, and no CarPlay scene declaration. Apple only grants that entitlement after you submit a CarPlay audio app application, and building with it unapproved fails to sign with:

Entitlement com.apple.developer.carplay-audio not found and could not be included in profile.

So CarPlay is a one-command opt-in instead:

make configure-carplay   # enable
make configure           # back to the default, CarPlay-free build

make configure-carplay derives a CarPlay copy of Config/Info.plist and Config/KumoneIOS.entitlements into ios/Config/Generated/, then writes ios/Config/CarPlay.local.xcconfig to point the build at them. All three files are untracked, and the Xcode project itself is never modified — so enabling CarPlay leaves git status clean and produces nothing to review.

Once your developer account has the entitlement approved:

  1. Apply for and obtain the CarPlay (Audio) capability for your App ID in Apple Developer → Identifiers.
  2. Regenerate the provisioning profile so it carries the new capability.
  3. Run make configure-carplay.
  4. Cmd + Shift + K and rebuild on a device.

To test without a car, use the CarPlay Simulator: Xcode ▸ Open Developer Tool ▸ Simulator, then I/O ▸ External Displays ▸ CarPlay.

Building

Requires macOS 15+ and Xcode 26+.

swift build                    # compile
Scripts/build-app.sh           # package the .app (outputs .build/app/Kumone.app)
Scripts/compile_and_run.sh     # kill → repackage → relaunch

Architecture

Sources/Kumone/
├── Core/
│   ├── API/            # NeteaseCrypto (weapi/eapi encryption), NeteaseClient (transport + cookies), NeteaseAPI (~50 endpoints)
│   ├── Models/         # unified Track model (tolerates both JSON shapes), lyrics parser
│   ├── Player/         # PlayerService (queue / shuffle / repeat / FM / URL resolution), UnblockService, NowPlayingManager
│   └── Storage/        # AccountStore, SettingsManager, two-tier image cache
├── DesignSystem/       # design tokens, button styles (hover scale / row highlight / chips), skeletons, cards, marquee, artwork palette
└── Features/           # pages + player bar + immersive now-playing + lyrics/queue panels

No third-party API server involved: weapi (double AES-CBC + RSA) and eapi (AES-ECB + MD5 digest) encryption are implemented natively in Swift, and requests go straight to music.163.com / interface.music.163.com.

Want a tvOS build? Check out Sonimbus, a NetEase Cloud Music client for Apple TV maintained by my friend Svend.

Credits

Kumone is written from scratch in Swift. No code was copied from the projects below, but their design and implementation ideas were referenced extensively:

License

Licensed under LGPL-3.0-only (the GPL-3.0 text is included alongside). For learning and personal use only — all music data and rights belong to NetEase Cloud Music and the respective source platforms. No downloading, no social features.

kumone (missuo/kumone)

Searching Database…

1.2K ·GitHub
Kumone
Что это?Kumone — неофициальное нативное macOS-приложение (есть и сборка для sideload на iOS), выступающее клиентом NetEase Cloud Music: написано на SwiftUI и общается напрямую с настоящим API NetEase без каких-либо сторонних серверов-посредников.
Нужен ли аккаунт NetEase Cloud Music, чтобы им пользоваться?Да, вход выполняется сканированием QR-кода через официальное приложение NetEase Cloud Music; полученные cookies хранятся локально и дальше обновляются автоматически. Также требуется macOS 15+ (Universal-сборка для Apple Silicon и Intel) или iOS 16+.
Есть ли подводные камни, о которых стоит знать заранее?Поддержка CarPlay встроена в бинарник, но по умолчанию поставляется выключенной, потому что Apple редко выдаёт entitlement на CarPlay-аудио; лицензия также явно ограничивает приложение личным/учебным использованием без скачивания и без социальных функций.
Работает ли и на Apple Silicon, и на Intel Mac?Да, macOS-сборка — это Universal-бинарник, работающий нативно и на Apple Silicon, и на Intel Mac, требуется macOS 15 или новее.
Что на самом деле делает разблокировка «серых» треков?Это нативная реализация на Swift ключевых источников UnblockNeteaseMusic (pyncmd, Kuwo, Kugou), которая автоматически находит треки, помеченные NetEase как недоступные или доступные только в ознакомительном режиме, подтягивая их из сторонних источников.
Можно включить поддержку CarPlay самостоятельно?Только если ваш собственный аккаунт Apple Developer получит одобрение entitlement CarPlay Audio; тогда 'make configure-carplay' сгенерирует нужные конфиги, и вы пересоберёте проект в Xcode — в сборке по умолчанию это выключено.
Есть ли текст песни поверх экрана, как плавающее окно?Да, строка текста песни в стиле LyricsX — всегда поверх всех окон, с переводом; её можно перетаскивать, а позиция сохраняется между Spaces и полноэкранными приложениями.
Откуда взялось имя Kumone?Это стяжение японской фразы 雲の音 (kumo no ne, «звук облаков»), отсылка к «облаку» в NetEase Cloud Music.
What are similar projects?Beans-Music, textream, tvbox-silicon, zulu, CodeEdit, KiwiDesk, awesome-mac, opendisplay
Which topics is it in?audio-streaming, media-player, lgpl, music-player, qr-code, ios-app, swiftui, apple, macos-app, app, i18n, reverse-engineering
Creator
missuo
Size
23.2 MB
Stars
1.2K
Updated
CommitOct 08Releasev0.3.20Oct 03
Age
2mo
Commits · 90 Days