Mu2026 Voice Bank Tools

Version 1.0.0. Build the external DX and AN factory voice banks used by the Mu2026 Hybrid 0.2.2 research preview. The converters are MIT-licensed source code; firmware, manuals and generated voice banks are not included.

Required inputs

Supply files you have appropriate rights to use. Hardware ownership alone is not represented here as permission to download or redistribute somebody else's dump. These are references to the resources discussed in issue 4, not firmware hosted by this project.

The converter swaps the AN dump's adjacent bytes internally. Do not pre-swap it. Both firmware and manual are checked by SHA-256 before parsing; other revisions, altered PDFs, truncated dumps and arbitrary user voice files are rejected. No download is performed by either converter.

Supported SHA-256 values

Windows quick start

1. Extract the tools ZIP into a writable folder. Install Python 3.10 or newer from python.org if needed. The converters do not install Python or create registry settings.
2. Run Build Voice Banks.cmd and choose 4 once to set up the pinned PDF libraries. This explicitly downloads packages from PyPI into user\venv, without modifying system Python.
3. Create an input subfolder beside the launcher. Put the appropriate firmware and manual there with the filenames in the table.
4. Run the launcher again and choose 1 for AN, 2 for DX, or 3 for both. It reads inputs without modifying them and creates the bank files beside the launcher.
5. Close the audio host, place the generated bank files beside mu2026-hybrid.dll in the 0.2.2 preview runtime, then reopen the host. The converters do not install or replace the plugin.

The launcher uses numbered console choices and ordinary keyboard input. Conversion progress and errors are recorded in user\session.log and one log per bank, overwritten on the next run. The local environment and logs stay beneath user. If converting both, each bank is independently validated: a successful first bank remains if the second fails. No existing bank is replaced unless -Force is explicitly requested.

Without input, the launcher exits on an unattended or redirected run instead of waiting for a menu answer. Example: Build Voice Banks.cmd -Mode Both -NonInteractive. Setup can be run explicitly with -Mode Setup -NonInteractive.

Linux and Wine quick start

1. Extract the same tools ZIP into a writable folder. Install your distribution's Python 3.10+ and virtual-environment support if needed; on Debian/Ubuntu the latter is commonly called python3-venv.
2. Open a terminal in that folder and run sh ./Build-VoiceBanks.sh --mode setup. This explicitly downloads the pinned libraries into user/venv; no Wine, PowerShell, administrator privileges or system pip installation is needed.
3. Put the required inputs in the input folder with exactly the filenames shown above. Linux filenames are case-sensitive.
4. Run sh ./Build-VoiceBanks.sh --mode both, or use --mode an / --mode dx. Running without a mode in an interactive terminal offers the same numbered menu as Windows. Redirected or unattended runs require a mode and never wait for keyboard input.
5. Close the Wine VST host. Place the generated plg-an-voices.bin and/or plg-dx-voices.bin in the actual Linux folder containing the 0.2.2 preview's mu2026-hybrid.dll, then reopen the host. This may be inside your Wine prefix or a folder mapped through Wine's Z: drive; it is not necessarily the updater's folder.

The banks contain platform-neutral bytes: Windows and Linux emit identical files. Conversion is native Python; only running the Windows synth needs Wine. --force explicitly permits replacement with one .previous backup. Logs and the local environment live under user; both-bank runs preserve a successful first bank if the second fails.

Command-line conversion

Use Python 3.10 or newer and the pinned requirements.txt. A local virtual environment is recommended. On Windows the launcher handles setup; on Linux use:

python3 -m venv user/venv
user/venv/bin/python -m pip install -r requirements.txt
user/venv/bin/python recover_dx.py --rom input/PLG150-DX.BIN --manual input/PLG150DXE.pdf --output plg-dx-voices.bin
user/venv/bin/python recover_an.py --rom input/IC3_XZ970A0_MBM29F800BA.bin --manual input/PLG150AN.pdf --output plg-an-voices.bin

Windows CLI uses user\venv\Scripts\python.exe instead. Paths with spaces must be quoted. Both scripts provide --help, --version, --rom, --manual, --output, --force and optional --log. Relative CLI paths use the current working directory; launcher paths use its own folder.

Identical existing output is left alone. Different output is refused by default. With --force, the prior bank is retained as .bin.previous before atomic replacement; the next forced replacement refreshes that one backup. A failed replacement preserves the prior bank. Input/output collisions and symlink output files are rejected. A .bin.lock prevents concurrent converters; after a power loss, remove a stale lock only when no converter is running.

Exit code 0 means success or already-current output. Exit code 1 means conversion failed; argument errors return 2. Wrong input hashes or unexpected recovery results leave existing output unchanged.

Bank container formats

ANP1 and DXP1 are this project's containers, not raw firmware formats. Integers below are unsigned little-endian, with no structure padding; program numbers and preset indexes are zero-based. The loaders in Source/AnEngine.cpp and Source/DxEngine.cpp are the executable format reference.

ANP1

Header: ASCII ANP1, 32-bit preset count, 32-bit selection count. Each preset contains 104 common bytes, 122 scene bytes, 70 sequencer bytes, a 32-bit Free EG byte count, and either zero or 768 Free EG bytes. Each selection contains one byte each for bank MSB, bank LSB and program, followed by a 16-bit preset index. This converter emits 256 presets and 848 selections, including aliases and user-slot defaults.

DXP1

Header: ASCII DXP1 and a 32-bit selection count. Each selection contains one byte each for bank MSB, bank LSB, program and layer count (1 to 4). Each layer contains a level byte, note-shift-plus-64 byte, detune-plus-64 byte, zero reserved byte and 155 unpacked DX7 VCED bytes. This converter emits 1,602 selections, including aliases and layered voices.

Coverage and limitations

Four AN aliases and 97 DX selections remain unrecovered; the tools do not invent missing data. Counts are selections, not unique sounds. The generated banks reproduce the existing verified preview assets byte-for-byte, not new sounds or new chip emulation. DX/AN sound-fidelity limitations in the main plugin guide still apply.

This release supports only the exact PLG150 firmware/manual pairs above. It does not import arbitrary AN1x, AN200, DX7 SysEx or user voices, does not dump physical hardware, and does not load these images as executable firmware. AN1x/AN200 ownership or voice files alone cannot generate the factory containers with these tools. Stable Mu2026 0.1.3 does not enable DX/AN merely by adding banks; use the opt-in 0.2.2 preview.

End-to-end recovery, launcher conversion and safety tests were checked on Windows and native Linux. Actual NVDA reading of the numbered menu and a native macOS run remain unverified. No paid services or online accounts are needed for conversion.

Credits and privacy

Firmware dump and research credit: Zhiyuan Wan (rgwan). Voice parameter formats and bank assignments: Yamaha's official PLG150 manuals. Converter implementation: Andre Louis, MIT licence. Yamaha firmware, manuals and generated parameters are not licensed by the converter project. The tools contain no firmware bytes, preset banks, private paths, credentials or telemetry.

Please report errors and version information in issue 5, without attaching firmware, manuals or generated bank data. Review logs for personal paths before sharing them. For updates, use the tools release; the synth updater does not install this standalone tooling release.

Tests

python test_bank_tools.py -v

The public tests use synthetic data only. The real-input hash checks and the converter's pinned output hashes provide reproducibility checks when you supply the matching inputs.