GENMIDI.OP2 OPL2 sound bank: Ruby parsing library

GENMIDI.OP2 is a sound bank file used by players based on DMX sound library to play MIDI files with General MIDI instruments using OPL2 sound chip (which was commonly installed on popular AdLib and Sound Blaster sound cards).

Major users of DMX sound library include:

  • Original Doom game engine (and games based on it: Heretic, Hexen, Strife, Chex Quest)
  • Raptor: Call of the Shadows

File extension

op2

KS implementation details

License: CC0-1.0

This page hosts a formal specification of GENMIDI.OP2 OPL2 sound bank using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Usage

Parse a local file and get structure in memory:

data = GenmidiOp2.from_file("path/to/local/file.op2")

Or parse structure from a string of bytes:

bytes = "\x00\x01\x02..."
data = GenmidiOp2.new(Kaitai::Struct::Stream.new(bytes))

After that, one can get various attributes from the structure by invoking getter methods like:

data.magic # => get magic

Ruby source code to parse GENMIDI.OP2 OPL2 sound bank

genmidi_op2.rb

# This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

require 'kaitai/struct/struct'

unless Gem::Version.new(Kaitai::Struct::VERSION) >= Gem::Version.new('0.7')
  raise "Incompatible Kaitai Struct Ruby API: 0.7 or later is required, but you have #{Kaitai::Struct::VERSION}"
end


##
# GENMIDI.OP2 is a sound bank file used by players based on DMX sound
# library to play MIDI files with General MIDI instruments using OPL2
# sound chip (which was commonly installed on popular AdLib and Sound
# Blaster sound cards).
# 
# Major users of DMX sound library include:
# 
# * Original Doom game engine (and games based on it: Heretic, Hexen, Strife, Chex Quest)
# * Raptor: Call of the Shadows 
# @see http://www.fit.vutbr.cz/~arnost/muslib/op2_form.zip http://doom.wikia.com/wiki/GENMIDI
class GenmidiOp2 < Kaitai::Struct::Struct
  def initialize(_io, _parent = nil, _root = self)
    super(_io, _parent, _root)
    _read
  end

  def _read
    @magic = @_io.ensure_fixed_contents([35, 79, 80, 76, 95, 73, 73, 35].pack('C*'))
    @instruments = Array.new(175)
    (175).times { |i|
      @instruments[i] = InstrumentEntry.new(@_io, self, @_root)
    }
    @instrument_names = Array.new(175)
    (175).times { |i|
      @instrument_names[i] = (Kaitai::Struct::Stream::bytes_terminate(Kaitai::Struct::Stream::bytes_strip_right(@_io.read_bytes(32), 0), 0, false)).force_encoding("ASCII")
    }
    self
  end
  class InstrumentEntry < Kaitai::Struct::Struct
    def initialize(_io, _parent = nil, _root = self)
      super(_io, _parent, _root)
      _read
    end

    def _read
      @flags = @_io.read_u2le
      @finetune = @_io.read_u1
      @note = @_io.read_u1
      @instruments = Array.new(2)
      (2).times { |i|
        @instruments[i] = Instrument.new(@_io, self, @_root)
      }
      self
    end
    attr_reader :flags
    attr_reader :finetune

    ##
    # MIDI note for fixed instruments, 0 otherwise
    attr_reader :note
    attr_reader :instruments
  end
  class Instrument < Kaitai::Struct::Struct
    def initialize(_io, _parent = nil, _root = self)
      super(_io, _parent, _root)
      _read
    end

    def _read
      @op1 = OpSettings.new(@_io, self, @_root)
      @feedback = @_io.read_u1
      @op2 = OpSettings.new(@_io, self, @_root)
      @unused = @_io.read_u1
      @base_note = @_io.read_s2le
      self
    end
    attr_reader :op1

    ##
    # Feedback/AM-FM (both operators)
    attr_reader :feedback
    attr_reader :op2
    attr_reader :unused

    ##
    # Base note offset
    attr_reader :base_note
  end

  ##
  # OPL2 settings for one operator (carrier or modulator)
  class OpSettings < Kaitai::Struct::Struct
    def initialize(_io, _parent = nil, _root = self)
      super(_io, _parent, _root)
      _read
    end

    def _read
      @trem_vibr = @_io.read_u1
      @att_dec = @_io.read_u1
      @sust_rel = @_io.read_u1
      @wave = @_io.read_u1
      @scale = @_io.read_u1
      @level = @_io.read_u1
      self
    end

    ##
    # Tremolo/vibrato/sustain/KSR/multi
    attr_reader :trem_vibr

    ##
    # Attack rate/decay rate
    attr_reader :att_dec

    ##
    # Sustain level/release rate
    attr_reader :sust_rel

    ##
    # Waveform select
    attr_reader :wave

    ##
    # Key scale level
    attr_reader :scale

    ##
    # Output level
    attr_reader :level
  end
  attr_reader :magic
  attr_reader :instruments
  attr_reader :instrument_names
end