BBP2MIDI V5
===========

Files in this package
---------------------
bbp2midi_reliable_v5.py  Main converter
BBP2MIDI_V5.bat          Drag one .bbp file onto this BAT file
BBP2MIDI_V5_BATCH_ALL.bat Convert every .bbp in the package/current folder
Instruments.xml          Instrument/program and drum definitions
GuitarChords.tbl         624-byte guitar voicing table

Requirements
------------
Python 3 and mido.
Install mido once with:
    py -m pip install mido

Usage
-----
1. Keep all files above together.
2. Drag a .bbp file onto BBP2MIDI_V5.bat.
3. The .mid is written next to the .bbp.

The converter also accepts:
    py bbp2midi_reliable_v5.py song.bbp
    py bbp2midi_reliable_v5.py song.bbp song.mid
    py bbp2midi_reliable_v5.py --batch

Technical corrections in V5
----------------------------
- Piano chord IDs are resolved against pianoOrig using the stored 1-based ID.
- Guitar timer rows are sparse updates: FF/FF retains the previous slot.
- Guitar timer states are copied per time position; they do not alias the final state.
- Guitar stock chords use GuitarChords.tbl and root/shape mapping.
- Flat roots wrap pitch classes modulo 12 (the practical interpretation of the
  C# byte arithmetic for Python/MIDI).
- Instruments.xml is required so program and drum mappings are not silently lost.

Validation against test.bbp
----------------------------
The V5 converter was checked against the source BBP event reconstruction:
- Piano: 1,524 note-ons; exact absolute-time/pitch sequence match.
- Guitar: 1,416 note-ons; exact absolute-time/pitch sequence match.
- With Instruments.xml loaded, the resulting test MIDI contains 11 tracks.

This validates the event/pitch reconstruction for the supplied test file;
it does not constitute a claim that every possible BBP variant has been
fully reverse-engineered.
