Macros
#define	OSC_DITHER

#define	UINT14_MAX (0x3FFF)

#define	SAMPLES_TO_MIDI_TICKS(n, tempo, div) ((n) * 1000000 * (div) / DAC_SAMPLE_RATE_HZ / (tempo))
	Convert the sample count to MIDI ticks.

#define	TICKS_TO_SAMPLES(ticks, tempo, div) ((ticks) * DAC_SAMPLE_RATE_HZ / (1000000) * (tempo) / (div))
	Convert a number of MIDI ticks to the offset of the first sample of the.

#define	VS_ANY(statePtr) ((statePtr)->on)

#define	VOICE_CUR_VOL(voice)

#define	SET_MSB(target, val)
	Set only the MSB of a 14-bit value.

#define	SET_LSB(target, val)
	Set only the LSB of a 14-bit value.

#define	SHIFT_HI_HAT (0)

#define	SHIFT_WHISTLE (6)

#define	SHIFT_GUIRO (12)

#define	SHIFT_CUICA (18)

#define	SHIFT_TRIANGLE (24)

#define	MASK_HI_HAT (0x3F)

#define	MASK_WHISTLE (0x3F << SHIFT_WHISTLE)

#define	MASK_GUIRO (0x3F << SHIFT_GUIRO)

#define	MASK_CUICA (0x3F << SHIFT_CUICA)

#define	MASK_TRIANGLE (0x3F << SHIFT_TRIANGLE)

#define	VOICE_FREE (0x3F)

Functions
void	midiPlayerInit (midiPlayer_t *player)
	Initialize the MIDI player.

void	midiPlayerReset (midiPlayer_t *player)
	Reset the MIDI player state.

void	midiPlayerResetNewSong (midiPlayer_t *player)
	Reset the MIDI player state by only doing the bare minimum. This is useful when playing multiple sound effects in quick succession.

int32_t	midiPlayerStep (midiPlayer_t *player)
	Calculate and return the next MIDI sample, stepping the player state forward by one sample.

void	midiPlayerFillBuffer (midiPlayer_t player, uint8_t samples, int16_t len)
	Fill a buffer with the next set of samples from the MIDI player. This should be called by the callback passed into initDac(). Samples are generated at sampling rate of DAC_SAMPLE_RATE_HZ.

void	midiPlayerFillBufferMulti (midiPlayer_t players, uint8_t playerCount, uint8_t samples, int16_t len)
	Fill a buffer with the next set of samples from an array of MIDI players.

void	midiAllSoundOff (midiPlayer_t *player)
	Stop all sound immediately. This is not affected by the sustain pedal.

void	midiResetChannelControllers (midiPlayer_t *player, uint8_t channel)
	Reset all controllers on a MIDI channel.

void	midiGmOn (midiPlayer_t *player)
	Activate General MIDI mode on a MIDI player.

void	midiGmOff (midiPlayer_t *player)
	Deactivate General MIDI mode on a MIDI player.

void	midiAllNotesOff (midiPlayer_t *player, uint8_t channel)
	Tun off all notes which are currently on, as though midiNoteOff() were called for each note. This respects the sustain pedal.

void	midiNoteOn (midiPlayer_t *player, uint8_t chanId, uint8_t note, uint8_t velocity)
	Begin playing a note on a given MIDI channel.

void	midiAfterTouch (midiPlayer_t *player, uint8_t channel, uint8_t note, uint8_t velocity)
	Change the velocity of a note on a given MIDI channel, after the note starts playing.

void	midiNoteOff (midiPlayer_t *player, uint8_t channel, uint8_t note, uint8_t velocity)
	Stop playing a particular note on a given MIDI channel.

void	midiSetProgram (midiPlayer_t *player, uint8_t channel, uint8_t program)
	Change the program (instrument) on a given MIDI channel.

void	midiSustain (midiPlayer_t *player, uint8_t channel, uint8_t val)
	Set the hold pedal status.

void	midiSustenuto (midiPlayer_t *player, uint8_t channel, uint8_t val)
	Set the sustenuto pedal status.

void	midiControlChange (midiPlayer_t *player, uint8_t channel, midiControl_t control, uint8_t val)
	Set a MIDI control value.

uint8_t	midiGetControlValue (midiPlayer_t *player, uint8_t channel, midiControl_t control)
	Get the value of a MIDI control.

uint16_t	midiGetControlValue14bit (midiPlayer_t *player, uint8_t channel, midiControl_t control)
	Get the combined value of two MIDI control registers.

void	midiSetParameter (midiPlayer_t *player, uint8_t channel, bool registeredParam, uint16_t param, uint16_t value)
	Set a registered or non-registered parameter value.

uint16_t	midiGetParameterValue (midiPlayer_t *player, uint8_t channel, bool registered, uint16_t param)
	Get the value of a registered or non-registered parameter.

void	midiPitchWheel (midiPlayer_t *player, uint8_t channel, uint16_t value)
	Set the pitch wheel value on a given MIDI channel.

void	midiSetTempo (midiPlayer_t *player, uint32_t tempo)
	Change the MIDI playback tempo.

void	midiSetFile (midiPlayer_t player, const midiFile_t song)
	Configure this MIDI player to read from a MIDI file.

void	midiPause (midiPlayer_t *player, bool pause)
	Set the paused state of a MIDI song.

void	midiSeek (midiPlayer_t *player, uint32_t ticks)
	Seek to a given time offset within a file.

void	initGlobalMidiPlayer (void)
	Initialize the system-wide MIDI players for both BGM and SFX.

void	deinitGlobalMidiPlayer (void)
	Deinitialize and free memory associated with the system-wide MIDI players.

void	globalMidiPlayerFillBuffer (uint8_t *samples, int16_t len)
	Fill the given sample buffer with samples from both the BGM and SFX system-wide MIDI players.

void	globalMidiPlayerPlaySong (midiFile_t *song, uint8_t songIdx)
	Play a song on one of the system-wide MIDI players, either BGM or SFX.

void	globalMidiPlayerPlaySongCb (midiFile_t *song, uint8_t songIdx, songFinishedCbFn cb)
	Play a song on noe of the system-wide MIDI players, with a callback once the song finishes.

void	globalMidiPlayerSetVolume (uint8_t trackType, int32_t volumeSetting)
	Set the volume using a value from 0 to 13.

void	globalMidiPlayerPauseAll (void)
	Pause all songs currently being played by the system-wide MIDI players.

void	globalMidiPlayerResumeAll (void)
	Resume all songs currently being played by the system-wide MIDI players.

void	globalMidiPlayerStop (bool reset)
	Stop all songs currently being played by the system-wide MIDI players, optionally resetting their state to the beginning of the song.

midiPlayer_t *	globalMidiPlayerGet (uint8_t songIdx)
	Return a pointer to the system-wide MIDI player for the given track type, either MIDI_SFX or MIDI_BGM.

Macro Definition Documentation

◆ OSC_DITHER

#define OSC_DITHER

◆ UINT14_MAX

#define UINT14_MAX (0x3FFF)

◆ SAMPLES_TO_MIDI_TICKS

#define SAMPLES_TO_MIDI_TICKS	(	n,
		tempo,
		div ) ((n) * 1000000 * (div) / DAC_SAMPLE_RATE_HZ / (tempo))

Convert the sample count to MIDI ticks.

◆ TICKS_TO_SAMPLES

#define TICKS_TO_SAMPLES	(	ticks,
		tempo,
		div ) ((ticks) * DAC_SAMPLE_RATE_HZ / (1000000) * (tempo) / (div))

Convert a number of MIDI ticks to the offset of the first sample of the.

◆ VS_ANY

#define VS_ANY ( statePtr ) ((statePtr)->on)

◆ VOICE_CUR_VOL

#define VOICE_CUR_VOL ( voice )

Value:

    (/*(uint8_t)*/ ((voice)->transitionStartVol                                                  \
                    + ((int)(voice)->targetVol - (int)(voice)->transitionStartVol)               \
                          * ((int)(voice)->transitionTicksTotal - (int)(voice)->transitionTicks) \
                          / (int)(voice)->transitionTicksTotal))

◆ SET_MSB

#define SET_MSB	(		target,
			val )

Value:

    do                                         \
    {                                          \
        uint16_t new14bitVal = ((val) & 0x7F); \
        new14bitVal <<= 7;                     \
        new14bitVal |= ((target) & 0x7F);      \
        (target) = new14bitVal;                \
    } while (0)

Set only the MSB of a 14-bit value.

◆ SET_LSB

#define SET_LSB	(		target,
			val )

Value:

    do                                                 \
    {                                                  \
        uint16_t new14bitVal = ((target) >> 7) & 0x7F; \
        new14bitVal <<= 7;                             \
        new14bitVal |= ((val) & 0x7F);                 \
        (target) = new14bitVal;                        \
    } while (0)

Set only the LSB of a 14-bit value.

◆ SHIFT_HI_HAT

#define SHIFT_HI_HAT (0)

◆ SHIFT_WHISTLE

#define SHIFT_WHISTLE (6)

◆ SHIFT_GUIRO

#define SHIFT_GUIRO (12)

◆ SHIFT_CUICA

#define SHIFT_CUICA (18)

◆ SHIFT_TRIANGLE

#define SHIFT_TRIANGLE (24)

◆ MASK_HI_HAT

#define MASK_HI_HAT (0x3F)

◆ MASK_WHISTLE

#define MASK_WHISTLE (0x3F << SHIFT_WHISTLE)

◆ MASK_GUIRO

#define MASK_GUIRO (0x3F << SHIFT_GUIRO)

◆ MASK_CUICA

#define MASK_CUICA (0x3F << SHIFT_CUICA)

◆ MASK_TRIANGLE

#define MASK_TRIANGLE (0x3F << SHIFT_TRIANGLE)

◆ VOICE_FREE

#define VOICE_FREE (0x3F)

Function Documentation

◆ midiPlayerInit()

void midiPlayerInit ( midiPlayer_t * player )

Initialize the MIDI player.

Parameters

player The MIDI player to initialize

◆ midiPlayerReset()

void midiPlayerReset ( midiPlayer_t * player )

Reset the MIDI player state.

Parameters

player The MIDI player to reset

◆ midiPlayerResetNewSong()

void midiPlayerResetNewSong ( midiPlayer_t * player )

Reset the MIDI player state by only doing the bare minimum. This is useful when playing multiple sound effects in quick succession.

Parameters

player The MIDI player to reset

◆ midiPlayerStep()

int32_t midiPlayerStep ( midiPlayer_t * player )

Calculate and return the next MIDI sample, stepping the player state forward by one sample.

Parameters

player The player to step forward

Returns: int32_t The next signed 32-bit sample, without any headroom or clipping applied

◆ midiPlayerFillBuffer()

void midiPlayerFillBuffer	(	midiPlayer_t *	player,
		uint8_t *	samples,
		int16_t	len )

Fill a buffer with the next set of samples from the MIDI player. This should be called by the callback passed into initDac(). Samples are generated at sampling rate of DAC_SAMPLE_RATE_HZ.

Parameters

player	The MIDI player to sample from
samples	An array of unsigned 8-bit samples to fill
len	The length of the array to fill

◆ midiPlayerFillBufferMulti()

void midiPlayerFillBufferMulti	(	midiPlayer_t *	players,
		uint8_t	playerCount,
		uint8_t *	samples,
		int16_t	len )

Fill a buffer with the next set of samples from an array of MIDI players.

Parameters

players	A pointer to an array of MIDI players
playerCount	The number of MIDI players in the array
samples	An array of unsigned 8-bit samples to fill
len	The length of the array to fill

◆ midiAllSoundOff()

void midiAllSoundOff ( midiPlayer_t * player )

Stop all sound immediately. This is not affected by the sustain pedal.

Parameters

player The player to stop

◆ midiResetChannelControllers()

void midiResetChannelControllers	(	midiPlayer_t *	player,
		uint8_t	channel )

Reset all controllers on a MIDI channel.

This includes:

Sustain Pedal
Legato, Vibrato, Sustenuto, etc.

Parameters

player
channel

◆ midiGmOn()

void midiGmOn ( midiPlayer_t * player )

Activate General MIDI mode on a MIDI player.

Parameters

player The MIDI player to set to General MIDI mode

◆ midiGmOff()

void midiGmOff ( midiPlayer_t * player )

Deactivate General MIDI mode on a MIDI player.

Parameters

player The MIDI player to take out of General MIDI mode

◆ midiAllNotesOff()

void midiAllNotesOff	(	midiPlayer_t *	player,
		uint8_t	channel )

Tun off all notes which are currently on, as though midiNoteOff() were called for each note. This respects the sustain pedal.

Parameters

player	The MIDI player
channel	The MIDI channel on which to stop notes

◆ midiNoteOn()

void midiNoteOn	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	note,
		uint8_t	velocity )

Begin playing a note on a given MIDI channel.

Using a velocity of 0 is equivalent to calling midiNoteOff()

Parameters

player	The MIDI player
channel	The MIDI channel on which to start the note
note	The note number to play
velocity	The note velocity which affects its volume and effects

◆ midiAfterTouch()

void midiAfterTouch	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	note,
		uint8_t	velocity )

Change the velocity of a note on a given MIDI channel, after the note starts playing.

Parameters

player	The MIDI player
channel	The MIDI channel on which to change the note velocity
note	The currently-playing note number to modify
velocity	The note velocity which affects its volume and effects

◆ midiNoteOff()

void midiNoteOff	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	note,
		uint8_t	velocity )

Stop playing a particular note on a given MIDI channel.

Parameters

player	The MIDI player
channel	The MIDI channel on which to stop the note
note	The note number to stop
velocity	[NYI] The release velocity which affects the note's release time

◆ midiSetProgram()

void midiSetProgram	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	program )

Change the program (instrument) on a given MIDI channel.

Parameters

player	The MIDI player
channel	The MIDI channel whose program will be changed
program	The program ID, from 0-127, to set for this channel

◆ midiSustain()

void midiSustain	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	val )

Set the hold pedal status.

When set, all notes that are currently on will be sustained until the pedal is unset, as well as all notes that are played after the pedal is set.

This is a convenience method for midiControlChange(player, channel, MCC_HOLD_PEDAL (64), val ? 127:0)

Parameters

player	The MIDI player
channel	The MIDI channel to set the hold status for
val	The sustain pedal value. Values 0-63 are OFF, and 64-127 are ON.

◆ midiSustenuto()

void midiSustenuto	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint8_t	val )

Set the sustenuto pedal status.

When set, only the notes that are currently on will be sustained until the pedal is unset. Notes that are played after the pedal is set will not be sustained.

Parameters

player	The MIDI player
channel	The MIDI channel to set the sustenuto status for
val	The sustenuto pedal value. Values 0-63 are OFF, and 64-127 are ON.

◆ midiControlChange()

void midiControlChange	(	midiPlayer_t *	player,
		uint8_t	channel,
		midiControl_t	control,
		uint8_t	val )

Set a MIDI control value.

Parameters

player	The MIDI player
channel	The channel to set the control on
control	The control number to set
val	The control value, from 0-127 whose meaning depends on the control number

◆ midiGetControlValue()

uint8_t midiGetControlValue	(	midiPlayer_t *	player,
		uint8_t	channel,
		midiControl_t	control )

Get the value of a MIDI control.

Parameters

player	The MIDI player
channel	The channel to retrieve the control from
control	The MIDI control number of the control

Returns: uint8_t The value of the specified control, or 0 if the specified controller is not implemented

◆ midiGetControlValue14bit()

uint16_t midiGetControlValue14bit	(	midiPlayer_t *	player,
		uint8_t	channel,
		midiControl_t	control )

Get the combined value of two MIDI control registers.

Parameters

player	The MIDI player
channel	The channel to retrieve the control from
control	The MIDI control number of either of the two controls that make up the value

Returns: uint16_t The value of the specified control, or 0 if the specified controller is not implemented

◆ midiSetParameter()

void midiSetParameter	(	midiPlayer_t *	player,
		uint8_t	channel,
		bool	registered,
		uint16_t	param,
		uint16_t	value )

Set a registered or non-registered parameter value.

Parameters

player	The MIDI player
channel	The channel to set the parameter on
registered	true if param refers to a registered parameter number and false if it refers to a non-registered
param	The registered or non-registered MIDI parameter to set the value of
value	The 14-bit value to set the parameter to

◆ midiGetParameterValue()

uint16_t midiGetParameterValue	(	midiPlayer_t *	player,
		uint8_t	channel,
		bool	registered,
		uint16_t	param )

Get the value of a registered or non-registered parameter.

Parameters

player	The MIDI player
channel	The channel to retrieve the parameter from
registered	true if param refers to a registered parameter number and false if it refers to a non-registered
param	The registered or non-registered MIDI parameter number to retrieve the value for

Returns: The current 14-bit value of the given registered or non-registered parameter, or 0 if the parameter is unsupported

◆ midiPitchWheel()

void midiPitchWheel	(	midiPlayer_t *	player,
		uint8_t	channel,
		uint16_t	value )

Set the pitch wheel value on a given MIDI channel.

By default, the center of the pitch wheel is 0x2000. A value of 0x0000 transposes one step down, while a value of 0x3FFF transposes one step down.

[NYI] The range of the pitch wheel can be changed using the registered parameters, with MSB being the range in (+/-)semitones and LSB being the range in (+/-) cents

Parameters

player	The MIDI player
channel	The MIDI channel to change the pitch wheel for
value	The pitch wheel value, from 0 to 0x3FFF (14-bits)

◆ midiSetTempo()

void midiSetTempo	(	midiPlayer_t *	player,
		uint32_t	tempo )

Change the MIDI playback tempo.

Parameters

player	The player to change the tempo of
tempo	The new tempo to set, in microseconds per quarter note

◆ midiSetFile()

void midiSetFile	(	midiPlayer_t *	player,
		const midiFile_t *	file )

Configure this MIDI player to read from a MIDI file.

Parameters

player	The MIDI player
file	A pointer to the MIDI file to be played

◆ midiPause()

void midiPause	(	midiPlayer_t *	player,
		bool	pause )

Set the paused state of a MIDI song.

Parameters

player	The player
pause	True to pause, false to play

◆ midiSeek()

void midiSeek	(	midiPlayer_t *	player,
		uint32_t	ticks )

Seek to a given time offset within a file.

Note that in the current implementation, seeking backwards by any amount requires re-reading the file from the beginning, and so may be very slow, particularly for large MIDI files.

Parameters

player	The MIDI player to seek on
ticks	The absolute number of MIDI ticks to seek to. If this is -1, it will seek to the end of the song

◆ initGlobalMidiPlayer()

void initGlobalMidiPlayer ( void )

Initialize the system-wide MIDI players for both BGM and SFX.

◆ deinitGlobalMidiPlayer()

void deinitGlobalMidiPlayer ( void )

Deinitialize and free memory associated with the system-wide MIDI players.

◆ globalMidiPlayerFillBuffer()

void globalMidiPlayerFillBuffer	(	uint8_t *	samples,
		int16_t	len )

Fill the given sample buffer with samples from both the BGM and SFX system-wide MIDI players.

Parameters

[out]	samples	A pointer to the array of unsigned 8-bit samples to be filled
	len	The number of samples

◆ globalMidiPlayerPlaySong()

void globalMidiPlayerPlaySong	(	midiFile_t *	song,
		uint8_t	trackType )

Play a song on one of the system-wide MIDI players, either BGM or SFX.

Parameters

song	A pointer to the song to play
trackType	The player to use, either MIDI_SFX or MIDI_BGM

◆ globalMidiPlayerPlaySongCb()

void globalMidiPlayerPlaySongCb	(	midiFile_t *	song,
		uint8_t	trackType,
		songFinishedCbFn	cb )

Play a song on noe of the system-wide MIDI players, with a callback once the song finishes.

Parameters

song	A pointer to the song to play
trackType	The player to use, either MIDI_SFX or MIDI_BGM
cb	The function to be called once the song completes

◆ globalMidiPlayerSetVolume()

void globalMidiPlayerSetVolume	(	uint8_t	trackType,
		int32_t	volumeSetting )

Set the volume using a value from 0 to 13.

Parameters

trackType	The player to set the volume for, either MIDI_SFX or MIDI_BGM
volumeSetting	The volume value

◆ globalMidiPlayerPauseAll()

void globalMidiPlayerPauseAll ( void )

Pause all songs currently being played by the system-wide MIDI players.

◆ globalMidiPlayerResumeAll()

void globalMidiPlayerResumeAll ( void )

Resume all songs currently being played by the system-wide MIDI players.

◆ globalMidiPlayerStop()

void globalMidiPlayerStop ( bool reset )

Stop all songs currently being played by the system-wide MIDI players, optionally resetting their state to the beginning of the song.

Parameters

reset if true, the players will be reset to the beginning of the song

◆ globalMidiPlayerGet()

midiPlayer_t * globalMidiPlayerGet ( uint8_t trackType )

Return a pointer to the system-wide MIDI player for the given track type, either MIDI_SFX or MIDI_BGM.

Parameters

trackType Which MIDI player to return, either MIDI_SFX or MIDI_BGM

Returns: midiPlayer_t*

Macros

Functions

Macro Definition Documentation

◆ OSC_DITHER

◆ UINT14_MAX

◆ SAMPLES_TO_MIDI_TICKS

◆ TICKS_TO_SAMPLES

◆ VS_ANY

◆ VOICE_CUR_VOL

◆ SET_MSB

◆ SET_LSB

◆ SHIFT_HI_HAT

◆ SHIFT_WHISTLE

◆ SHIFT_GUIRO

◆ SHIFT_CUICA

◆ SHIFT_TRIANGLE

◆ MASK_HI_HAT

◆ MASK_WHISTLE

◆ MASK_GUIRO

◆ MASK_CUICA

◆ MASK_TRIANGLE

◆ VOICE_FREE

Function Documentation

◆ midiPlayerInit()

◆ midiPlayerReset()

◆ midiPlayerResetNewSong()

◆ midiPlayerStep()

◆ midiPlayerFillBuffer()

◆ midiPlayerFillBufferMulti()

◆ midiAllSoundOff()

◆ midiResetChannelControllers()

◆ midiGmOn()

◆ midiGmOff()

◆ midiAllNotesOff()

◆ midiNoteOn()

◆ midiAfterTouch()

◆ midiNoteOff()

◆ midiSetProgram()

◆ midiSustain()

◆ midiSustenuto()

◆ midiControlChange()

◆ midiGetControlValue()

◆ midiGetControlValue14bit()

◆ midiSetParameter()

◆ midiGetParameterValue()

◆ midiPitchWheel()

◆ midiSetTempo()

◆ midiSetFile()

◆ midiPause()

◆ midiSeek()

◆ initGlobalMidiPlayer()

◆ deinitGlobalMidiPlayer()

◆ globalMidiPlayerFillBuffer()

◆ globalMidiPlayerPlaySong()

◆ globalMidiPlayerPlaySongCb()

◆ globalMidiPlayerSetVolume()

◆ globalMidiPlayerPauseAll()

◆ globalMidiPlayerResumeAll()

◆ globalMidiPlayerStop()

◆ globalMidiPlayerGet()