csound-opl3 : OPL3 (YMF262) FM synthesis emulation for Csound

Overview

csound-opl3 is a Csound plugin which provides an interface to emulated OPL3 FM synthesis as popularised by Yamaha chips, utilised by various computer sound cards from the late 1980s onwards. The YMF262 chip in particular was popularised by inclusion on the Sound Blaster 16 card, and Yamaha's specific FM implementation had a significant impact on home computer synthesis, in particular through usage in games.

The YMF262 chip applies an implementation of synthesis similar to some of Yamaha's other well known FM synthesisers such as the DX7 and TX81z although provides a cut-down 4 oscillator approach. Due to the popularity of the chip for computer games, it has been widely emulated in software and notably included in DOSBox, which has in turn been used (along with other emulations) by ADLMIDI, further extrapolated to libADLMIDI and finally utilised to create this set of plugin opcodes for Csound.

Complete control over all four oscillators (operators, in Yamaha terminology) is provided, along with the ability to use preset banks (instrument sets) which are compiled into ADLMIDI/libADLMIDI - many are custom banks extracted from various games and other software from the 1990s.

Requirements

Cmake >= 2.8.12
Csound with development headers
libADLMIDI

Tested on Linux with Csound 6.17 and libADLMIDI 1.5.0.1 as of writing.

Installation

Create a build directory at the top of the source tree, execute cmake .., make and optionally make install as root. If the latter is not used/possible then the resulting library can be used with the --opcode-lib flag in Csound. eg:

mkdir build && cd build
cmake ..
make && sudo make install

Cmake should find Csound and any other required libraries using the modules in the cmake/Modules directory and installation should be as simple as above.

Notes

Multiple types of OPL3 emulation are provided as in libADLMIDI. These are explained further on the libADLMIDI and ADLMIDI pages.

Instrument parameter ranges are representative of the original OPL3 chip which used 8-bit registers, hence ranges such as 0 - 15 and 0 - 3. The parameters are all unsigned integers, so for example with attack, there are actually only 16 possible attack times. Any floating point numbers passed will just be converted accordingly. This is also the case for control change messages which are unsigned 8-bit integers.

The only exception to this is the pitch bend opcode, oplpitchbend, which takes a value corresponding to a midi note (ie 1 = 1 semitone) and can be negative.

There are two modes of selecting sounds to be used:

Preset banks and patches (compiled into libADLMIDI) using the oplsetbank, oplpatchchange and oplbanknames opcodes.
Parametric instrument editing of all parameters using the oplinstrument and oploperator opcodes.

Once the oplinstrument opcode is used for a particular opl instance, it will switch the channel from using preset banks to parametric editing.

Examples

Four examples are provided in the examples directory, including a FLTK gui for editing instruments. There is also a demonstration video of the FLTK editor, and another video showing all four examples.

Opcode reference

opl

Create an instance of the emulated OPL3 synthesiser.

ioplhandle, aleft, aright __opl__ [iemulation=0, irunatpcmrate=0]

ioplhandle : handle to be used in other opcodes to control synthesis
aleft, aright : stereo audio outputs
iemulation : OPL3 chip emulation type (0 = DOSBox, 1 = Nuked_1.8, 2=Nuked_1.74, 3=Opal, 4=Java)
irunatpcmrate : run emulation at PCM rate; setting to 1 may reduce CPU usage but lessen emulation accuracy

oplnote

Play a note using the synthesiser specified by ioplhandle.

oplnote ioplhandle, ichannel, inote, ivelocity

ioplhandle : handle created by the opl opcode
ichannel : channel for playback (0 - 15)
inote : midi note number to play
ivelocity : midi note velocity (0 - 127)

oplinstrument

Modify the current instrument parameters and obtain handles to all four operators (oscillators) for further manipulation with the oploperator opcode.

iop1, iop2, iop3, iop4 __oplinstrument__ ioplhandle, kmode12, kmode34, kfbk12, kfbk34, k4op, kpseudo4op, kdeepvib, kdeeptrem

iop1, iop2, iop3, iop4 : handles for the individual operators to be used by the oploperator opcode.
ioplhandle : handle created by the opl opcode
kmode12 : op 1 and 2 mode (0 = FM, 1 = AM)
kmode34 : op 3 and 4 mode (0 = FM, 1 = AM)
kfbk12 : op 1 and 2 feedback (0 - 7)
kfbk34 : op 3 and 4 feedback (0 - 7)
k4op : use all 4 operators (0 = no, 1 = yes)
kpseudo4op : use all 4 operators with pseudo emulation (0 = no, 1 = yes)
kdeepvib : global deep vibrato (0 = off, 1 = on)
kdeeptrem : global deep tremolo (0 = off, 1 = on)

oploperator

Alter individual operator parameters. Out of range parameters will wrap around.

oploperator iop, klevel, kscale, kattack, kdecay, ksustain, krelease, kwave, kfreqmul, ktrem, kvib, ksus, kenv

iop : handle for the specific operator as provided by the oplinstrument opcode
klevel : gain level (0 - 63)
kscale : key scale (0 - 3)
kattack : attack time (0 - 15)
kdecay : decay time (0 - 15)
ksustain : sustain time (0 - 15)
krelease : release time (0 - 15)
kwave : waveform (0 - 7)
kfreqmul : frequency multiplier (0 - 15)
ktrem : tremolo switch (0 - 1)
kvib : vibrato switch (0 - 1)
ksus : sustaining switch (0 - 1)
kenv : key envelope switch (0 - 1)

oplpanic

Terminate all current notes and reset the opl instance.

oplpanic ioplhandle

ioplhandle : handle created by the opl opcode

oplbanknames

Obtain all of the bank names compiled into libADLMIDI. The indexes returned can be used by the oplsetbank opcode accordingly.

Sbanks[] __oplbanknames__ ioplhandle

Sbanks[] : array of bank names
ioplhandle : handle created by the opl opcode

oplsetbank

Set the current bank (sound set) for the given opl instance. Any playing notes will be stopped and the instance will be reset (may cause a click if audio is playing).

oplsetbank ioplhandle, ibank

ioplhandle : handle created by the opl opcode
ibank : the bank index (corresponds to the output of oplbanknames)

oplpatchchange

Set the patch for the specified channel.

oplpatchchange ioplhandle, kchannel, kpatch

ioplhandle : handle created by the opl opcode
kchannel : channel index (0 - 15)
kpatch : patch index (0 - 127)

oplpitchbend

Set the pitch bend value for the specified channel.

oplpitchbend ioplhandle, kchannel, kbend

ioplhandle : handle created by the opl opcode
kchannel : channel index (0 - 15)
kbend : bend amount in semitones (may be positive or negative)

oplaftertouch

Set the aftertouch value for the specified channel.

oplaftertouch ioplhandle, kchannel, kaftertouch

ioplhandle : handle created by the opl opcode
kchannel : channel index (0 - 15)
kaftertouch : aftertouch amount (0 - 127)

oplcontrolchange

Set a control change value for a specified channel.

oplcontrolchange ioplhandle, kchannel, kcontrol, kvalue

ioplhandle : handle created by the opl opcode
kchannel : channel index (0 - 15)
kcontrol : MIDI CC number (0 - 127)
kvalue : value (0 - 127)