NetEase Cloud Music NCM decryptor & downloader — full metadata, lyrics, cover art
Install • Quick Start • Commands • 中文
pip install git+https://github.com/CPbianma/ncmdec.gitOr for development:
git clone https://github.com/CPbianma/ncmdec.git
cd ncmdec
pip install -e .Requires Python 3.10+. Zero heavy dependencies — the AES implementation is pure Python (NIST-vector tested), the NCM audio cipher is a period-256 keystream XOR, so no C compiler is needed.
# 1. Extract login cookie from the running NetEase Cloud Music client
# (decrypts the client's Chromium cookie store; validates it online)
ncmdec auth
# 2. Download a song (search + download + tag in one step)
ncmdec download "陈奕迅 不要说话" -o ~/Music -q flac
# 3. Or by numeric song id
ncmdec download 25906124 -o ~/Music -q flac --lrc
# 4. Decrypt local .ncm files downloaded by the official client
ncmdec decrypt ~/CloudMusic -o ~/Music| Command | Description |
|---|---|
ncmdec auth |
Extract login cookie from the running client / its cookie store |
ncmdec init --cookie <MUSIC_U> |
Manually set the cookie (full string or bare 32-hex token) |
ncmdec doctor |
Check configuration & login status |
ncmdec search <keyword> |
Search songs |
ncmdec download <keyword|id> |
Search + download + tag one song |
ncmdec album <album_id> |
Batch download one album |
ncmdec artist <artist_id> |
Batch download all albums of an artist |
ncmdec playlist <playlist_id> [-n limit] |
Batch download a playlist |
ncmdec decrypt <path> |
Decrypt local .ncm files |
ncmdec url <song_id> |
Print the direct download URL (debug) |
| Value | Meaning | Requires |
|---|---|---|
flac |
lossless (asks for best, server decides) | logged-in VIP cookie |
320 |
320 kbps MP3 | free songs: anonymous OK |
128 |
128 kbps MP3 | anonymous OK |
When the requested quality is unavailable, download falls back to 320 → 128 automatically (reported in the JSON output as quality).
Two strategies, in order — every candidate cookie is validated online against /api/nuser/account/get before being saved:
- Chromium cookie store of the client's embedded browser (
webapp91x64): the AES key is DPAPI-unprotected fromLocalPrefs.json, the cookie value is Chromiumv10AES-256-GCM. Works even while the client is closed. - Process memory scan of every
cloudmusic.exeforMUSIC_U=<32-hex>tokens (stale tokens get rejected by validation).
Anonymous usage (no cookie) still supports search, lyrics, tagging, local .ncm decrypt, and 320 kbps downloads of free songs.
NetEase ranks results by playability for the requesting account. Tracks the account cannot play (removed catalogs such as parts of 周杰伦's discography, region locks) are pushed below covers even when logged in — that is the server's ranking, not a client bug. Use -n to pick an alternative result, or download by numeric song id.
Every downloaded/decrypted file gets complete metadata:
- Title / Artist / Album Artist / Album
- Track number / Year (from the album)
- Lyrics (original LRC with the Chinese translation interleaved line-by-line)
- Cover art (1000x1000 album artwork)
--lrcadditionally writes a sibling.lrcfile for external-lyrics players
ncmdec decrypt handles .ncm files produced by the official client:
- key blob: XOR 0x64 → AES-ECB(
hzHRAmso5kInbaxW) → RC4-style KSA - metadata: XOR 0x63 → base64 → AES-ECB(
#14ljk_!\]&0U<'() → JSON - audio: period-256 keystream XOR (tiled + big-int XOR, tens of MB/s in pure Python)
Output extension is sniffed from the decrypted header (.flac / .mp3 / .ogg / .m4a), falling back to the embedded metadata. Even fully offline, title / artist / album come from the metadata embedded in the file; with network, year / track number / cover / lyrics are enriched from the API.
ncmdec auth：自动从正在运行的网易云音乐客户端提取登录 Cookie（解密其内置浏览器的 Cookie 库，或扫描进程内存），并在线验证。ncmdec download "歌名 歌手" -o 目录 -q flac：搜索并下载，自动写入完整标签（标题/歌手/专辑/音轨/年份/封面/歌词），--lrc额外导出 .lrc。ncmdec decrypt 目录：解密本地.ncm文件（无需登录）。- VIP 歌曲需要黑胶账号的 Cookie 才能取到无损链接；免费歌曲匿名即可下 320k。
- 搜索结果按账号可播性排序：周杰伦等下架曲库的翻唱会排在前面，属服务端行为，用
-n选择其他结果或直接用歌曲 id 下载。
MIT