| MD_YM2413 Library 1.0 Library for Yahama YM2413 sound synthesizer

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Attributes | List of all members
MD_YM2413 Class Reference

`#include <MD_YM2413.h>`

## Public Types

enum | instrument_t { I_CUSTOM = 0 , I_VIOLIN = 1 , I_GUITAR = 2 , I_PIANO = 3 , I_FLUTE = 4 , I_CLARINET = 5 , I_OBOE = 6 , I_TRUMPET = 7 , I_ORGAN = 8 , I_HORN = 9 , I_SYNTH = 10 , I_HARPSICHORD = 11 , I_VIBRAPHONE = 12 , I_SYNTH_BASS = 13 , I_ACOUSTIC_BASS = 14 , I_EGUITAR = 15 ,
P_HI_HAT = 16 + 0 , P_TOP_CYMBAL = 16 + 1 , P_TOM_TOM = 16 + 2 , P_SNARE_DRUM = 16 + 3 ,
P_BASS_DRUM = 16 + 4 , I_UNDEFINED = 0xff
}

## Public Member Functions

| MD_YM2413 (const uint8_t *D, uint8_t we, uint8_t a0)
| ~MD_YM2413 (void)
void | begin (void)
Hardware and Library Management.
uint8_t | countChannels (void)
bool | isPercussion (void)
bool | isPercussion (uint8_t chan)
void | setPercussion (bool bEnable)
void | loadInstrumentOPL2 (const uint8_t *ins, bool fromPROGMEM=true)
void | loadInstrument (const uint8_t *data)
void | setSustain (uint8_t chan, bool sustain)
bool | isIdle (uint8_t chan)
void | run (void)
void | write (uint8_t addr, uint8_t data)
Sound Management.
bool | setInstrument (uint8_t chan, instrument_t instr, uint8_t vol=VOL_MAX)
instrument_t | getInstrument (uint8_t chan)
uint8_t | getVolume (uint8_t chan)
void | setVolume (uint8_t chan, uint8_t v)
void | setVolume (uint8_t v)
void | noteOn (uint8_t chan, uint16_t freq, uint8_t vol, uint16_t duration=0)
void | noteOn (uint8_t chan, uint8_t octave, uint8_t note, uint8_t vol, uint16_t duration=0)
void | noteOff (uint8_t chan)

## Static Public Attributes

static const uint8_t | VOL_OFF = 0x0
| Convenience constant for volume off.
static const uint8_t | VOL_MAX = 0xf
| Convenience constant for volume maximum.
static const uint8_t | MIN_OCTAVE = 1
| smallest octave playable
static const uint8_t | MAX_OCTAVE = 8
| largest playable octave
static const uint8_t | CH_UNDEFINED = 255
| undefined channel indicator
static const uint8_t | OPL2_DATA_SIZE = 12
| OPL2 instrument definition size.
static const uint8_t | PERC_CHAN_BASE = 6
| Base channel number for percussion instruments if enabled.
static const uint8_t | CH_HH = PERC_CHAN_BASE + 0
| HI HAT channel number.
static const uint8_t | CH_TCY = PERC_CHAN_BASE + 1
| TOP CYMBAL channel number.
static const uint8_t | CH_TOM = PERC_CHAN_BASE + 2
| TOM TOM channel number.
static const uint8_t | CH_SD = PERC_CHAN_BASE + 3
| SNARE DRUM channel number.
static const uint8_t | CH_BD = PERC_CHAN_BASE + 4
| BASS DRUM channel number.

## Detailed Description

Base class for the MD_YM2413 library

## Member Enumeration Documentation

## ◆ instrument_t

enum MD_YM2413::instrument_t

Predefined musical and percussion instrument definitions The IC has a number of predefined profiles instruments with IDs that are defined here.

## Constructor & Destructor Documentation

## ◆ MD_YM2413()

MD_YM2413::MD_YM2413 | ( | const uint8_t * | D,
|  | uint8_t | we,
|  | uint8_t | a0
| ) |  |

Class Constructor.

Instantiate a new instance of this derived class. The parameters passed are used to connect the software to the hardware. Multiple instances may co-exist.

The D array is arranged to correspond to the IC pins (ie, pin D[0] is connected to IC pin D0, D[1] to D1, etc). D0 is the MSB in the data byte, D7 the LSB.

The we and a0 pins are used for handshaking the data over the data bus.

See also
  Hardware Connections

Parameters

  D | pointer to array of 8 pins used as the data bus interface
  we | pin number used as write enable
  a0 | pin number used as address/data selector

## ◆ ~MD_YM2413()

MD_YM2413::~MD_YM2413 | ( | void |  | ) |

Class Destructor.

Does the necessary to clean up once the object is no longer required.

## Member Function Documentation

## ◆ begin()

void MD_YM2413::begin | ( | void |  | ) |

Initialize the object.

Initialize the object data. This needs to be called during setup() to initialize new data for the class that cannot be done during the object creation.

All the I/O is initialize, percussion mode is disabled and all instruments are set as I_PIANO at VOL_MAX volume by default.

See also
  setVolume(), setInstrument(), setPercussion()

## ◆ countChannels()

uint8_t MD_YM2413::countChannels | ( | void |  | ) |

Return the number of channels.

Return the number of channels depending on whether the percussion instruments are set.

See also
  setPercussion()

Returns
  the number of channels in the current configuration.

## ◆ getInstrument()

instrument_t MD_YM2413::getInstrument | ( | uint8_t | chan | ) |

Get the current instrument setting

Get the instrument set for the specified channel. This will be one of the instrument_t values.

See also
  setInstrument(), instrument_t

Parameters

  chan | channel number on which volume is set [0..countChannels()-1].

Returns
  the value of the instrument set for the channel.

## ◆ getVolume()

uint8_t MD_YM2413::getVolume | ( | uint8_t | chan | ) |

Get the volume for a channel.

Get the current volume for a channel.

Parameters

  chan | channel number on which volume is set [0..countChannels()-1].

Returns
  the current volume in the range [VOL_MIN..VOL_MAX].

## ◆ isIdle()

bool MD_YM2413::isIdle | ( | uint8_t | chan | ) |

Return the idle state of a channel.

Used to check if a channel is currently idle (ie, not playing a note).

Parameters

  chan | channel to check [0..countChannels()-1].

Returns
  true if the channel is idle, false otherwise.

## ◆ isPercussion() [1/2]

bool MD_YM2413::isPercussion | ( | uint8_t | chan | ) |

Check if the channel is for percussion

Returns whether the specified channel is allocated to a percussion instrument. Percussion instruments are allocated to specific channels as explained in setPercussion().

See also
  setPercussion()

Parameters

  chan | channel to check [0..countChannels()-1].

Returns
  true if specified is for percussion, false otherwise.

## ◆ isPercussion() [2/2]

bool MD_YM2413::isPercussion | ( | void |  | ) |

Return the current library mode

Returns the current library/hardware operating mode set by setPercussion().

See also
  setPercussion()

Returns
  true if percussion channels are enabled, false otherwise.

## ◆ loadInstrument()

void MD_YM2413::loadInstrument | ( | const uint8_t * | data | ) |

Define direct parameters for a custom instrument.

Define the data for a custom instrument directly. The data is preformatted for the YM2413 device and will be passed through without further processing.

This method is used to set instrument definitions that are in OPLL format and held in the application as a compact byte sequence.

See also
  Custom Instruments

Parameters

  data | an array of 8 bytes in RAM that will be written to registers 0x00 through 0x07.

## ◆ loadInstrumentOPL2()

void MD_YM2413::loadInstrumentOPL2 | ( | const uint8_t * | ins,
|  | bool | fromPROGMEM = `true`
| ) |  |

Define the parameters for a custom instrument.

Define the playing envelope in OPL2/OPL3 format for the custom instrument. The parameters are in higher OPL format, which is readily available and very close to the YM2413 format (OPLL). Translations are made as required.

See also
  Custom Instruments

Parameters

  ins | an array of OPL2_DATA_SIZE uint8_t bytes in OPL2 format data.
  fromPROGMEM | true if the data is loaded from PROGMEM false otherwise.

## ◆ noteOff()

void MD_YM2413::noteOff | ( | uint8_t | chan | ) |

Stop playing a note

Stop the note currently playing on the specified channel

Causes a key-off event to be processed by the channel.

See also
  noteOn(), run()

Parameters

  chan | channel number on which to stop this note [0..countChannels()-1].

## ◆ noteOn() [1/2]

void MD_YM2413::noteOn | ( | uint8_t | chan,
|  | uint16_t | freq,
|  | uint8_t | vol,
|  | uint16_t | duration = `0`
| ) |  |

Play a note (frequency)

Output a note with frequency freq on the specified channel using the instrument currently defined for the channel.

If specified, the duration will cause an automatic note off event when the total time has expired. If duration is 0 the note will be sustained until it is turned off by the application.

See also
  noteOff(), run()

Parameters

  chan | channel number on which to play this note [0..countChannels()-1].
  freq | frequency to play.
  vol | volume to set this note in range [VOL_MIN..VOL_MAX].
  duration | length of time in ms for the whole note to last.

## ◆ noteOn() [2/2]

void MD_YM2413::noteOn | ( | uint8_t | chan,
|  | uint8_t | octave,
|  | uint8_t | note,
|  | uint8_t | vol,
|  | uint16_t | duration = `0`
| ) |  |

Play a note (octave and note#)

Output a note defined by octave and note number on the specified channel using the instrument currently defined for the channel.

Middle C is the first note in octave 4 (C4). Notes [C, C#, D, D#, E, F, F#, G, G#, A, A#, B] are numbered sequentially 0 to 11 within the octave.

If specified, the duration will cause an automatic note off event when the total time has expired. If duration is 0 the note will be sustained until it is turned off by the application.

See also
  noteOff(), run()

Parameters

  chan | channel number on which to play this note [0..countChannels()-1].
  octave | the octave block for this note [MIN_OCTAVE..MAX_OCTAVE].
  note | the note number to play [0..11] as defined above.
  vol | volume to set this note in range [VOL_MIN..VOL_MAX].
  duration | length of time in ms for the whole note to last.

## ◆ run()

void MD_YM2413::run | ( | void |  | ) |

Run the music machine.

Runs the automatic note off timing for all channels. This should be called from the main loop() as frequently as possible to allow the library to execute the note required timing for each channel.

This method is not required if the application does not use durations when invoking noteOn().

## ◆ setInstrument()

bool MD_YM2413::setInstrument | ( | uint8_t | chan,
|  | instrument_t | instr,
|  | uint8_t | vol = `VOL_MAX`
| ) |  |

Set the playing instrument for a channel.

Set the instrument for the channel to be one the value specified. Valid instruments are given by the enumerated type instrument_t.

If percussion is not enabled, the valid range of instruments is one of the I_* values on channels [0..9]. The percussion instruments P_* are automatically set up on the channels CH_* [6..11] when percussion mode is enabled, and instruments I_* can be set up on channels [0..5].

Custom instruments must be defined before they can be used.

See also
  setPercussion(), instrument_t, setSustain(), defineInstrument()

Parameters

  chan | channel number on which volume is set [0..countChannels()-1].
  instr | one of the instruments I_* from instrument_t.
  vol | volume to set for the specified channel in range [VOL_MIN..VOL_MAX].

Returns
  true if the instrument was set correctly.

## ◆ setPercussion()

void MD_YM2413::setPercussion | ( | bool | bEnable | ) |

Set the current library/hardware operating mode.

The library can operate with or without percussion instruments configured. Without percussion instruments, there are 9 channels(0..8] available for general instruments. With percussion enabled, there are 6 channels[0..5] available for general instruments and 5 channels[6..10], for a total of 11, allocated to percussion instruments.

The method countChannels() will always return the total number of channels for the current configuration.

See also
  isPercussion(), countChannels()

Parameters

  bEnable | true to enable percussion mode, false otherwise.

## ◆ setSustain()

void MD_YM2413::setSustain | ( | uint8_t | chan,
|  | bool | sustain
| ) |  |

Standardize the instrument release phase

For the specific channel, set the release value to a standarized mid-point for this instance of the instrument.

See also
  setInstrument()

Parameters

  chan | channel number on which sustain is set [0..countChannels()-1].
  sustain | set true to standardize the release phase to a mid level value.

## ◆ setVolume() [1/2]

void MD_YM2413::setVolume | ( | uint8_t | chan,
|  | uint8_t | v
| ) |  |

Set the volume for a channel.

Set the volume for a channel to be the value specified. Valid values are all the values in the range [VOL_MIN..VOL_MAX].

Parameters

  chan | channel number on which volume is set [0..countChannels()-1].
  v | volume to set for the specified channel in range [VOL_MIN..VOL_MAX].

## ◆ setVolume() [2/2]

void MD_YM2413::setVolume | ( | uint8_t | v | ) |

Set the volume for all channels.

Set the volume for all channels to be the specified value. Valid values are all the values in the range [VOL_MIN..VOL_MAX].

Parameters

  v | volume to set for all channels in range [VOL_MIN..VOL_MAX].

## ◆ write()

void MD_YM2413::write | ( | uint8_t | addr,
|  | uint8_t | data
| ) |  |

Write a byte directly to the device

This method should be used with caution, as it bypasses all the checks and buffering built into the library. It is provided to support applications that are a collection of register setting to be written to hardware at set time intervals (eg, VGM files).

Parameters

  addr | the 8 bit device address to write the data.
  data | the 8 bit data value to write to the device.

The documentation for this class was generated from the following files:

- src/MD_YM2413.h
- src/MD_YM2413.cpp
- src/MD_YM2413_hw.cpp