BBP2MIDI V13
============

Purpose
-------
BBP2MIDI converts Daigasso! Band Brothers / Band Brothers P .BBP song data
into standard MIDI files while preserving the musical timing, channel layout,
instrument assignments, drum mapping, piano voicings, and guitar voicings
encoded in the BBP data.

V13 status
----------
V13 is the verified continuation of the V11/V12 converter.  The proven V11
musical-decoding core is retained unchanged so that the established regression
baseline is not lost.  V12 adds a cleaned release package, corrected BAT files,
and a standalone regression-test utility.

Verified corpus
----------------
BIG BATCH contains:
  41 BBP files
  40 corresponding reference MIDIs

V13 verification:
  41/41 BBPs converted successfully
  40/40 supplied reference MIDIs matched byte-for-byte
  1 BBP has no supplied reference MIDI: the Iori file listed below

The previously failing BBP was:
  Iori - kimi ga ireba (#U30d4#U30ab#U30c4#U30a5).bbp

The V11/V12/V13 guitar fix recognizes native/original-guitar raw-root sentinels:
  0xEB, 0xED, 0xEF

For those values, the pair index addresses guitarOrig[].  The 0xEB case is
required by the Iori file and is therefore retained as a first-class rule.

Files
-----
BBP2MIDI_V13/
  bbp2midi_v13.py       Main converter
  convert_one.bat       Drag one BBP onto this file
  batch_convert.bat     Convert every BBP in the current folder
  regression_test.py    Compare generated MIDIs with supplied references
  Instruments.xml        Instrument / MIDI / drum mappings
  GuitarChords.tbl       624-byte stock guitar voicing table
  PianoChords.tbl        Piano chord table retained for compatibility/reference
  README.txt             This document

Requirements
------------
Windows:
  Python 3.x
  mido

Install the Python dependency with:
  py -3 -m pip install mido

Linux/macOS:
  python3 -m pip install mido
  python3 bbp2midi_v13.py song.bbp

Single-file conversion
----------------------
Drag a .bbp file onto convert_one.bat, or use:
  py -3 bbp2midi_v13.py input.bbp output.mid

Batch conversion
----------------
Place the BBP files and the supporting XML/TBL files in the same folder and
run batch_convert.bat.  The resulting MIDI files are written beside the BBPs.

Regression testing
------------------
Place the 41 BBPs and 40 reference MIDIs in one folder.  Run:
  py -3 regression_test.py <folder>

The test converts each BBP into a separate regression_out directory and then
compares the result with the reference MIDI having the same filename stem.
The reference-less BBP is counted as a successful conversion but is not used
for byte comparison.

Technical notes
---------------
* BBP timing is expanded at 48 frames per line.
* The MIDI file uses 48 ticks per beat with a 4-tick frame scale.
* Standard channels decode directly from their note stream.
* Drum bytes carry two 4-bit streams which are mapped through Instruments.xml.
* Piano playback uses song-specific pianoOrig voicings.
* Guitar playback uses time-selected guitarTimer mappings.
* Native/original guitar entries resolve through guitarOrig[] and the six-string
  packed representation used by the BBP format.
* BDX-derived guitar pair encodings are handled in addition to native BBP/P
  encodings.

Development policy
------------------
V13 is intentionally conservative.  The current release does not introduce a
new speculative musical rule merely to create a version-number change.  The
next algorithmic revision should only be made when supported by additional
format evidence or an unseen validation corpus, and must retain the 41/41 and
40/40 regression gates.


V13 output robustness
---------------------
V13 retains the V12/V11 musical-decoding core and hardens MIDI output handling.
Conversion and file writing are now treated as separate operations. MIDI is
first written to a temporary file and then atomically moved into place. If the
requested destination is locked by another Windows process, the conversion is
NOT reported as a decode failure: the generated MIDI is preserved using a
unique filename such as "song (converted).mid". This addresses the common
case where a previously generated MIDI is open in a player or DAW.
