Kumone: a native macOS NetEase Cloud Music client in SwiftUI

What Kumone is, and the account it assumes you already have

Kumone is a client, not a service. The README describes it as a native macOS client for NetEase Cloud Music, built with SwiftUI, that talks directly to NetEase's real API. Everything you see in the app, from daily recommendations to lyrics, is fetched from that API using your own account. There is no Kumone server, no proxy and no bundled catalogue. If you do not have a NetEase Cloud Music account, the app has nothing to show you.

That shapes the audience. The project targets people who already pay for or use NetEase Cloud Music and find the web player or a wrapped desktop build unsatisfying on macOS. The feature list reads like a checklist of what those users miss: QR code login with cookies persisted locally and auto-refreshed, lossless quality up to Hi-Res with an automatic fallback, and a gray track detection path for tracks that are unavailable or trial-only in your region. The name itself is a nod to the cloud in NetEase Cloud Music, per the About the Name section.

The platform floor is macOS 15 or newer, Universal for Apple Silicon and Intel. That is a recent floor, and it is a deliberate one: the project uses Swift 6.2 and Xcode 26 or newer to build. Anyone on an older Mac is not the target.

How the client talks to NetEase, and where the local state lives

The architecture visible in the repository is a SwiftPM package under Sources/ with a separate iOS project under ios/, plus Tests/ for the macOS suite. The macOS app is built with swift build and bundled by Scripts/build-app.sh. The iOS side has its own package at ios/KumoneIOSPackage and an Xcode project regenerated from ios/project.yml with XcodeGen, which the Makefile exposes as make project. The iOS project file is generated, not hand-edited, which matters if you plan to change build settings.

Authentication is QR code based. The README states that cookies are persisted locally and auto-refreshed, so the app holds your session rather than asking you to log in on every launch. Playback uses AVPlayer, and the quality ladder runs from Standard up to Hi-Res, with lossless gated behind 黑胶 VIP and an automatic fallback when the higher tier is not available to your account. Shuffle, repeat one, repeat all, a play-next queue and gray track detection are all listed as part of the playback layer.

The gray track path is the most interesting piece of engineering in the project. The README describes it as a native implementation of UnblockNeteaseMusic's core sources, naming pyncmd, Kuwo and Kugou. When a track is unavailable or trial-only, Kumone resolves it from those third-party sources instead. That is a real design decision with real consequences: it means the app's correctness depends on services outside NetEase, and those sources can change or disappear without any release from this project. The README does not document what happens when all three sources fail, beyond the implication that the track stays unavailable.

System integration is handled through the standard macOS surface: media keys and Control Center Now Playing, scrobbling, and a playback queue restored across launches. Desktop lyrics are implemented as a floating always-on-top lyric line with translation, draggable, with a persisted position and visible across Spaces and full-screen apps. That is a LyricsX-style approach, and the README compares it to LyricsX by name.

Installing Kumone with Homebrew and signing in for the first time

The README gives two install paths. The Homebrew cask is the shortest, and it requires the owo-network tap:

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

After that finishes, Kumone should appear in Applications. The alternative is to download the latest Kumone-x.y.z.zip from the Releases page, unzip it and drag the app into Applications. The README states that the app is signed with a Developer ID certificate and notarized by Apple, so Gatekeeper should not block the first launch on a supported Mac.

Once the app is open, the first real task is signing in. Kumone uses QR code login, so the flow is: open the app, find the login entry, and scan the code with the NetEase Cloud Music mobile app. The README says the cookies are then persisted locally and auto-refreshed, which means you should not need to repeat this unless the session is invalidated server-side.

Updates after that are handled by Sparkle. The menu bar item Kumone → Check for Updates… is the manual trigger, and the README notes that release notes are bilingual. If you would rather build from source, the README's Building section requires macOS 15+ and Xcode 26+, and the entry point is:

swift build                    # compile

For a bundled .app rather than a bare binary, the Makefile target is make app, which calls Scripts/build-app.sh. The Makefile also defines make test for the macOS SwiftPM suite. The iOS targets, make ios-test and make ios-uitest, drive simulators and take an IOS_DESTINATION override, defaulting to an iPhone 17 Pro simulator.

CarPlay is implemented but deliberately not shipped

This is the part of the project most likely to confuse a new user. The README states that CarPlay support is fully implemented under Sources/Kumone/Core/CarPlay/, with Now Playing, tabbed library, queue and search templates present in the binary, yet the default build ships none of it: no com.apple.developer.carplay-audio entitlement, no UISupportsCarPlay, and no CarPlay scene declaration.

The reason is Apple's entitlement process. Apple grants the CarPlay audio entitlement only after an application, and the README quotes the signing failure you get without it: "Entitlement com.apple.developer.carplay-audio not found and could not be included in profile." Because that entitlement is per-app and not granted to most accounts, the project keeps it out of the default configuration that CI and every contributor gets.

Enabling it is a one-command opt-in:

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

According to the README, 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 generated files are untracked and the Xcode project itself is never modified, so enabling CarPlay leaves git status clean. That is a thoughtful arrangement, but it does not change the practical outcome: unless your own Apple developer account has the CarPlay (Audio) capability approved, you cannot ship or sideload a working CarPlay build. The README's own steps require applying for the capability, regenerating the provisioning profile, running make configure-carplay, then a clean build (Cmd + Shift + K) on a device. For testing without a car, it points at the CarPlay Simulator under Xcode's I/O ▸ External Displays menu.

iOS sideloading, TrollStore, and the update trap

Kumone is not on the App Store or TestFlight, and the README says plainly that it will not be, because it is an unofficial client. Every release ships an unsigned Kumone-iOS-x.y.z.ipa for iOS 16 and above, which you install with a sideloading tool that signs it with your own Apple ID: AltStore, SideStore, Sideloadly or Xcode. On iOS 26 and later the tab bar uses the system's native Liquid Glass; on iOS 16 through 25 it falls back to a simulated glass bar.

The update story is where the platform fights back. iOS apps cannot replace themselves, so the README describes Settings → About → Check for Updates as a notifier: it tells you a newer release exists and links to it, and you download the new IPA and reinstall with the same tool. Sign-in state and settings are kept, according to the README. AltStore and SideStore can also track the release automatically via a source.

The exception is TrollStore. On a device with TrollStore, Kumone updates itself: Settings → About → Check for Updates, or the automatic check on launch, downloads the new IPA with a progress ring and hands it to TrollStore via apple-magnifier://install?url=… for a one-tap install. The README notes this is the same mechanism Dopamine uses, and that it works only under TrollStore. A plain AltStore or SideStore sideload is signed with a personal certificate and cannot install an IPA on-device, so there the feature degrades to opening the release page for a manual re-sideload. If automatic updates are a requirement for you, this is the deciding constraint, not the feature list.

Where Kumone is the wrong tool

The clearest limitation is scope. Kumone is a NetEase Cloud Music client. It does not play local files as a general library, it does not aggregate other streaming services, and its entire catalogue is whatever your NetEase account can reach. If you want one player for a mixed local and streaming library, this is not it.

Second, the gray track unblocking is a dependency you do not control. The README names pyncmd, Kuwo and Kugou as the core sources. Those are third-party endpoints, and the project's behaviour for a given track depends on them being reachable and unchanged. The README does not document fallback ordering, retry behaviour or what the UI shows when all sources fail, so you should treat unblocking as best-effort rather than a guarantee.

Third, the platform floor is high on both sides: macOS 15+ and Xcode 26+ to build, iOS 16+ for the sideloaded IPA, and CarPlay only with an Apple-approved entitlement. A user on an older Mac, or one who wants CarPlay without going through Apple's application process, is outside what this project supports.

Finally, there is the nature of an unofficial client. Because Kumone talks directly to NetEase's API rather than through an abstraction, changes on NetEase's side can break features between releases. That is inherent to the approach, and the README does not claim otherwise.

How it compares with a browser tab or an Electron wrapper

The most common alternative is the NetEase Cloud Music web player in a browser, or one of the Electron-based desktop clients that wrap it. The difference in approach is architectural. A wrapper renders the web app and inherits its layout, its input handling and its resource usage; it also inherits the browser's media stack. Kumone instead reimplements the client in SwiftUI and plays audio through AVPlayer, which is why media keys, Control Center Now Playing, scrobbling and a restored playback queue are native rather than bolted on. Desktop lyrics as a floating always-on-top window across Spaces are a direct consequence of being a real macOS app rather than a page in a shell.

The trade-off runs the other way too. A web or Electron client usually works on Windows and Linux as well, and it tends to survive API changes because it follows whatever the web app does. Kumone is macOS-only for the desktop build, with a separate iOS target, and it owns its own API calls, so it has to keep up on its own. The README's own comparison point for desktop lyrics is LyricsX, which is a lyrics utility rather than a full client; Kumone folds that behaviour into a player instead of asking you to run two apps.

There is also the UnblockNeteaseMusic project itself, which the README cites as the source of the gray track technique. That is a proxy or patch approach aimed at making unavailable tracks playable across clients. Kumone reimplements the core sources natively inside the app rather than asking you to run a separate proxy. If you already run UnblockNeteaseMusic as a service and are happy with it, the native reimplementation is a convenience, not a new capability.

Licence, maintenance and the cost of upgrading

Kumone is licensed under LGPL-3.0-only, per the badge and the LICENSE file, with COPYING also present at the repository root. That is a copyleft licence, and it is a meaningful choice for a desktop app: if you redistribute a modified build, the LGPL's obligations apply to the library portions. This is not legal advice, and the exact boundary between the app and any linked components is something you should read LICENSE and COPYING to determine for your own distribution plans. Personal use of a downloaded or Homebrew-installed build does not raise the same questions as shipping a fork.

The maintenance picture is straightforward. The repository is not archived, and the last push was on 2026-09-14. Recent releases are v0.3.17 on 2026-09-10, v0.3.16 on 2026-09-04 and v0.3.15 on 2026-09-04. The version numbers in the 0.3.x range and the cadence of the last three releases suggest a project that is still moving, but the README does not publish a support policy, a deprecation policy or a compatibility matrix, so there is nothing to hold the maintainer to.

Upgrade cost depends on how you installed it. Homebrew users get the usual brew upgrade path for the cask. Manual macOS users get Sparkle, which the README describes as built in, with the menu bar item Kumone → Check for Updates…. iOS users pay the highest cost: without TrollStore, every update is a fresh IPA download and a re-sideload, and the README is explicit that the app cannot replace itself. There is no documented rollback procedure in the README, so if a release regresses something you rely on, plan on keeping the previous zip or IPA around yourself.

Editorial conclusion

Adopt Kumone if you already have a NetEase Cloud Music account, run macOS 15 or newer, and want a native SwiftUI client instead of a browser tab or an Electron wrapper. Skip it if you need a cross-platform player, cannot accept an unofficial client whose API calls may break whenever NetEase changes something, or depend on CarPlay without an Apple-approved audio entitlement. Before installing, check the Releases page for the newest signed and notarized zip, confirm your macOS version meets the 15+ floor, and read the LGPL-3.0 terms in LICENSE if you plan to redistribute a build.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. missuo/kumone on GitHub
4. README
5. Releases