BBP2MIDI V14
============

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.

V14 status
----------
V14 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

Important note on supplied MIDIs
--------------------------------
MIDIs supplied by the user alongside BBPs are converter-generated outputs, not
independent reference recordings. They are useful as historical output snapshots
and regression fixtures when explicitly identified as such, but they do not by
themselves prove musical correctness. Independent listening against the original
game/hardware is the authoritative validation for musical fidelity.

V14 verification on the existing corpus:
  41/41 BBPs converted successfully
  40/40 historical converter-output MIDIs can be reproduced byte-for-byte
  1 BBP has no supplied historical MIDI: the Iori file listed below

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

The V11/V12/V14 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_V14/
  bbp2midi_v14.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_v14.py song.bbp

Single-file conversion
----------------------
Drag a .bbp file onto convert_one.bat, or use:
  py -3 bbp2midi_v14.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 independent 4-bit streams which are mapped through Instruments.xml.
* Each drum nibble stream independently honors the leading 0xF three-note marker,
  giving the same 3-frame/4-frame timing behavior as the original Degausser logic.
* Drum hits are emitted as MIDI note-on trigger events only (no same-tick note-off),
  matching the original AddDrum behavior and avoiding silent zero-length triggers.
* 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
------------------
V14 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.


V14 output robustness
---------------------
V14 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.
