Beans Music: an iOS SwiftUI client for NetEase, QQ Music and Kugou

What Beans Music actually is, and who it is built for

Beans Music is an open-source SwiftUI music player for iOS 15 and later, published as the public iOS client under the MIT License. The README lists three platform integrations by name: NetEase Cloud Music, QQ Music, and Kugou Music. Around those it wraps account login, synced playlists, favorites, rankings, artists, albums, recent plays, a playback queue with shuffle and repeat, playback speed, a sleep timer, background playback, and lock-screen controls.

The audience is narrow in a useful way. This is a repository for someone who wants to read SwiftUI view code and platform networking side by side, or who wants to build their own client and is willing to sign it. It is not a hosted service and there is no App Store listing described anywhere in the README. The repository describes itself as being for study, and the licence text repeats the boundary: music, trademarks, and platform services belong to their respective owners, and the README asks users to follow each platform's terms of service.

That framing matters more than it first appears. A player that talks to three commercial platforms is doing something the platforms themselves do not publish a supported client API for. The README does not claim any official partnership or sanctioned access, and the presence of a dedicated UnblockService.swift file in the project layout suggests user-side source resolution is part of the design rather than an afterthought.

How the app is wired: one file per platform, one manager for playback

The project layout in the README is the clearest description of the architecture available. Each platform gets its own file: NetEaseAPI.swift, QQMusicAPI.swift, KugouMusicAPI.swift. The development notes state that the project keeps platform-specific networking inside the corresponding API files, which means the request shapes, headers and response parsing for each service stay in one place instead of being spread across views.

Above that sits PlayerManager.swift, described as handling queue, playback, history, and recovery. That is the piece that survives navigation: RootView.swift provides tab navigation and a mini player, while PlayerView.swift holds the full player and the lyrics experience. DiscoverView.swift, SearchView.swift, LibraryView.swift and ProfileView.swift map to the four user-facing surfaces (home and rankings, search, synced and local libraries, and account plus appearance, backup and settings).

Two more files carry state that is easy to underestimate. DownloadManager.swift handles audio download and export, and Theme.swift holds theme and wallpaper state. Models.swift is shared across all of it. The README does not document a caching layer, a database schema, or how history is persisted, so anyone planning to extend the project should read PlayerManager.swift first rather than assume the storage model from the file names.

Building Beans Music from source with XcodeGen

The README gives an explicit build path. Requirements are macOS, Xcode 26 or later, and XcodeGen. The project file is generated rather than committed, which is why project.yml sits at the repository root and why the first step is to install the generator.

brew install xcodegen
xcodegen generate

After that, the README builds an unsigned app for a physical device SDK. Note that code signing is switched off deliberately, so this produces an unsigned build rather than something you can install on a device without further signing work.

xcodebuild \
  -project Beans.xcodeproj \
  -scheme Beans \
  -configuration Release \
  -sdk iphoneos \
  -derivedDataPath build \
  CODE_SIGNING_ALLOWED=NO \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGN_IDENTITY="" \
  build

The README also states that the GitHub Actions workflow can build an unsigned IPA on demand, and that the workflow is configured for test builds by default and does not create a release unless explicitly enabled. That is the practical route if you do not want to run xcodebuild locally, but the same signing caveat applies to the artifact.

For a first real use, the sensible path is to open the generated project in Xcode, run it in the simulator, and start with SearchView: the README lists platform search across all three services, and search is the surface that exercises the API files without requiring account login first. The README does not document a demo account, sample credentials, or a mock mode, so expect the platform-facing screens to be empty or failing until you configure something yourself.

The sources are not in the repository, and that is the main constraint

The development notes state plainly that user-configured music sources are stored locally and are not bundled with this repository. UnblockService.swift exists to resolve user-configured sources. Read together, those two facts define the real failure mode: a fresh clone builds, launches, and can browse whatever the platform endpoints return, but resolution of restricted content depends on configuration the project deliberately does not ship.

The README also instructs contributors not to commit credentials, cookies, API keys, personal files, build artifacts, or local configuration. That is a sensible rule and it is also a warning about how the app is meant to be used. If you are looking for a turnkey streaming client, this is the wrong tool, and not because of a bug. It is the wrong tool because the design assumes you bring your own account and your own source configuration, and because the project's own framing is study rather than distribution.

A second limitation is environmental. Xcode 26 or later is a hard requirement in the README, and the Liquid Glass styling is described as applying on supported systems. On older toolchains or older iOS versions you should expect the styling path to be skipped rather than emulated. The README does not describe a fallback design for those systems beyond the iOS 15 minimum.

How it compares with a self-hosted server plus a thin client

The obvious alternative approach is a self-hosted music server that indexes your own library and serves it to a generic client, with the server owning metadata, transcoding and streaming. That model puts the hard part on a machine you control and keeps the mobile app comparatively dumb.

Beans Music inverts that. There is no server component in the repository layout. The iOS app holds the platform integrations, the playback manager, the download manager and the theme state, and it talks directly to NetEase, QQ Music and Kugou from the device. The trade-off is concrete: you get a native SwiftUI experience with lock-screen controls and lyrics without running any infrastructure, but every platform change lands in an app update rather than a server-side fix, and anything requiring credentials lives on the phone. The README's instruction not to commit local configuration is a direct consequence of that architecture.

A second alternative is using the official first-party app for each service. Those will always have better platform coverage and no build step. What they will not give you is one queue across three services, a configurable player layout, or source code you can read. That combination, not playback quality, is the reason to consider this project.

Maintenance, upgrades and what the MIT licence does not cover

The repository is not archived, and the last push was on 2026-09-16. Two releases are listed in the recent history: v1.6.5.1 on 2026-09-04 and v1.6.6 on 2026-09-06. A VERSIONING.md file sits at the root alongside CHANGELOG.md, so the project documents its own versioning policy, but the README does not restate it and does not describe a migration path between releases. The 1.6.5.1 to 1.6.6 step is the kind of patch-level change you would check CHANGELOG.md for before upgrading.

Upgrade cost is dominated by the toolchain rather than by the code. Because the project file is generated from project.yml, a dependency or target change means regenerating with xcodegen generate rather than resolving a merge in a committed .xcodeproj. That is cleaner for contributors and slightly more surprising for anyone who expects to open the repository and build immediately.

The MIT License covers the code in this repository. It does not cover the music, the trademarks, or the platform services, and the README says so explicitly. THIRD_PARTY_NOTICES.md exists at the root for the dependencies. Whether your use of a given platform's endpoints is permitted is a question for that platform's terms of service, not for this licence, and the README's own guidance is to use the app responsibly and follow those terms.

Editorial conclusion

Beans Music is for iOS developers who want a readable SwiftUI reference for multi-platform music browsing and playback, and for users willing to compile an unsigned app themselves. It is not for anyone expecting a signed App Store build, a working out-of-the-box streaming client, or a documented API contract: the README states that user-configured music sources are stored locally and are not bundled, so playback of third-party content depends on configuration you supply. Before adopting it, verify the Xcode 26 requirement against your toolchain, read THIRD_PARTY_NOTICES.md and 说明.md alongside the README, and check VERSIONING.md to see what a 1.6.5.1 to 1.6.6 upgrade is expected to involve.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. XIaodou0416/Beans-Music on GitHub