# KugouMusic.NET: a native Avalonia client for Kugou, built because Linux lacked one > KA Music is a .NET 10 and Avalonia desktop client for Kugou Music with a native desktop stack rather than an Electron wrapper, shipping a tray icon, desktop lyrics window, auto update and a local library that can import Jellyfin media folders. It also contains a Kugou business SDK, an ASP.NET Core wrapper around it, a terminal player and a Native AOT export layer. **Linsxyx/KugouMusic.NET** — 基于 .NET 10 与 Avalonia 打造的轻量级跨平台酷狗音乐客户端。 - Repository: https://github.com/Linsxyx/KugouMusic.NET - Stars: 934 · Forks: 69 - Language: C# - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/linsxyx-kugoumusic-net ## A native desktop stack instead of a browser wrapper The project describes itself in Chinese as the best and lightest Kugou Music Concept Edition player, and immediately qualifies that: the phrase is a goal and a design direction rather than a measured claim. The README adds a note saying exactly that. The technical choice behind the goal is the interesting part. The project is built on .NET 10 and Avalonia, and the stated aim is a consistent cross platform desktop experience rather than a browser shell style client. The README justifies the choice by pointing at the author's own setup: a long time using Arch Linux and Windows in dual boot, and a shortage of a complete Kugou player on Linux. That origin story explains the feature list better than a generic feature list would. The claimed advantages are that it is lighter, because it does not go the Electron route and the installer stays small, and that it behaves like a desktop player rather than a web page: tray, desktop lyrics, close behaviour and auto update are all described as complete desktop interactions. The Linux section makes the same point in stronger terms, saying the goal is not to merely run on Linux but to fill in the experiences Linux desktop users actually care about, with the lyrics floating window behaving like the Windows one, supporting mouse pass-through, staying on top and transparency. That is a specific and defensible claim for an Avalonia application. The same UI tree and the same interaction code run on all three platforms, so fixing a behaviour on one platform fixes it everywhere, which is exactly the maintenance problem that Electron based players accept in exchange for a web stack. The audience is desktop Kugou users, most of them on Linux where the author found the gap. ## Downloads are per-architecture archives, and only some of them auto update Installation is a download from the Releases page rather than a package manager, and the README lists exactly what is published. On Windows there is `KugouAvaloniaPlayer-win-x64.exe`. On Linux x64 there is `KugouAvaloniaPlayer-linux-x64.AppImage`, and on Linux arm64 there is a manual update archive, `KugouAvaloniaPlayer-linux-arm64.tar.gz`. For macOS there is an arm64 installer, `KugouAvaloniaPlayer-mac-arm64-Setup.pkg`, plus a manual arm64 archive `KugouAvaloniaPlayer-mac-arm64.app.zip` and a manual x64 archive `KugouAvaloniaPlayer-mac-x64.app.zip`. Auto update is provided through Velopack together with GitHub Releases, and it is not universal. The architectures that support auto update are Windows x64, Linux x64 and macOS arm64. Linux arm64 and macOS x64 are manual update only. The manual procedure is to download the new archive for your architecture, then either overwrite the old program directory or move to a new directory and run from there. The README warns that manual updates produce no prompt, so you have to watch the Releases page yourself. One dependency detail catches Linux users out. Linux builds use the system SQLite, `libsqlite3.so.0`, and do not bundle the native library. On UOS, Debian or Ubuntu, if the library is missing, the runtime package is: ```bash sudo apt install libsqlite3-0 ``` Windows and macOS keep using the SQLite shipped with the program. macOS has its own wrinkle, since the current installer is unsigned and Gatekeeper may block it. The README gives the command for that case: ```bash xattr -dr com.apple.quarantine /Applications/KugouAvaloniaPlayer.app ``` And if the pkg installer will not install at all, the arm64 zip can be unpacked and run directly. ## Online playback needs a login, local playback does not The feature list is split into four groups, and the split maps onto a real difference in how the client behaves. Online content covers sign-in by phone number verification code and by QR code scan, with login persistence and automatic session recovery, daily recommendations, discovered playlists and recommended content, leaderboards with paged chart songs, artist detail pages, search across songs, playlists and albums, and user information with VIP status display. The local music library covers a home screen for local playlists, imported folders and Jellyfin libraries. You can import a local music folder, with thousands of songs still importing quickly, refresh an already imported folder or a Jellyfin library, set cover art for local playlists and songs, match lyrics and artists, and play local songs without being logged in. The supported audio formats are listed as MP3, FLAC, WAV, OGG, M4A, AAC, WEBM, DSF and DFF, and local lyrics in KRC, LRC, VTT and QRC are supported. The Jellyfin import is the part that distinguishes this from a plain streaming client. Because the library can be pointed at a Jellyfin media library and organised into local playlists by album, the client can act as a front end for a self hosted collection rather than only for the Kugou catalogue. Playback control and quality includes online song playback, queue management, next track and shuffle modes, switching quality on the fly, and a 10 band equaliser with presets and custom settings, plus favouriting the current song and adding or editing online playlists. The desktop experience list covers the lyrics window, per character lyric highlighting with progress animation, a system tray menu, a configurable close behaviour of either quitting or minimising to the tray, and auto update. There is also playlist migration: the README says playlists can be parsed and imported from NetEase Cloud Music and QQ Music, which is aimed at users moving between Chinese music services. The FAQ section is candid about the constraints. Online playback requires a valid login state, so an unlogged user can only play imported local songs. If playback fails entirely, the advice is to sign in again to obtain a new url, and if the url is obtained but playback still fails, to turn off the system proxy. ## The repository is an SDK plus three front ends, not just an app The developer entry points listed in the README are the more interesting part of this project for anyone who wants to build on it. `src/Libraries/KuGou.Net` is the Kugou business SDK, wrapping login, search, playlists, lyrics, leaderboards and user capabilities. `src/Apps/KugouAvaloniaPlayer` is the Avalonia desktop client, the app now called KA Music. `src/Apps/KgTest` is a terminal TUI player, described as a test player that is workable and now includes the smart transition feature. `src/Apps/KgWebApi.Net` is an ASP.NET Core Web API wrapper built on the SDK. `src/Libraries/SimpleAudio` is a cross platform playback and sound effects layer based on ManagedBass. `src/Libraries/AvaloniaLyrics` is a lyrics control library. `src/Native/KuGou.Net.Native` exports the SDK capabilities as a Native AOT friendly C ABI. That last layer is the one that sets the project apart from a personal music player. Exporting the Kugou capabilities through a C ABI makes them reachable from native code and from other languages without going through .NET, which is the prerequisite for Native AOT and for embedding in a host that is not .NET. The Web API project turns the same SDK into an HTTP surface, and the README gives the development documentation address as `http://localhost:5058/scalar/v1`. That is a Scalar style API reference page, which is how you would explore the SDK's endpoints without reading the C# source. The repository layout matches. There is a `KugouMusic.NET.slnx` solution file, a `Directory.Packages.props` for central package versions, and a `tools/` directory alongside `src/` and `docs/`. The README also credits two inspirations: KuGouMusicApi and folia-major. ## Local development needs a stable .NET 10 SDK and a Windows-specific target The project supports .NET 10 only, and the README asks local developers to install a stable .NET 10 SDK, with CI using the .NET 10 SDK. The target frameworks are stated precisely: the Windows player targets `net10.0-windows10.0.19041.0`, while the remaining projects and the non-Windows player target `net10.0`. That Windows-specific target is worth noting because it explains why the platform builds are separate artifacts rather than one self-contained executable. The Windows build depends on the Windows 10 19041 API surface, and the Linux and macOS builds cannot share that target. The clone and build sequence is the standard .NET one: ```bash git clone https://github.com/Linsxyx/KugouMusic.NET.git cd KugouMusic.NET dotnet restore KugouMusic.NET.slnx dotnet build KugouMusic.NET.slnx dotnet run --project src/Apps/KugouAvaloniaPlayer/KugouAvaloniaPlayer.csproj ``` Running the other two entry points follows the same shape, with the project path changing: ```bash dotnet run --project src/Apps/KgTest/KgTest.csproj ``` ```bash dotnet run --project src/Apps/KgWebApi.Net/KgWebApi.Net.csproj ``` One FAQ entry connects directly to this workflow and explains a behaviour that otherwise looks like a bug. Auto update depends on the Velopack installation, so if you run the app with `dotnet run` or by copying files manually, the application skips the auto update check entirely. The README says to use the Releases installer if you want updates. The Windows auto update failure case has its own explanation: check whether you have moved the files, or whether you installed into a high privilege directory such as Program Files, Windows or System. That is a useful pair of diagnostics because both causes are outside the application. The terminal player's own documentation, including its features, key bindings and configuration, lives in `src/Apps/KgTest/README.md`. ## An Android client is announced but not shipped The quick start section lists the developer entry points and then adds that an Android version is in development, with a separate project address at the umr-xiaomai/kgka_Music_hl repository. That belongs in a different category from everything else in this project, and it is worth being precise about it. The desktop applications, the SDK, the Web API wrapper, the terminal player and the Native AOT export layer are all in this repository and all buildable today. The Android client is a separate repository, in development, and none of the release artefacts listed here are for Android. So if you are evaluating this for a phone, the answer is that this repository is not the thing you install, and the announcement is a pointer to work in progress elsewhere. Two smaller naming details from the FAQ are also worth recording, because they look like inconsistencies but are deliberate. The application display name is KA Music while the package and artefact names remain KugouAvaloniaPlayer, and the README explains this is to keep the historical upgrade path working: the display name can keep improving while the package identifier stays stable, which avoids breaking the upgrade chain from older versions. And the phrase about being the best and lightest player carries the note that it is a project goal and design direction rather than a benchmark claim. The project also maintains a QQ group, number 1081635731, listed in the README as the discussion channel. ## MIT licence, fast release cadence, and a public API disclaimer The licence is MIT, and the release history is quick. v4.2.1 was published on 2026-10-18, v4.2.0 on 2026-10-17 and v4.1.0 on 2026-09-20, with the last push on 2026-10-18. Two releases a day apart is normal for a project in active development with an active user base, and it also means the README changelog is a summary rather than a full history. From the changelog in the README, v4.2.0 added two playback themes modelled on the Folia player, fixed a failure fetching leaderboards, added escape key handling on some pages, improved the settings page and fixed some known issues. v4.1.0 fixed Linux arm64 not working and fixed some known issues. v4.0.0 brought a brand new playback theme, desktop lyrics that remember their position and lock state, fixes for some page rendering and a new icon set. The full version history is on the Releases page. The disclaimer at the end of the README states that the project is a third party music client developed on the basis of public API interfaces. That sentence matters for anyone considering it seriously, and it cuts both ways. It means the project is not asking to be used to break DRM or to bypass a paid tier, since it works through the interfaces the service already exposes. It also means the project depends on interfaces that the service can change at any time, and that the client cannot be guaranteed to keep working when it does. The VIP status is displayed rather than circumvented, and the paid tier is left as the service defines it. For an evaluation, that framing is the right lens: this is a desktop client for a catalogue, not a way around the catalogue's business model. An Android build is in development in a separate repository, so the current release scope remains desktop only. ## Conclusion KugouMusic.NET suits a desktop user on Linux, macOS or Windows who wants the Kugou catalogue with real desktop behaviour, lyrics and a local library in one native client, and it is the wrong choice if you expect offline-first playback, because online playback needs a valid login and the local library is the only path that works without one. Verify three things before you install: that your platform matches a published package, because Linux arm64 and macOS x64 get manual update archives only, that the system SQLite library is present on Linux where the player expects libsqlite3.so.0 rather than bundling it, and that you are comfortable with a third party client built on public API interfaces, as the project's own disclaimer states. ## FAQ ### Which platforms does KugouMusic.NET support? Windows, Linux and macOS. The README lists a Windows x64 executable, a Linux x64 AppImage, a Linux arm64 manual update archive, a macOS arm64 installer and manual archives for macOS arm64 and x64. Linux builds also need the system SQLite library, libsqlite3.so.0. ### Does KugouMusic.NET support auto update on every platform? No. Auto update through Velopack and GitHub Releases works on Windows x64, Linux x64 and macOS arm64. Linux arm64 and macOS x64 receive manual update archives only, and manual updates give no prompt, so you have to watch the Releases page. ### Why does my KugouMusic.NET build not update automatically? Auto update depends on the Velopack installation, so running with `dotnet run` or copying files manually makes the app skip the update check. The README says to install from the Releases package instead. ### Can I play music in KugouMusic.NET without logging in? Only local files. The README states that online playback requires a valid login state, while imported local songs can be played without being logged in. Local formats include MP3, FLAC, WAV, OGG, M4A, AAC, WEBM, DSF and DFF. ### Can KugouMusic.NET read a Jellyfin library? Yes. The local music library section supports importing a Jellyfin media library and generating local playlists by album, alongside importing local music folders and refreshing either of them. ### How do I run the Kugou SDK as an HTTP API? Run the Web API project with `dotnet run --project src/Apps/KgWebApi.Net/KgWebApi.Net.csproj`. The development documentation is served at `http://localhost:5058/scalar/v1`. ## Sources - [Issues](https://github.com/Linsxyx/KugouMusic.NET/issues) - [License: MIT](https://github.com/Linsxyx/KugouMusic.NET/blob/master/LICENSE) - [Linsxyx/KugouMusic.NET on GitHub](https://github.com/Linsxyx/KugouMusic.NET) - [README](https://github.com/Linsxyx/KugouMusic.NET/blob/master/README.md) - [Releases](https://github.com/Linsxyx/KugouMusic.NET/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linsxyx-kugoumusic-net