Sonic Colors Recomp — music_asset on Windows
============================================

The Music Library uses `tools/music_asset.exe` (or `music_asset.cmd`) to:
  - build/update catalog.json
  - decode original AAX previews (vgmstream)
  - export original WAV
  - prepare patched CPK replacements (cricodecs)

Required (same roles as Linux) — preferred path on Windows:
  Open the launcher Music tab → **Install Music tools**
  Downloads pinned Python embed + cricodecs + vgmstream + LGPL FFmpeg into
    %LOCALAPPDATA%\SonicColorsRecomp\dependencies\
  (see data\music_deps_manifest.json and licenses\MUSIC_DEPS_RUNTIME.txt)

Manual / developer fallback:
  1. Python 3.11+ on PATH (`python` / `py -3`)
  2. cricodecs (via tools\music_deps_setup.cmd → .venv-music)
  3. vgmstream-cli.exe — %APPDATA%\SonicColorsRecomp\tools\bin or tools\bin\
  4. ffmpeg.exe — same drop-in folders (prefer an LGPL build)

Installed app (Setup.exe — preferred):
  Drop-ins → %APPDATA%\SonicColorsRecomp\tools\bin
  Venv     → %APPDATA%\SonicColorsRecomp\.venv-music
  (music_deps_setup.cmd detects installed.txt and uses these paths)

Portable ZIP:
  Drop-ins → tools\bin\
  Venv     → .venv-music next to the install root

Quick setup:
  1. Music tab → Install Music tools (recommended)
  2. Or tools\music_deps_setup.cmd + manual ffmpeg/vgmstream drop-ins
  3. Music tab → Check tools

Works immediately (no host tools): browse catalog, replacement WAV preview,
play with an already-prepared music_mods cache.

Needs setup: original preview/export (cricodecs+vgmstream); Prepare (cricodecs+ffmpeg).

Packages ship catalog.json, music_asset*, music_deps_manifest.json, music_deps_setup,
tools/bin/README, libwinpthread beside music_asset.exe. They do not ship
Python/cricodecs/ffmpeg/vgmstream binaries (Windows downloads them on demand).
See docs\WINDOWS_INSTALLER.md.

`manifest.toml` and `tracks/` are created next to the catalog when you assign
replacements in the Music tab (not shipped).

Replacement CPK cache (`music_mods/current.json`) is created by Prepare. A
“not prepared yet” status is normal until then — original previews/export still
use the game CPK directly (they need vgmstream-cli.exe in tools\bin or PATH).

If preview says vgmstream was not found, open Music → Check tools and read `searched`
paths in the doctor JSON, or copy vgmstream-cli.exe into the drop-in folder above.

Override the launcher path with SCR_MUSIC_ASSET.
Override the Python interpreter with SCR_MUSIC_PYTHON (full path to python.exe).

Exit codes from music_asset.exe:
  127 — Python not found (install Python + music_deps_setup, or set SCR_MUSIC_PYTHON)
  126 — Python path resolved but CreateProcessW failed (see stderr Win32 code)
  other non-zero — Python/cli failure

If you previously saw "CreateProcess failed (87)" then "PREPARE FAILED (rc=127)",
that was a Unicode environment-block bug in the launcher (fixed: CREATE_UNICODE_ENVIRONMENT).
