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.
- Cmake >= 2.8.12
- Csound with development headers
- libADLMIDI
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.
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.
Some examples are provided in the examples directory, including a FLTK gui for editing instruments.
There is also a demonstration video of the FLTK editor.
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
Play a note using the synthesiser specified by ioplhandle.
- 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)
Modify the current instrument parameters and obtain handles to all four operators (oscillators) for further manipulation with the oploperator opcode.
-
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)
Alter individual operator parameters. Out of range parameters will wrap around.
- 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)
Terminate all current notes and reset the opl instance.
- ioplhandle : handle created by the opl opcode
Obtain all of the bank names compiled into libADLMIDI. The indexes returned can be
used by the oplsetbank opcode accordingly.
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).
- ioplhandle : handle created by the opl opcode
- ibank : the bank index (corresponds to the output of oplbanknames
Set the patch for the specified channel.
- ioplhandle : handle created by the opl opcode
- kchannel : channel index (0 - 15)
- kpatch : patch index (0 - 127)
Set the pitch bend value for the specified channel.
- ioplhandle : handle created by the opl opcode
- kchannel : channel index (0 - 15)
- kbend : bend amount in semitones (may be positive or negative)
Set the aftertouch value for the specified channel.
- ioplhandle : handle created by the opl opcode
- kchannel : channel index (0 - 15)
- kaftertouch : aftertouch amount (0 - 127)
Set a control change value for a specified channel.
- ioplhandle : handle created by the opl opcode
- kchannel : channel index (0 - 15)
- kcontrol : MIDI CC number (0 - 127)
- kvalue : value (0 - 127)