ncm-cli-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ncm-cli 安装配置

ncm-cli Installation and Configuration

ncm-cli 是网易云音乐的 CLI 工具（音乐搜索、播放控制、歌单管理、TUI 播放器）。

ncm-cli is a CLI tool for NetEase Cloud Music (supports music search, playback control, playlist management, and TUI player).

安装流程

Installation Process

第一步：安装 ncm-cli、mpv

Step 1: Install ncm-cli and mpv

1.1 安装 ncm-cli

1.1 Install ncm-cli

bash

npm install -g @music163/ncm-cli

验证安装：

bash

ncm-cli --version

bash

npm install -g @music163/ncm-cli

Verify installation:

bash

ncm-cli --version

1.2 安装 mpv

1.2 Install mpv

播放功能需要 mpv 播放器。先检测是否已安装：

bash

mpv --version

macOS / Windows：若未安装，直接执行安装脚本：

bash

python3 scripts/install_mpv.py

Linux：询问用户是否需要播放功能：

如果是桌面环境、需要本地播放 → 执行
```
python3 scripts/install_mpv.py
```
如果是服务器环境、不需要播放 → 跳过，搜索/歌单等命令仍可正常使用

安装脚本会自动识别包管理器：

macOS：Homebrew（
```
brew install mpv
```
）或 MacPorts
Linux：apt / dnf / pacman / zypper
Windows：winget / Chocolatey / Scoop

Playback functionality requires the mpv player. First check if it is already installed:

bash

mpv --version

macOS / Windows: If not installed, run the installation script directly:

bash

python3 scripts/install_mpv.py

Linux: Ask the user if playback functionality is needed:

If it's a desktop environment and local playback is required → run
```
python3 scripts/install_mpv.py
```
If it's a server environment and playback is not needed → skip, commands like search/playlist can still be used normally

The installation script will automatically identify the package manager:

macOS: Homebrew (
```
brew install mpv
```
) or MacPorts
Linux: apt / dnf / pacman / zypper
Windows: winget / Chocolatey / Scoop

第二步：配置 API Key

Step 2: Configure API Key

使用 ncm-cli 需要先设置API Key：

bash

ncm-cli config set appId <你的AppId>
ncm-cli config set privateKey <你的PrivateKey>

如果还没有 API Key，请先前往网易云音乐开放平台申请 API Key（appId 和 privateKey）。

Using ncm-cli requires setting the API Key first:

bash

ncm-cli config set appId <your AppId>
ncm-cli config set privateKey <your PrivateKey>

If you don't have an API Key yet, please go to NetEase Cloud Music Open Platform to apply for an API Key (appId and privateKey).

第三步：配置默认播放器

Step 3: Configure Default Player

询问用户选择默认播放器：

mpv（内置播放器）：轻量、跨平台，需先完成第一步中的 mpv 安装
orpheus（云音乐 App）：调用本地网易云音乐客户端播放，仅支持 macOS

根据用户选择执行：

bash

ncm-cli config set player mpv      # 选择内置播放器
ncm-cli config set player orpheus  # 选择云音乐 App

Ask the user to select the default player:

mpv (built-in player): Lightweight, cross-platform, requires completing mpv installation in Step 1 first
orpheus (Cloud Music App): Calls the local NetEase Cloud Music client for playback, only supports macOS

Execute according to the user's selection:

bash

ncm-cli config set player mpv      # Select built-in player
ncm-cli config set player orpheus  # Select Cloud Music App

第四步：登录

Step 4: Login

登录是必须的，请使用：

bash

ncm-cli login --background

bash

ncm-cli login --background

常见问题

Common Issues

问题	解决方法
`ncm-cli: command not found`	检查 npm 全局 bin 是否在 PATH 中： `npm bin -g`
`mpv not found`	重新运行 `python3 scripts/install_mpv.py` 或手动安装：https://mpv.io
登录超时	重新执行 `ncm-cli login --background`

Issue	Solution
`ncm-cli: command not found`	Check if the npm global bin directory is in PATH: `npm bin -g`
`mpv not found`	Re-run `python3 scripts/install_mpv.py` or install manually: https://mpv.io
Login timeout	Re-run `ncm-cli login --background`

基本信息

Basic Information

需要 Node.js >= 18

Requires Node.js >= 18