Open-source project
taurusxin/ncmdump avatar
taurusxin/ncmdump

ncmdump: converting ncm cache files, and the cover art it cannot fetch

Convert Netease Cloud Music ncm files to mp3/flac files.

4,905 stars554 forksC++MIT

At a glance

What is it?
A C++ converter that turns downloaded NetEase Cloud Music ncm files into mp3 or flac, with six command line flags and a Windows-only dynamic library for calling it from C#, Python or Java. It does not fetch cover art, and on Linux the build needs taglib compiled by hand.
Who is it for?
Use ncmdump if you already have ncm files on disk from the desktop client and you want plain audio files out of them, and if you are on macOS or Windows where the build or the prebuilt binary is the shortest path. Expect no cover art on files produced by recent client versions, and expect to fetch that art with a separate tool.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 87 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • taurusxin/ncmdump4,905 ★ · +324
Star history
Repository2026-09-232026-11-15
taurusxin/ncmdump4.6k4.9k

324 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Five flags cover the whole command line

The CLI is small enough to read in one screen. Help and version come first, and they are the only way to discover anything:

shell
ncmdump -h
shell
ncmdump -v

Files are named positionally, one or many:

shell
ncmdump 1.ncm 2.ncm...

Then three flags do the work. `-d` points at a folder and processes every file with the ncm extension in it, `-r` combines with `-d` to recurse into subfolders, and `-o` sets an output directory, which the README says works together with `-r` and keeps the directory structure when it recurses:

shell
ncmdump -d source_dir -o output_dir -r

The remaining flag is `-m`, which deletes the source file once it has been processed correctly. Six options, one positional list, no configuration file, no environment variable. What is not documented matters as much: there is no note about what happens when the output file already exists, no overwrite flag, no verbosity switch, and no dry run.

-m deletes sources and there is no dry run to try it with

The deletion flag is one line in the README: use `-m` to delete the source file if it is processed correctly. Combined with the folder flags, that is a batch operation that consumes its own input.

shell
ncmdump -d source_dir -r -o output_dir -m

Nothing in the README slows that down. There is no `-n` or `--dry-run`, no confirmation prompt, and no output showing what would be removed. The only discovery tool is `-h`, so the way to find out whether a flag combination is right is to run it on a directory you can afford to lose.

The safer order, then, is: run on a copy first, check that the mp3 or flac files are where you expect and that nothing important was removed, and only then add `-m`. If your input is the only copy of a cache, note that the ncm files come from a download cache in the first place, which means the source is usually recoverable by re-downloading. That is a property of the input, not a permission, so treat it as a convenience and not a plan.

Cover art after client version 3.0 is somebody else's problem

The README carries a warning that is easy to skim past. For some versions of NetEase Cloud Music after 3.0, the downloaded ncm files do not embed the album cover, and the needed cover data has to be fetched over the network. The author's judgement is that embedding a large network library inside a small tool is not worth it, so the fix lives in other programs.

Two are named. There is ncmdump-go, and there is a graphical program, ncmdump-gui, built on top of the Go version. The README says both were rewritten entirely in Go, and that they support reading cover information from metadata, fetching the cover art from the network, and embedding it into the target music file.

So the honest summary is that this converter produces audio files, not complete files. If you are building a library, sorting by album art in a player, or feeding these files to anything that expects embedded art, the C++ version will hand you gaps and the answer is to run a second program. That is a design decision with a stated reason, not an oversight, but it does mean one binary is not the whole job.

Filenames are UTF-8 or the library throws

Version 1.3.0 is the release that fixed filenames. The README explains that earlier versions received a lot of issue reports about being unable to decrypt files whose names contained special characters, naming Chinese, Japanese, Korean and emoji, and that from 1.3.0 onward the problem is completely fixed and every UTF-8 character decrypts normally.

The same entry notes that a dll build now ships alongside the binary, so that other applications, with C#, Python and Java named, can call it. That is what makes the second half of the usage section exist.

The sharp edge is on the caller. If you are developing on Windows, the filename encoding passed to the library constructor must be UTF-8, otherwise a runtime error is thrown. A constructor that throws on a string argument fails at run time, not at build time, and on Windows the natural string type for a path carries whatever code page the caller happened to be in. A C# or Python binding that hands a local-code-page path to `libncmdump` will raise an exception on the first call rather than misbehave quietly, which is the good version of this bug, but it is still a conversion you have to do in your own code.

Linux needs taglib 2.x built and installed by hand

The three platforms have genuinely different setup costs, and Linux is the expensive one. The reason is stated: on Ubuntu 24.04 the taglib package is still 1.x, which does not support CMake, so version 2.x has to be compiled and installed manually. The README adds that the Linux build in GitHub Actions does the same thing by hand.

shell
wget https://github.com/taglib/taglib/releases/download/v2.1.1/taglib-2.1.1.tar.gz
tar -xzf taglib-2.1.1.tar.gz && cd taglib-2.1.1
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release .
make -j$(nproc)
sudo make install

After that the project itself is configured and built exactly as on macOS:

shell
cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build -j$(nproc)

Read what that costs on a shared machine: a source download, a compiler run with every core, and a `sudo make install` writing into /usr/local. If you are on a distribution whose taglib is 2.x already, or you use a container, this step disappears. If you are on Ubuntu 24.04, plan for it before you start, because it is the difference between one command and four.

macOS is one brew command, Windows is a vcpkg bootstrap

macOS is the shortest path. Install taglib through Homebrew, then run the same two cmake commands as everywhere else:

shell
brew install taglib

Windows needs the full toolchain: Visual Studio 2022, cmake, and the C++ desktop development environment, then vcpkg cloned and bootstrapped:

shell
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat

Configuration carries two arguments that matter. The generator is pinned with `-G "Visual Studio 17 2022"`, and the triplet is `-DVCPKG_TARGET_TRIPLET=x64-windows-static`:

shell
cmake -G "Visual Studio 17 2022" -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -B build
cmake --build build -j 8 --config Release

That static triplet is a decision rather than a default. taglib is linked statically, which suits a DLL you intend to ship to another application without asking it to resolve taglib at run time. Worth knowing before you change it.

The repository also ships a `vcpkg.json` manifest.

The DLL is Windows only, and the upstream project is gone

For secondary development, the README points at the `libncmdump` dynamic library, with usage in the repository's `example` folder. The tree at the root holds `CMakeLists.txt`, `vcpkg.json`, `src/`, `test/`, `example/` and `LICENSE.txt`, and the only example listed is `example/csharp/`, so the documented binding is a C# one even though the text names Python and Java as possible callers.

The platform limit matters. The build output paragraph says you will find the compiled binary in the `build` folder, along with a dynamic library that other projects can use, marked Windows only. So on macOS and Linux this repository gives you a program, not an embeddable library. A Python or Java project on those systems has no documented path here.

The lineage explains why this exists at all. The source was recreated from anonymous5l/ncmdump as of 2021-10-06, and the README notes that the original author has deleted that repository. This version is described as the earliest C++ version and the first program on the market to support ncm conversion, with cross-platform porting across operating systems and fixes for some memory overflow problems.

On cadence, releases are 1.4.0 on 2024-09-13, 1.5.0 on 2024-09-25, and 1.5.1 on 2025-10-05, with the last push to the repository on 2026-08-20. The repository is not archived, and the gap between the newest release and the last commit is the normal sign of work landing on main before it is cut.

Editorial conclusion

Use ncmdump if you already have ncm files on disk from the desktop client and you want plain audio files out of them, and if you are on macOS or Windows where the build or the prebuilt binary is the shortest path. Expect no cover art on files produced by recent client versions, and expect to fetch that art with a separate tool. Do not reach for it as a library outside Windows, since the DLL is the only documented embedding path and it needs UTF-8 filenames or it throws at runtime. Before you script anything around it, check three things: that a first run works without `-m`, because that flag deletes sources and no dry run is documented, that the output directory you pass with `-o` does not already hold files, since overwrite behaviour is not documented, and that on Linux you are prepared to install taglib 2.x into /usr/local yourself.

Frequently asked questions

How do I convert ncm files to mp3 with ncmdump?

Download the compiled binary for your system from the project's releases, then pass the files directly with `ncmdump 1.ncm 2.ncm`. Use `-d source_dir` to process every file with the ncm extension in a folder, add `-r` to include subfolders, and add `-o output_dir` to choose where the converted files land.

Does ncmdump delete the original ncm files?

Only if you pass `-m`, which deletes the source file after it has been processed correctly. No dry run flag is documented, so the first run on a directory is safer without it, especially with `-d` and `-r` together.

Why do my converted ncmdump files have no cover art?

For some versions of NetEase Cloud Music after 3.0, the downloaded ncm files do not embed the album cover and the data has to be fetched over the network. The author says embedding a large network library in a small tool is unnecessary, and points to ncmdump-go and the ncmdump-gui program built on it, both rewritten in Go, which fetch the cover and embed it in the target file.

Can I call ncmdump from Python or C#?

Through the `libncmdump` dynamic library, with usage examples in the repository's `example` folder, which contains an `example/csharp/` directory. On Windows, the filename encoding passed to the library constructor must be UTF-8, otherwise a runtime error is thrown, and the dynamic library is Windows only.

How do I build ncmdump on Linux?

taglib on Ubuntu 24.04 is still 1.x and does not support CMake, so build 2.x yourself: download taglib-2.1.1.tar.gz, unpack it, run `cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release .`, then `make -j$(nproc)` and `sudo make install`. After that configure and build the project with `cmake -DCMAKE_BUILD_TYPE=Release -B build` and `cmake --build build -j$(nproc)`.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. taurusxin/ncmdump on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/taurusxin-ncmdump.svg)](https://hysenlabs.com/projects/taurusxin-ncmdump)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/taurusxin-ncmdump.svg)](https://hysenlabs.com/projects/taurusxin-ncmdump)

Was this useful?