===============================================================================
              MIDI playing bank for Yamaha OPL2 (YMF262) chip
                 file format specification (WOPL and OPLI)
===============================================================================
                         Created in July, 23, 2017
===============================================================================
Author:             Vitaliy Novichkov "Wohlstand"
Contacts emails:    admin@wohlnet.ru, nvd339@yandex.ru
===============================================================================

===============================================================================
Contents:
    0. Changelog
    1. Single-instrument entry
    2. Instrument file (OPLI)
    3. MIDI playing bank file (WOPL)
===============================================================================

===============================================================================
                        0. Changelog
===============================================================================

Version | What's new
-------------------------------------------------------------------------------
    1   | First version (July, 23, 2017)
-------------------------------------------------------------------------------
    2   | Added banks meta-data arrays into bank format (August, 1, 2017)
-------------------------------------------------------------------------------
    3   | Added two delay coefficients are needed for ADLMIDI's channel busy
        | (November 19, 2017)
        | Change: Added 'blank instrument' flag into existing variable
        | (March 26, 2018)
        | Change: Added rhythm-mode drum type three-bit number
        | (May 29, 2018)
        | Change: Added two new volume scaling models: DMX and Apogee with
        | fixed AM voices
        | (August 31, 2020)
        | Change: Added three new volume scaling models: Audio Interfaces
        | Library, Win9x Generic FM, and HMI Sound Operating System
        | (September 6, 2020)
-------------------------------------------------------------------------------

===============================================================================
                        1. Single-instrument entry
===============================================================================

    Each instrument file contains a set of data for single
channel of YMF262 chip to setup the timbre

Lenght of each instrument entry is 62 bytes (up to version 2 and in OPLI files)

Since version 3, in WOPL banks each instrument has extra 4 bytes for
a two extra fields

Bytes-Lenght  | Description
-------------------------------------------
    32        | Name of instrument null-terminated string
    2         | Big-Endian 16-bit signed integer, MIDI key offset value
              | (master instrument, or first voice in pseudo 4-operators mode)
    2         | Big-Endian 16-bit signed integer, MIDI key offset value
              | (second voice in pseudo 4-operators mode)
    1         | 8-bit signed integer, MIDI Velocity offset
    1         | 8-bit signed integer, Second voice detune
              | in pseudo-4-operators mode
    1         | 8-bit unsigned integer, Percussion instrument key number
    1         | 8-bit unsigned integer, Bitwise flags:
              |     [0EEEDCBA]
              |     A) 0x00 - 2-operator mode
              |     B) 0x01 - 4-operator mode
              |     C) 0x02 - pseudo-4-operator (two 2-operator voices) mode
              |     D) 0x04 - is 'blank' instrument (instrument which has no sound)
              |     E) 0x38 - Reserved for rhythm-mode percussion type number (three bits number)
              |        -> 0x08 - is Bass drum
              |        -> 0x10 - is Snare
              |        -> 0x18 - is Tom-tom
              |        -> 0x20 - is Cymbal
              |        -> 0x28 - is Hi-hat
              |     0) Reserved / Unused
    1         | 8-bit unsigned integer, Feedback / Connection
              | for 1'st and 2'nd operators or first voice
    1         | 8-bit unsigned integer, Feedback / Connection
              | for 3'st and 4'nd operators or second voice
--- Operators 1/2/3/4 (repeats 4 times) ---
    1         | AM/Vib/Env/Ksr/FMult characteristics
    1         | Key Scale Level / Total level register data
    1         | Attack / Decay
    1         | Systain and Release register data
    1         | Wave form
-------------------------------------------

--VERSION >= 3---WOPL-Bank-only, OPLI must don't have those fields---
    2         | Big-Endian 16-bit unsigned integer, Millisecond delay of sound
              | while key is on
    2         | Big-Endian 16-bit unsigned integer, Millisecond delay of sound
              | after key off
-------------------------------------------



===============================================================================
                         2. Instrument file (OPLI)
===============================================================================

    Each instrument file contains a set of data for single
channel of YMF262 chip to setup the timbre on it.

Total data lenght: 76 bytes

Bytes-Lenght |  Description
---------------Header--------------------
    11       |  Magic number "WOPL3-INST\0". Where '\0' is a zero byte which
             |  termiates the string
    2        |  Version. Little endian Unsigned 16-bit integer.
             |  Latest version is 2 (no difference between 2 and 1)
    1        |  Is this instrument a percussion. 0 - melodic, or 1 - percussion
----------------Data---------------------
    62       |  [Single-instrument entry], look at top of this text file


===============================================================================
                      3. MIDI playing bank file (WOPL)
===============================================================================

    Bank format designed to store instrument bank for playing MIDI
in multiple standards like GM, GS and XG. Format allows to save
multiple sets with 128-instruments which is needed to store
GS and XG instrument sets which are have more than standard 128
instruments with a single bank.

Total data length is sum of: 19 + (62*128*MBanks) + (62*128*PBanks) bytes

Bytes-Lenght      |      Description
---------------Header-----------------------
--Header--
    11            | Magic number "WOPL3-BANK\0". Where '\0' is a zero byte
                  |     which termiates the string
    2             |  Version. Little endian Unsigned 16-bit integer.
                  |  Latest version is 2
    2             | [MBanks] Unsigned 16-bit BE integer, count of melodic
                  |     MIDI banks (every bank contains 128 instruments)
    2             | [PBanks] Unsigned 16-bit BE integer, count of percussion
                  |     MIDI banks (every bank contains 128 instruments)
    1             | 8-bit unsigned integer, Global bank bitwise flags:
                  |     [000000BA]
                  |     A) Deep-Tremolo flag
                  |     B) Deep-Vibrato flag
                  |     0) Unused / Reserved
    1             | 8-bit unsigned integer, ADLMIDI's volume scaling model
                  |     enumeration, default is 0:
                  |     0 - Generic, linearized
                  |     1 - Native OPL3's logariphmic volume model
                  |     2 - DMX volume model
                  |     3 - Apogee Sound System's volume model
                  |     4 - Windows 9x SB16 driver volume model
                  |     5 - DMX volume model with fixed AM voices
                  |     6 - Apogee Sound System volume model with fixed AM voc.
                  |     7 - Audio Interfaces Library volume model
                  |     8 - Windows 9x Generic FM driver volume model
                  |     9 - HMI Sound Operating System volume model
--VERSION >= 2---Melodic bank meta-data-----
(repeat MBanks times)
    32            | Name of melodic bank null-terminated string
    1             | LSB index of bank (unsigned char)
    1             | MSB index of bank (unsigned char)
--VERSION >= 2---Percussion bank meta-data--
(repeat PBanks times)
    32            | Name of melodic bank null-terminated string
    1             | LSB index of bank (unsigned char)
    1             | MSB index of bank (unsigned char)

InsSize:
    --62 bytes in up to version 2
    --66 bytes since version 3 and later

-----------Melodic Instruments--------------
    InsSize * 128 * MBanks  | 128 [Single-instrument entries] per each bank,
                            |     look at top of this text file
---------Percussion Instruments-------------
    InsSize * 128 * PBanks  | 128 [Single-instrument entries] per each bank,
                            |     look at top of this text file
--------------------------------------------

