ESC
开源 4 分钟阅读

kumone: 雲の音 — Native macOS NetEase Cloud Music client built with SwiftUI

kumone 是原生 macOS 网易云音乐客户端，基于 SwiftUI 构建，直接调用网易云真实 API。支持二维码登录、每日推荐、沉浸式播放页、多音质（含 Hi-Res）和灰色歌曲解锁等功能，并通过 Sparkle 自动更新。该项目以满足用户需求和不俗的界面设计受到关注。

来源：GitHub

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

HomeNow Playing
Daily RecommendationsLyrics 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

  • 🔐 QR code login — scan with the NetEase Cloud Music app; cookies are persisted locally and auto-refreshed
  • 🏠 Home — daily recommendations, Personal FM, Heartbeat Mode, recommended playlists, radar playlists (Personal Radar family, personalized per account), charts, new albums, recommended artists
  • 🧭 Explore — category playlists (curated / official / charts / mood) with infinite scrolling
  • 🎵 Playback — AVPlayer engine, Standard to Hi-Res quality (lossless with 黑胶 VIP, automatic fallback), shuffle / repeat one / repeat all, play-next queue, gray track detection
  • 🔓 Gray track unblocking — native implementation of UnblockNeteaseMusic’s core sources (pyncmd / Kuwo / Kugou); unavailable or trial-only tracks automatically resolve from third-party sources
  • 🖼 Immersive now-playing page — artwork-tinted gradient backdrop, large artwork, big synced lyrics (click the player-bar artwork to open, Esc to close)
  • 📻 Personal FM — immersive roaming page with trash / skip
  • 📝 Lyrics — glass side panel with line-synced lyrics + translation, click to seek
  • 🪟 Desktop lyrics — LyricsX-style floating always-on-top lyric line with translation; draggable, persisted position, visible across Spaces and full-screen apps
  • 📚 Library — liked songs, created / subscribed playlists, saved albums, followed artists, recently played, cloud disk
  • ✏️ Playlist management — create / delete / subscribe playlists, add / remove tracks, heart songs
  • 🔍 Search — aggregate / songs / artists / albums / playlists, trending keyword placeholder
  • ⌨️ System integration — media keys / Control Center (Now Playing), scrobbling, playback queue restored across launches
  • 🌐 Localization — English and Simplified Chinese, following the system language; bilingual release notes in Sparkle updates

Installation

Requires an Apple Silicon Mac running macOS 15+.

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…).

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.

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:

  • YesPlayMusic (MIT, © qier222) — feature design, NetEase API endpoints and behavior
  • kaset (MIT, © sozercan) — UI design system, motion, and SwiftPM packaging approach
  • UnblockNeteaseMusic/server (LGPL-3.0-only) — third-party source endpoints and matching strategy for gray tracks (UnblockService.swift is an independent Swift reimplementation)
  • LyricsX (MPL-2.0, © ddddxxx) — desktop lyrics window design reference (window configuration, screen-factor positioning; DesktopLyrics.swift is an independent SwiftUI implementation)

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.