# musicTransfer

**Repository Path**: ywwynm/musicTransfer

## Basic Information

- **Project Name**: musicTransfer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# musicTransfer

本项目是本地音乐转换工具，把一首 **Source Song** 送入可插拔 Backend，生成 MIDI、音频、乐谱、视频等音乐派生结果。当前稳定工作流是 **Piano Cover**：输出 **Cover MIDI** 和可选的 **Render Audio**。

## Runtime

项目按 WSL2 + Conda 使用：

```bash
cd /mnt/e/projects/musicTransfer
conda env create -f environment.yml
conda activate musicTransfer

source scripts/music-transfer-env.sh
```

如果 `musicTransfer` 环境已经创建过，但还没有安装项目依赖：

```bash
cd /mnt/e/projects/musicTransfer
conda activate musicTransfer
conda env update -n musicTransfer -f environment.yml

source scripts/music-transfer-env.sh
```

源码留在 Windows 的 `E:\projects\musicTransfer`，但依赖安装、模型推理、MIDI/音频生成都从 WSL2 shell 执行。不要在代码里硬编码 Windows 路径。

基础开发环境只安装轻量依赖。需要具体 Backend 时再安装对应 extra：

```bash
pip install -e ".[dev]"
```

PyTorch/CUDA 建议用 Conda 按本机驱动和 GPU 单独安装，避免被 pip extra 意外替换。

Pop2Piano 依赖包含 C/C++ wheel，环境必须是 CPython 3.10/3.11，不能是 GraalPy/PyPy：

```bash
python - <<'PY'
import platform, sys
print(platform.python_implementation(), sys.version)
PY
```

如果输出不是 `CPython`，先修环境：

```bash
conda install -n musicTransfer -c conda-forge cpython python=3.10
conda activate musicTransfer
```

Essentia 建议先从官方 PyPI 安装已有 CPython wheel，避免镜像源回退到 source distribution 后本地编译：

```bash
python -m pip install --index-url https://pypi.org/simple --only-binary=:all: "essentia==2.1b6.dev1034"
python -m pip install --force-reinstall "numpy>=1.23,<1.24"
pip install -e ".[pop2piano,render]"
```

如果运行时报 `A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x`，
这不是 CUDA 问题，而是 Essentia wheel 与 NumPy 2 不兼容。执行：

```bash
python -m pip install --force-reinstall "numpy>=1.23,<1.24"
python -m pip install --force-reinstall --index-url https://pypi.tuna.tsinghua.edu.cn/simple --only-binary=:all: "essentia==2.1b6.dev1034"
```

如果运行时报 `No module named 'resampy'`：

```bash
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "resampy>=0.4"
```

如果要从 **Cover MIDI** 生成 **Engraved Score**，先安装记谱依赖：

```bash
pip install -e ".[score]"
```

`.musicxml` 输出只需要 `music21`；`.pdf` 输出还需要系统里能调用 MuseScore。可通过 `MUSESCORE_COMMAND` 指定可执行文件：

```bash
export MUSESCORE_COMMAND=musescore
music-transfer doctor --score --hints
```

## CLI

检查当前环境：

```bash
music-transfer doctor
music-transfer doctor --hints
music-transfer doctor --json
music-transfer doctor --backend pop2piano
music-transfer doctor --score --hints
music-transfer doctor --ncm --hints
music-transfer cache
music-transfer inspect source.mp3
```

`.ncm` Source Song 会先通过本地外部解码器转成 MP3/FLAC，再进入同一条 Piano Cover 流程。项目不内置 NCM 解码器；如果 `ncmdump` 不在 `PATH`，设置命令模板：

```bash
export NCM_DECODE_COMMAND='ncmdump {source_song_q}'
music-transfer source.ncm --backend pop2piano --output-dir outputs/source --overwrite
```

生成 **Cover MIDI**：

```bash
music-transfer source.mp3 --backend pop2piano --dry-run
music-transfer source.mp3 --backend pop2piano --composer composer7 --output-dir outputs/source --overwrite
```

如果要同时生成 **Render Audio**，项目默认使用 `soundFonts/1775388268276_GeneralUser-GS.sf2`：

```bash
music-transfer source.mp3 \
  --backend pop2piano \
  --output-dir outputs/source \
  --audio-output outputs/source/render.mp3
```

音频质量策略：如果输出 `.mp3`，项目使用 LAME 320 kbps；如果需要完全无损的 **Render Audio**，把输出后缀改成 `.wav`。钢琴卷 MP4 合成音频时，MP3/M4A/AAC 会直接 stream copy；WAV/FLAC 会转成 MP4 可封装的 ALAC lossless。

如果还要同时生成钢琴谱：

```bash
music-transfer source.mp3 \
  --backend pop2piano \
  --output-dir outputs/source \
  --audio-output outputs/source/render.mp3 \
  --score-output outputs/source/score.pdf \
  --score-title "source" \
  --score-midi-output outputs/source/score.mid \
  --score-audio-output outputs/source/score.mp3 \
  --score-time-signature 4/4 \
  --score-quantize 1/16 \
  --score-min-note 1/32 \
  --score-max-notes-per-hand 4 \
  --score-split-pitch C4 \
  --overwrite
```

已有 **Cover MIDI** 时，可以单独转成 MP3：

```bash
music-transfer render outputs/source/cover.mid \
  --output outputs/source/render.mp3
```

已有 **Cover MIDI** 时，也可以生成钢琴卷演示视频：

```bash
pip install -e ".[visualize]" -i https://pypi.tuna.tsinghua.edu.cn/simple
music-transfer doctor --visualize --hints

music-transfer visualize outputs/source/cover.mid \
  --audio outputs/source/render.mp3 \
  --output outputs/source/piano-roll.mp4 \
  --overwrite
```

视频默认会高亮并轻微下沉正在按下的琴键；可用 `--no-key-animation` 关闭。

已有 **Cover MIDI** 时，也可以生成可编辑的 MusicXML 和可打印的 PDF 钢琴谱：

```bash
music-transfer score outputs/source/cover.mid \
  --output outputs/source/score.pdf \
  --title "source" \
  --overwrite
```

默认会把音符按 `C4` 分界拆成右手高音谱表和左手低音谱表。谱子如果仍然不顺手，可以调整分界音高：

```bash
music-transfer score outputs/source/cover.mid \
  --output outputs/source/score.pdf \
  --title "source" \
  --split-pitch D4 \
  --overwrite
```

默认谱面清理会先生成一个更适合记谱的 `notation.mid`：强制 `4/4`、按 `1/16` 网格量化、去掉短于 `1/32` 的碎音、禁用三连音类复杂记谱、按 `C4` 拆右手/左手，并限制每只手同一时间最多 4 个音。可以生成一版更简单的谱：

```bash
music-transfer score outputs/source/cover.mid \
  --output outputs/source/score-simple.pdf \
  --title "source" \
  --time-signature 4/4 \
  --quantize 1/8 \
  --min-note 1/16 \
  --max-notes-per-hand 3 \
  --split-pitch C4 \
  --overwrite
```

也可以从清理后的谱子再导出 MIDI/MP3，用来和原始 `render.mp3` 对比：

```bash
music-transfer score outputs/source/cover.mid \
  --output outputs/source/score.pdf \
  --score-midi-output outputs/source/score.mid \
  --score-audio-output outputs/source/score.mp3 \
  --title "source" \
  --time-signature 4/4 \
  --quantize 1/16 \
  --min-note 1/32 \
  --max-notes-per-hand 4 \
  --split-pitch C4 \
  --overwrite
```

如果暂时没有 MuseScore，可以先生成 MusicXML，再用 MuseScore 手动打开修订：

```bash
music-transfer score outputs/source/cover.mid \
  --output outputs/source/score.musicxml \
  --title "source" \
  --overwrite
```

比较 Pop2Piano 的多个 composer 风格：

```bash
music-transfer compare source.mp3 \
  --composers composer1,composer7,composer13 \
  --output-dir outputs/source-compare \
  --audio-format mp3 \
  --overwrite
```

不传 `--composers` 时会生成 `composer1..composer21` 全部变体；每个 composer 会写入自己的子目录。

Pop2Piano 的 `composer1..composer21` 是 21 个匿名的作曲/编配风格 token，不对应真实作曲家，也不是质量档位。不同 composer 会让模型生成不同的钢琴编配倾向；实际使用时建议通过 `compare` 批量生成几个候选，听结果后选择。

当前代码先提供统一接口和 Pop2Piano 适配器。PiCoGen2 通过命令适配器预留集成点，等外部 PiCoGen2 推理命令确认后接入。

AMT-APC 默认使用项目内的 `amt-apc/infer` 和 `amt-apc/models/params/apc.pth`，会自动先用高质量 ffmpeg 重采样生成模型需要的 16 kHz mono WAV，不需要手写 `AMT_APC_COMMAND`。如果外部仓库或模型放在其它位置，可以设置 `AMT_APC_ROOT` 或 `AMT_APC_MODEL_PATH`；`AMT_APC_COMMAND` 仍保留为完整覆盖入口。

AMT-APC 的 `AMT_APC_STYLE` 可设为 `level1`、`level2` 或 `level3`。它控制上游模型的 style vector：`level1` 更稀疏保守，`level2` 是上游默认的中等风格，`level3` 更饱满活跃、音符更多。它同样不是音质档位；如果输出听起来过密或过乱，可以改用 `level2` 或 `level1`。

```bash
python -m pip install torchaudio torchcodec soundfile tqdm pretty-midi
music-transfer source.mp3 --backend amt-apc --dry-run
```

PiCoGen2 默认通过 `scripts/picogen2-command.sh` 接外部仓库。先 clone：

```bash
git clone -b v2 https://github.com/tanchihpin0517/PiCoGen.git picogen2
```

Docker 方式：

```bash
export PICOGEN2_DOCKER_IMAGE=tanchihpin0517/picogen2:latest-full
docker info
docker pull tanchihpin0517/picogen2:latest-full
music-transfer source.mp3 --backend picogen2 --output-dir outputs/source-picogen2 --overwrite
```

如果 `docker info` 报 `/var/run/docker.sock` permission denied：

```bash
sudo usermod -aG docker $USER
```

然后重启 WSL shell；必要时在 PowerShell 执行 `wsl --shutdown` 后重新打开 WSL。

如果 `docker pull` 报 Docker Hub `EOF` 或 timeout，说明 Docker 可用但访问 Docker Hub 不稳定。可以重试同一条 `docker pull`，配置 Docker registry mirror/proxy，或者改用下面的本地 Conda 方式。

本地 Conda 方式：

```bash
cd picogen2
conda create -n picogen2 python=3.10 -y
conda install -n picogen2 mpi4py Cython -y
conda run -n picogen2 --no-capture-output pip install .
cd ..
export PICOGEN2_CONDA_ENV=picogen2
music-transfer source.mp3 --backend picogen2 --output-dir outputs/source-picogen2 --overwrite
```