taurusxin/ncmdump: Converting Netease Cloud Music ncm files to mp3 and flac

What ncmdump is for, and who actually needs it

Netease Cloud Music stores downloaded tracks in a proprietary ncm container. The file is not playable outside the client, and the audio inside it is encrypted. ncmdump exists to reverse that: the README states it converts downloaded ncm cache files into mp3 or flac. The intended user is someone who has a folder of ncm files on disk and wants ordinary audio files they can move to another player, a phone, or a car stereo.

The README also makes a claim about lineage that matters for anyone comparing forks. This C++ version is described as the earliest version and as the first program of its kind to support ncm conversion, with source replicated from anonymous5l/ncmdump after that original repository was deleted in October 2021. The author credits the earlier work. What this version adds on top, per the README, is cross platform compilation across all major operating systems, fixes for memory overflow problems, and a DLL build that other applications can call.

The project is not a music downloader and it does not touch the network. It reads files you already have. That boundary is worth stating plainly, because a search for the project name often turns up unrelated tools that do something else.

The ncm decryption path and where taglib fits

The repository layout tells you the shape of the program: src/ holds the implementation, example/ holds usage samples for the shared library, test/ holds tests, and CMakeLists.txt plus vcpkg.json drive the build. The README does not document the byte level format of the ncm container or the key derivation, so any description of the cipher itself would be guesswork. What can be said from the README is the data flow at the level the tool exposes.

An ncm file goes in, the tool decrypts the audio payload, and the output is written as mp3 or flac depending on what the source contained. Metadata handling is delegated to taglib, which is why taglib is the one external dependency the build instructions spend time on. On Windows the README uses vcpkg to install taglib as a static library with the x64-windows-static triplet. On macOS it uses Homebrew. On Linux it compiles taglib 2.1.1 from source, because the Ubuntu 24.04 package is still taglib 1.x and does not support CMake. That last detail is not incidental: it is the single biggest difference between building this on macOS and building it on Linux.

The library form, libncmdump, exposes the same conversion to other languages. The README points to the example folder for how to call it, and gives one hard constraint for Windows developers: the filename passed to the library constructor must be UTF-8 encoded, or a runtime error is thrown. That constraint is a direct consequence of the 1.3.0 fix, which the README says made all UTF-8 characters, including Chinese, Japanese, Korean and emoji filenames, decrypt correctly.

Installing ncmdump and converting your first folder

The README recommends downloading a prebuilt binary for your operating system from the Releases page rather than compiling. If a binary exists for your platform, that is the shortest path. Confirm it runs and see the available flags by printing help.

ncmdump -h

The output lists the flags described in the README: -d for a directory, -r to recurse, -o for an output directory, -m to delete source files after a successful conversion, and -v for the version. A single file or a list of files is passed positionally.

ncmdump 1.ncm 2.ncm

For a folder, point -d at the directory. The README notes that without -r only files directly inside that folder are processed, and subfolders are skipped.

ncmdump -d source_dir -o output_dir -r

That command recurses through source_dir, writes results into output_dir, and per the README preserves the directory structure when -r is combined with -o. If you would rather have the originals removed after a successful conversion, add -m. The README says it deletes the source file only when processing succeeded, which makes it safe to combine with a batch run, but it is still a destructive flag and worth testing on a copy of a few files first.

Building from source is a different exercise. On macOS the README installs taglib with Homebrew and then configures and builds with CMake.

brew install taglib
cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build -j$(nproc)

On Linux you first build taglib 2.1.1 from source and install it to /usr/local, then run the same two CMake commands. On Windows the README uses Visual Studio 2022, CMake and vcpkg with the x64-windows-static triplet. The README states the compiled binary and, on Windows only, a shared library for other projects end up in the build folder.

The cover art gap in Netease Cloud Music 3.0 and later

This is the limitation to understand before you commit to the C++ version. The README warns that in some versions of Netease Cloud Music after 3.0, downloaded ncm files no longer embed the album cover image. The cover data has to be fetched from the network instead. The author's stated reasoning is that embedding a large network library inside a small utility is not justified, and the README redirects those users to ncmdump-go or the GUI program ncmdump-gui, both rewritten in Go, which read cover information from metadata and fetch the image over the network before embedding it.

That is a deliberate scope decision, not a bug, but it has a practical consequence. If your ncm files come from a recent client version, the mp3 or flac that ncmdump produces may have correct audio and correct tags but no artwork. Your player will show a blank tile. If artwork matters to you, this is the wrong build to pick, and the README says so itself. If you only care about the audio and the tags, the missing cover is irrelevant.

A second constraint is the UTF-8 filename requirement for the library on Windows. Applications that pass a filename in the platform's local encoding will hit a runtime error rather than a graceful failure. That is a sharp edge for integrators, and the README states it as a must, not a suggestion.

ncmdump versus ncmdump-go and ncmdump-gui

The most useful comparison is not against some other project but against the author's own Go rewrite, because the README frames it that way. The difference is not cosmetic. ncmdump-go and ncmdump-gui are described as complete rewrites in Go, and they add a capability the C++ version deliberately leaves out: reading cover information from metadata and downloading the image from the network to embed in the output file. ncmdump-gui is built on ncmdump-go and provides a visual interface.

So the choice comes down to what you are integrating. If you want a binary to run in a shell script, or a shared library to call from C#, Python or Java, the C++ version fits, and libncmdump is the reason. If you want cover art filled in automatically, or you would rather not touch a command line at all, the Go projects are the ones the README points to. Choosing the C++ version for a desktop user who expects thumbnails is choosing the wrong tool on purpose.

The shared library is also Windows only according to the README. Developers on macOS or Linux who wanted to embed conversion in another language will need to build a library themselves from src/, since the build output described in the README only produces the dynamic library on Windows.

Maintenance, licensing and the cost of upgrading

The repository is not archived. The last push was on 2026-08-20, and the most recent release, 1.5.1, is dated 2025-10-05. Before that, 1.5.0 shipped on 2024-09-25 and 1.4.0 on 2024-09-13. The release cadence is irregular: two releases eleven days apart in September 2024, then a gap of about a year, then 1.5.1. That pattern suggests a project that gets attention when something needs fixing rather than one with a scheduled release train. Plan accordingly if you depend on it in a pipeline.

The licence is MIT, which is permissive and places few obligations on how you redistribute the binary or link the library. This article does not give legal advice; read LICENSE.txt in the repository for the actual terms, and note that the README's account of the code's origin, replicated from a repository that was deleted in 2021, is the kind of provenance question a legal reviewer may want to look at independently.

Upgrade cost is dominated by the taglib dependency rather than by ncmdump itself. On Linux, the build instructions exist specifically because the distribution package is too old, so a fresh build environment needs the manual taglib 2.1.1 step each time unless you cache it. On macOS and Windows, Homebrew and vcpkg handle it. Version 1.3.0 changed filename handling for UTF-8, which is the kind of change that could alter behaviour for existing scripts, so pinning a version and reading the release notes before jumping is the sensible default.

Editorial conclusion

Adopt ncmdump if you already have ncm files sitting on disk and want them as mp3 or flac without a GUI, especially if you need libncmdump from C#, Python or Java. Do not adopt it if you need cover art fetched from the network, or if you want a maintained fork with a visual interface; the README points to ncmdump-go and ncmdump-gui for that. Verify first that your ncm files come from a Netease Cloud Music version before 3.0, since the README states that some 3.0 and later downloads omit the embedded cover image, and check whether the release binary for your platform already exists before compiling taglib 2.x by hand.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. taurusxin/ncmdump on GitHub