# ncm2mp3

**Repository Path**: cbb0416/ncm2mp3

## Basic Information

- **Project Name**: ncm2mp3
- **Description**: 网易云音乐的 `.ncm` 文件转换为常见音频格式（如 MP3/FLAC）工具
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-11
- **Last Updated**: 2025-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NCM2MP3 歌曲转换工具（PyQt5 桌面版）

## 项目简介
- 这是一个基于 PyQt5 的桌面 GUI 应用，用于将网易云音乐的 `.ncm` 文件转换为常见音频格式（如 MP3/FLAC）。
- 提供“添加文件夹、选择性转换、进度显示、完成提示、输出目录选择/记忆”等易用功能。
- 适配 Windows 环境，强调简洁、直观的操作体验。

## 主要特性
- 批量扫描并加载 `.ncm` 文件，显示文件名与大小，提供进度条与状态列。
- 选择性转换：支持仅转换你在表格中选中的行；若未选择，则转换全部。
- 转换完成提示：队列结束时弹出提示框（"All conversions completed."），同时状态栏显示完成信息。
- 统计显示：窗口左下角显示“Selected: X  Remaining: Y”，便于掌握当前选择数量与剩余任务数。
- 输出目录：
  - 勾选“Use Source Folder”时输出到源文件夹；
  - 取消勾选后可通过“Output Folder”指定统一输出路径。
- 路径记忆：使用 QSettings 记住“上次加载文件夹”和“上次输出文件夹”，下次打开对话框将定位到上次路径。
- UI 优化：隐藏 Format/Title/Artist/Output Path 四列以减少拥挤；默认行高增至 32 像素，避免文本裁剪。
- 线程安全退出：在窗口关闭或任务切换时，确保后台线程正确结束，避免 `QThread: Destroyed while thread is still running` 警告或异常。

## 运行环境
- 操作系统：Windows（建议 Windows 10/11）
- Python：3.8+（项目中已使用 venv，推荐使用虚拟环境）
- 依赖：见 `requirements.txt`
  - PyQt5
  - pycryptodome

## 快速开始（推荐使用一键脚本）
项目提供了 `run_install_build.bat`，包含安装、运行、打包三个功能，且安装使用国内镜像（清华源）。该批处理文件输出文本为英文（符合规范）。

1) 安装依赖（国内源）
- 双击 `run_install_build.bat`，选择 `1) Install dependencies (CN mirror)`；或在命令行执行：
```
run_install_build.bat install
```

2) 运行 GUI 程序
- 双击 `run_install_build.bat`，选择 `2) Run GUI program`；或在命令行执行：
```
run_install_build.bat run
```

3) 构建 EXE（PyInstaller）
- 双击 `run_install_build.bat`，选择 `3) Build EXE with PyInstaller`；或在命令行执行：
```
run_install_build.bat build
```
- 构建成功后输出：`dist\ncm2mp3-gui.exe`

## 手动安装与运行（使用国内源）
如不使用批处理脚本，可手动执行以下步骤：

1) 创建并激活虚拟环境
```
python -m venv .venv
.venv\Scripts\activate
```

2) 安装依赖（使用清华镜像）
```
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

3) 启动应用
```
python main.py
```

## 使用说明
1) 加载文件
- 点击“Add Folder”，选择包含 `.ncm` 文件的文件夹；程序会扫描并加载到表格中。
- 再次选择时，目录对话框会默认定位到上次使用的路径。

2) 选择输出目录
- 勾选“Use Source Folder”：输出与源文件同目录，按钮“Output Folder”会禁用。
- 取消勾选后点击“Output Folder”：选择统一输出目录；对话框会默认定位到上次使用的输出路径。

3) 开始转换
- 如需选择性转换：在表格中选中目标行（支持 Ctrl/Shift 多选），再点击“Convert All”。
- 未选择任何行时：点击“Convert All”会转换所有已加载文件。
- 转换过程中：
  - 每行显示进度与状态（Pending/Converting/Done/Failed）；
  - 左下角“Selected/Remaining”会随队列变化而更新。
- 队列完成：弹出提示框，并在状态栏显示“全部完成”。

4) 清空列表
- 点击“Clear”清空表格与内部队列；若正在转换会提示不可清空。

## 常见问题（FAQ）
- 为什么看不到浏览器预览？
  - 本项目为桌面 GUI 程序而非 Web 应用，需在桌面窗口中操作，不会生成浏览器可预览的 URL。
- 出现 `QThread: Destroyed while thread is still running`？
  - 已在代码中通过等待线程结束与规范信号连接进行修复；若仍出现，请确认未强制关闭程序或系统无异常。
- 依赖安装缓慢？
  - 使用项目提供的批处理脚本或手动指定国内镜像（清华源）进行安装。

## 目录结构（简要）
```
├── converter.py         # 转换逻辑（解密、进度回调等）
├── gui.py               # 图形界面（表格、按钮、线程管理、QSettings 持久化）
├── main.py              # 程序入口（创建并显示主窗口）
├── requirements.txt     # 运行时依赖列表
├── run_install_build.bat# 一键安装/运行/打包脚本（输出英文，使用国内源）
└── .venv/               # 虚拟环境（脚本自动创建）
```

## 构建与发布
- 使用 `run_install_build.bat build` 一键打包生成单文件 EXE。
- 打包后可直接分发 `dist\ncm2mp3-gui.exe`，用户无需安装 Python 与依赖。

## 备注
- 所有代码注释（文件级、类级、函数级）均使用英文；文档与界面文本优先为中文说明。
- 默认运行环境为 Windows；如需在其他平台运行，请自行测试兼容性。