# go-music-dl: a Go music downloader with Web, TUI and desktop modes

> go-music-dl aggregates search across more than ten Chinese music platforms and can resolve FLAC from NetEase, QQ Music and Bilibili. It ships as a CLI, a web service, a TUI and a desktop app, under AGPL-3.0.

**guohuiyuan/go-music-dl** — 一个基于 Go 语言的全网音乐搜索与下载工具。支持 CLI 命令行与 Web 服务双模式，内置网易云、QQ、酷狗、Bilibili、汽水音乐等 10+ 个主流平台，支持多源并发搜索与无损音质解析。music-dl交流群：755087923

- Repository: https://github.com/guohuiyuan/go-music-dl
- Website: https://music.zkkp.nyc.mn
- Stars: 5,008 · Forks: 479
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/guohuiyuan-go-music-dl

## What go-music-dl searches that a single-platform downloader cannot

A downloader for one service gives you one catalogue and one set of failure modes. go-music-dl is built around the opposite assumption: the README lists NetEase Cloud Music, QQ Music, Kugou, Bilibili, Qishui Music and others, and describes multi-source concurrent search as a core feature. The same query can return results from several platforms at once, and the Web interface lets you tick which sources participate.

The audience is narrow but real. It is for people who want a self-hosted service on a home server or NAS, who are comfortable running a Docker container, and who read Chinese. The homepage, screenshots and most of the documentation are Chinese-first, and the supported platforms are Chinese streaming services. There is a mobile build, an Android APK with ffmpeg and ffprobe bundled, and an unsigned iOS IPA that the README says users must sign themselves.

Beyond single tracks, the README describes playlist and album search, playlist category browsing across NetEase, QQ, Kugou, Kuwo, Migu, Qianqian, JOOX and Apple Music, and a "my playlists" view for logged-in accounts on NetEase, QQ, Kugou and Qishui. That is a broader scope than most download scripts attempt, and it is also where the project accumulates the most platform-specific code to maintain.

## How the Go service, the music-lib dependency and the SQLite index fit together

go.mod shows the shape of the project. The HTTP layer is gin, the terminal interface is charmbracelet's bubbletea and lipgloss, the desktop builds use gioui.org plus webview bindings, and storage is glebarez/sqlite through gorm. Platform logic is not in this repository: it is delegated to github.com/guohuiyuan/music-lib, the same author's library, which the README says was synced for Migu, Jamendo, JOOX, Qianqian and Qishui playlist and album functions. So go-music-dl is largely a front end over music-lib plus local state.

That local state matters more than it first appears. Settings and the local music index live in data/settings.db. The README states that on startup the service asynchronously builds an index table of the download directory in that file, upserting rows as files are scanned and clearing rows when files disappear. Keyword search over local files then runs against SQLite instead of rescanning the disk, with an existence check on the hits so deleted or moved files do not appear.

The caching design is explicit. GET /api/local_music caches its result for 10 seconds; within that window repeat requests return the snapshot. When the cache expires, the service returns the previous result immediately and rescans in the background, showing a notice in the UI. Per-file metadata (title, artist, album, cover, lyrics, duration, bitrate) is keyed on path plus file size plus modification time, so unchanged files skip ffprobe and tag parsing. Uploads and deletions invalidate the snapshot, and ?refresh=1 forces a full rescan.

This is a sensible design for a directory that can hold thousands of files, and the README is unusually specific about it. The trade-off is that the index and the filesystem can disagree for up to one scan cycle, and the existence check is the only thing standing between a stale index and a broken result.

## Running go-music-dl in Docker and making a first search

The repository ships a Dockerfile and a compose file, so the container path is the shortest one. The image builds the binary with CGO_ENABLED=0, runs Alpine 3.22, installs ffmpeg, and verifies both ffmpeg and ffprobe during the build. The compose file pins the published image, maps port 8080, mounts ./data to /home/appuser/data, and starts the web mode.

```yaml
services:
  music-dl:
    image: guohuiyuan/go-music-dl:latest
    container_name: music-dl
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/home/appuser/data
    environment:
      - TZ=Asia/Shanghai
    command: [ "./music-dl", "web", "--port", "8080", "--no-browser" ]
```

After docker compose up, open http://localhost:8080/music. The README says the web service mounts under /music by default. Search, playback, download and playlist browsing work without logging in; only the settings panel, saving system settings, managing platform cookies and QR-code login require an administrator account. If no admin exists, the terminal prints a one-time initialization token on first use of a system configuration action, and you set a username and a password of at least 6 characters on the initialization page. Session cookies last 7 days by default.

If you prefer the terminal, the TUI takes a keyword directly:

```bash
./music-dl -k "搜索关键词"
```

To serve the same web UI under a subpath behind a reverse proxy, the README documents --base-path:

```bash
./music-dl web --base-path /dl
```

One practical detail for anyone enabling metadata embedding: the README recommends leaving "embed cover and lyrics" off, because the default streaming download is faster and supports Range requests for seeking. Turning it on requires FFmpeg, and without it the service skips embedding and returns the original audio.

## Where go-music-dl breaks or is the wrong choice

The project's own README documents a live failure: Qishui Music's PC passport QR login depends on dynamic a_bogus and msToken anti-abuse signatures, the flow is not working, and the QR entry has been hidden in the web UI. Qishui playlist and download features therefore require a manually configured cookie. That is a concrete example of the general risk with this class of tool: platform-side changes silently remove capability, and the fix lives in music-lib, not here.

There are other boundaries. Lossless FLAC is documented for NetEase, QQ Music and Bilibili only, so a user expecting lossless from every listed source will be disappointed. Paid resources are filtered out, which means some searches return less than the platform shows in its own app. Cookie storage is local (data/settings.db, with the WebDAV password not echoed back by the settings API), but the README warns not to share configuration files containing cookies; anyone running this on a shared host should treat that file as a secret.

The local music feature has sharp edges too. Deleting a local track is a hard delete: the file is removed from the download directory and the index entry cleared, after a confirmation. Playlists that referenced it keep the entry as invalid, and you can re-point that entry to an online source. External imported playlists and albums do not accept local tracks. And the filename template supports {name}, {artist}, {album}, {source}, {id} and {ext}, with slashes creating subdirectories; if you omit {ext} the extension is appended automatically. Get the template wrong and you will be reorganizing files by hand.

Finally, if what you need is a stable API with a versioned contract, this is the wrong tool. It is a scraper-driven downloader over third-party services, and its correctness depends on those services.

## go-music-dl against yt-dlp: aggregation versus extraction

The closest mental comparison is yt-dlp, and the difference is the layer each one works at. yt-dlp extracts streams from a site's own pages and APIs, one extractor per site, and it is used mostly for video platforms and for audio ripped from them. go-music-dl does not extract from a page in that sense; it queries music-lib, which talks to each platform's search and song endpoints, and it adds a web UI, local library management and playlist browsing on top.

That gives go-music-dl two things yt-dlp does not have out of the box: a browser interface with per-source checkboxes and a persistent local music index, and first-class handling of Chinese music platform login cookies via QR scan for NetEase, QQ Music, Kugou and Bilibili. In the other direction, yt-dlp covers a far wider range of sites and is not tied to Chinese streaming services or to one author's library.

The practical split: if your target is a Chinese music platform and you want a self-hosted web front end with playlists, go-music-dl is the more direct fit. If your target is a video site, or you need one tool that covers many unrelated sources, yt-dlp is the broader instrument.

## Licence, maintenance and what upgrading actually costs

go-music-dl is AGPL-3.0. For anyone running it at home that changes nothing. For anyone who modifies it and exposes it as a network service, the AGPL's source-availability obligation is the part to read carefully, and that is a question for a lawyer rather than for this article. The bundled music-lib dependency is a separate module with its own licence, which is worth checking before redistribution.

The maintenance signal is good but should be read precisely. The last push was on 2026-09-17, and v1.1.1 was released the same day, with v1.1.0 on 2026-08-30 and v1.0.34 on 2026-08-27. The repository is not archived. What those dates do not tell you is whether the upstream platforms still behave; a release can ship while a given source is broken, as the hidden Qishui QR entry shows.

Upgrade cost is mostly in local data rather than in the binary. Settings and the local music index live in data/settings.db, and the Docker setup mounts ./data, so a container swap preserves both. Platform cookies are in that same file, meaning an upgrade that changes cookie handling may require re-authenticating. If you enable WebDAV sync, the remote path, username and password are stored server-side and are not returned by the settings API, so a fresh deployment needs them re-entered. The 10 second snapshot cache and the path/size/mtime metadata keys mean a large library will rebuild its index after a version that changes the index schema, but the README does not document a migration step for that case.

## Conclusion

Adopt go-music-dl if you want a self-hosted web service or CLI that searches several Chinese platforms at once and can pull FLAC from NetEase, QQ Music or Bilibili, and if you accept AGPL-3.0 terms. Skip it if you need stable access to a specific platform's paid catalogue, if you cannot run FFmpeg for metadata embedding, or if you want a maintained API contract rather than a scraping tool that tracks upstream changes. Before deploying, verify that your target sources still respond, that ffmpeg and ffprobe resolve inside the container, and that a scan of your download directory completes under the default 10 second cache.

## FAQ

### What is go-music-dl?

It is a Go music search and download tool that supports Web, TUI and desktop modes, aggregates search across more than ten platforms, and can resolve lossless FLAC from NetEase, QQ Music and Bilibili. It is licensed AGPL-3.0.

### What is the best music downloader?

There is no single answer, and the README makes no such claim. go-music-dl fits cases where you want a self-hosted web service or CLI that searches several Chinese platforms at once and can download FLAC from NetEase, QQ Music and Bilibili; a tool aimed at other sites or other formats would be a different choice.

### Why is Google music no longer available?

This question is about Google Play Music, not about go-music-dl, and the repository material says nothing about Google's service. For go-music-dl, the README does document one source that is currently unavailable: Qishui Music's QR login depends on dynamic a_bogus and msToken signatures, the flow is not working, and the QR entry has been hidden in the web UI.

### Is Go-Go Music still around?

This question refers to Go-Go music, a genre, and not to the go-music-dl project, so the repository material cannot answer it. The project itself is not archived: the last push was on 2026-09-17, and v1.1.1 was released the same day.

## Sources

- [guohuiyuan/go-music-dl on GitHub](https://github.com/guohuiyuan/go-music-dl)
- [License: AGPL-3.0](https://github.com/guohuiyuan/go-music-dl/blob/main/LICENSE)
- [Project website](https://music.zkkp.nyc.mn)
- [README](https://github.com/guohuiyuan/go-music-dl/blob/main/README.md)
- [Releases](https://github.com/guohuiyuan/go-music-dl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/guohuiyuan-go-music-dl