BUILD OR UPDATE

Run python apply.py in a terminal (Windows: py -3.13 apply.py).
Choose Build or update, then select your media and available outputs.
Settings are remembered; intact outputs can be reused safely.
Check requirements is optional. Change settings saves without building.
Enter q at any prompt to quit. Run apply.py --help for the existing
command-line options and specialized workflows described below.

CPS+ — arranged CD-era soundtracks for CPS1/CPS2 arcade games on MiSTer
=======================================================================

Version:     1.8
Hardware:    MiSTer FPGA — CPS-1.0, CPS-1.5 and CPS-2 cores
Project by:  Steve Gordon (https://x.com/strygo)
Website:     https://arcadepatches.com/cps-plus/

CPS+ adds the arranged (CD-quality) soundtracks Capcom recorded for its
console releases to the original arcade games, running on real FPGA
recreations of the arcade hardware.  The game's own sound engine stays
live — the core passively watches the sound commands the game issues and
streams the matching arranged track, while sound effects keep playing
through the original QSound/OKI hardware path.  No game code is modified.

  core source:   https://github.com/strygo/jtcores/tree/cpsplus   (GPL-3.0)

WHAT'S IN THIS KIT — AND WHAT ISN'T
-----------------------------------
This kit contains no game ROMs or directly playable soundtrack audio. The
Final Fight EX CPS2 English scenes are keyed to the matching Japanese disc;
they reconstruct only from your own corresponding scene data.

  apply.py           the entry point: list, check or build selected packs
  builder/           the pack generator (Python), the per-game trigger maps,
                     the three CPS+ cores, the MRA definitions, the X68000
                     render tools, the PlayStation sound-test recorder and
                     the Switch music reader (builder/tools/, see X68000.md,
                     PSX.md and SWITCH.md)
  out/mister/        built by the generator, laid out like your SD card.
                     This is the only folder you copy across.

You supply, as with any MiSTer arcade setup:
  * the arcade ROM zips (MAME naming) in games/mame/ or games/hbmame/
  * disc rips of the Capcom releases that carry each arranged soundtrack
    (see builder/discs.toml for the exact list per pack)
  * for the three X68000 MIDI packs: the games' X68000 disk images and
    your SC-55 ROM set -- the soundtrack is rendered on your machine
    (builder/X68000.md explains what that involves)
  * for the Super Street Fighter II X68000 FM pack: the same disk images,
    MAME, and MAME's x68000 BIOS set (also in builder/X68000.md)
  * for the Double Impact and HD Remix packs: the albums themselves, both
    free official downloads -- Capcom's Final Fight: Double Impact remixed
    soundtrack (http://www.finalfightgame.com/remix) and OC ReMix's SSF2T
    HD Remix soundtrack (https://ocremix.org/album/12); discs.toml has the
    direct links
  * for the Strider (PSX Soundtrack) pack: your Strider (USA) PlayStation
    disc, MAME, and MAME's PlayStation ROM sets -- the kit records the
    game's own sound test (builder/PSX.md explains what that involves)
  * for the USF2 Remix pack: Ultra Street Fighter II: The Final
    Challengers for Nintendo Switch (a supported USA base .nsp or .xci) and your
    own prod.keys (builder/SWITCH.md explains what that involves)

QUICK START
-----------
  1. Run python3 apply.py --list to see the available soundtracks and inputs.
     Choose one and supply your media, for example:
       python3 apply.py --only mtwins --disc mtwins_pce_disc="/discs/chiki.7z"
     Repeat --only and --disc to select more. Windows paths work too.
     To save paths for later, edit builder/discs.toml; then run:
       python3 apply.py
     Python 3.11+ is needed to start; the bundled bootstrap prepares the
     numerical dependencies. Verified media helpers are fetched on demand
     or supplied offline (builder/TOOLS.md). Git, CMake and a compiler are
     not needed for the supported prebuilt helpers. X68000 renders can
     take up to an hour (builder/X68000.md). Strider PSX and SSF2 X68000 FM
     also need your MAME installation and matching BIOS files.
     Each built pack is verified byte-for-byte against the published hash,
     so your build is exactly the authored pack.
  2. Copy the contents of out/mister/ onto your MiSTer SD card
     (/media/fat/), merging with what's already there.  It holds the
     cores, your packs, and the MRAs those packs can load.  See
     INSTALL.md for details.

Using the shared Arcade Patches builder: add this kit, scan folders holding
your owned media or existing CPS+ packs, and select the soundtrack and region.
An accepted existing pack can be reused directly, including from its ZIP.
Finished group caches are checked against the accepted pack hashes and survive
documentation, launcher and core-metadata updates. The four DOS soundtracks
also share verified extraction of their game archive. Cache data stays local;
missing entries are rebuilt from the declared inputs.

IF A PACK DOES NOT VERIFY
-------------------------
The album and CD-audio packs (Final Fight OST, UN Squadron SNES, Mega
Twins, Forgotten Worlds, Muscle Bomber) check your rip before encoding:
one row per track with its length, CRC32 and MATCH / ALIGNED / DIFFERENT /
MISSING.  ALIGNED means the exact audio was found in your rip but not
where the track list put it (another read offset, other gap handling,
other numbering) and was re-cut from where it is -- that still builds the
published pack.  DIFFERENT and MISSING rows say what the difference points
at; a pack with such a track is not built.  To see the table without
building anything:
       python3 apply.py --check-inputs
If a pack's inputs match but its hash still differs, the message names the
first stage that did (loop/fade processing or ffmpeg's ADX encoder), and
builder/work/packs/<pack>.audit.json has the per-track record -- include it
if you report the problem.

COMPANION GAME MRAS
------------------------------------------------------------------------
Most MRAs here target the stock arcade ROM sets. Companion launchers pair
CPS+ audio with these reconstructed games:

  * Alpha / Zero EX and Alpha / Zero 2 EX load their companion games:
      https://arcadepatches.com/sfa-ex/
      https://arcadepatches.com/sfa2-ex/
    EX arranged music pauses and resumes at the same musical position.
    Install the supplied CPS2 core together with these packs.

  * Final Fight EX CPS2 has separate USA, Japan and English-restoration packs,
    with voiced scenes and the Time Attack theme:
      https://arcadepatches.com/final-fight-ex-cps2/
    These use their own CPS2 word commands; the CPS1 EX packs serve the
    original CPS1 backport. Build the arcade set with its companion game kit.

  * "Street Fighter Alpha 2 Gold (Arrange)" + the other Gold MRAs load
    the SFA2 Gold 8 MiB sets — reconstructed from your own game data by
    the SFA2 Gold kit:  https://arcadepatches.com/sfa2-gold/

  * The "Super Street Fighter II Turbo: Grand Master Challenge" MRAs, one
    per Super Street Fighter II soundtrack, load the English restoration
    of Japan's Super Turbo (ssf2tgmc.zip in games/hbmame/), built by its
    kit:
    https://arcadepatches.com/ssf2t-gmc/ -- that zip holds
    only the seven changed files, so keep your stock ssf2xj, ssf2t and
    qsound zips in games/mame/; the MRA reads the rest of the set there.

  * The "Super Street Fighter II EX" MRAs, one per Super Street Fighter II
    soundtrack plus their Japan versions, load SSF2 EX: The Ultimate
    Championship (ssf2tuc.zip or ssf2xuc.zip in games/hbmame/), built by
    its kit:
    https://arcadepatches.com/ssf2-ex/ -- like Grand Master
    Challenge, keep the stock ssf2xj, ssf2t and qsound zips in games/mame/.
    The bonus stages keep the game's own music.

  * "Final Fight EX (Arrange)" loads Final Fight EX, the Sega CD
    cutscene backport set (ffightus01 in games/hbmame/), built by its kit:
    https://arcadepatches.com/final-fight-ex/

  * "Final Fight 30th Anniversary CPS2 Edition (Arrange)" loads the CPS2
    conversion of Final Fight by grego2d and rotwang (ffightae_cps2.zip),
    distributed through the Arcade Offset project for MiSTer:
    https://github.com/Toryalai1/Arcade_Offset  -- its pack is built from
    the same US Final Fight CD as the CPS-1 arrange pack.

Without those sets installed, these specific MRAs will not load; every
other MRA works with stock MAME-naming ROM sets.

MAKING YOUR OWN PACKS
---------------------
Everything you need is in builder/: PACK_FORMAT.md specifies the trigger
contract and the pack binary layout, build_pack.py --help lists
the build modes, and build_pack.py is the tool (init <game> →
pack.toml → build → embed into an MRA).  Community packs for any QSound
CPS2 title are a first-class goal of the format.

LICENSES
--------
Cores: GPL-3.0 (see builder/cores/SOURCE_AND_LICENSE.txt).  MRAs, trigger
manifests and the builder are configuration/metadata and code from the
CPS+ project.  The X68000 render path fetches and builds two open-source
projects at pinned revisions (ValleyBell's X68000 decoders and the
Nuked-SC55 emulator, each under its own licence in its checkout), and the
Strider pack runs your own installation of MAME; none of their code is
bundled here.  The arranged recordings remain (c) Capcom —
which is why soundtrack packs are built from your own discs, disks and ROMs.
The English scene data in this kit is keyed to the corresponding Japanese
disc scenes and checked block by block during reconstruction.

MEDIA TOOLS
  See builder/TOOLS.md for verified downloads, offline tools and cache options.
