MidiPlayer

Inherits: AudioStreamPlayer < Node < Object

A MIDI and SoundFont player class.

Description

The MidiPlayer class can play MIDI files. It does this using a collection of sounds called SoundFont which was originally invented in the early 1990s by Creative Labs for their SoundBlaser AWE32 sound card. The MIDI specification is even older from 1983.

Although these technologies are old, they are still being used today in music industry because they are incredibly handy. While SoundFont has become less relevant with the development of sampling, MIDI specifically has seen continuous use very with minimal changes to the standard since inception.

In order to use this class, the node should be added to the scene tree. Create a new AudioStreamGenerator via inspector in AudioStreamPlayer.stream and then load a MidiFile containing a SoundFont should be set to soundfont and a MidiFile midi song set to midi. For instance:

func _ready():
    $MidiPlayer.midi = preload("res://moonlight.mid")
    $MidiPlayer.soundfont = preload("res://piano.sf2")
    $MidiPlayer.play()

You can find MIDI songs and General MIDI SoundFonts online. Here are just a few completely free ones that you might want to look for: ChoriumRevA.sf2, WeedsGM3.sf2, SGM-V2.01FluidR3_GM.sf2, TimGM6mb.sf2 (close in sound with the original Sound Blaster soundfont), Timbres Of Heaven GM_GS_XG_SFX V 3.0 Final.sf2 (very high quality).

It should be possible to play notes via InputEventMIDI as well.

List of keywords:

channel: And audio channels (or tracks) is the audio route the sound takes and allows one instrument to play. Multiple channels allow for different instruments to play on top of each other. Channel 10 is always set to Drums and is handled differently. The number of channels depends on implementation most commonly 16. Tiny Sound Font (which MidiPlayer uses) allocates channels dynamically so you can have as many as you want.

voice: A voice is related to a channel except that this is the actual audio you hear. Each channel has a voice called a Channel Voice. Some instruments or sound effects may also use voices. The number of voices depends on the implementation. On a typical instrument can be anywhere from 1 (monophonic) to 64 (polyphonic). Similar to channels, voices are allocated dynamically so you may have as many as you wish. There is a way to hard limit the max voices but hasn’t been implemented.

program: A program is the tone quality. Drums has a unique program for playing individual samples, regular notes have a program, many effects have a program. Note that reverb and chorus have not been implemented.

preset/instrument: This is the instrument for example Piano, Harpsichord, etc. It uses various PCM samples mapped to regions of the keyboard. Drums (usually set to channel 10) are special in that each key has a unique sample and the entire instrument is handled by a drum program.

bank: All samples inside a SoundFont are organized in groups called banks. A bank is commonly 128 samples. In practice most SoundFonts define their own internal sample organization.

note/message: Sometimes called message as it represents a note ON/OFF event. This is the note (or key) to play. It must be a value between 0 and 127. A value of 60 is middle C (C4).

volume/velocity: Commonly called velocity. A value of 0.0 means lowest volume (mute) while a value of 1.0 is loudest volume.

Methods

float channel_get_pan ( int channel )
float channel_get_pitchrange ( int channel )
int channel_get_pitchwheel ( int channel )
int channel_get_preset_bank ( int channel )
int channel_get_preset_index ( int channel )
int channel_get_preset_number ( int channel )
float channel_get_tuning ( int channel )
float channel_get_volume ( int channel )
void channel_midi_control ( int channel, int control, int value )
void channel_note_off ( int channel, int note )
void channel_note_off_all ( int channel )
void channel_note_on ( int channel, int note, float volume )
void channel_set_bank ( int channel, int bank )
int channel_set_bank_preset ( int channel, int bank, int preset )
void channel_set_pan ( int channel, float pan )
void channel_set_pitchrange ( int channel, float pitchrange )
void channel_set_pitchwheel ( int channel, int pitchwheel )
void channel_set_preset_index ( int channel, int preset_index )
int channel_set_preset_number ( int channel, int preset_number, int drums )
void channel_set_tuning ( int channel, float tuning )
void channel_set_volume ( int channel, float volume )
PoolStringArray get_preset_names ( ) const
void note_off ( int preset, int note )
void note_off_all ( )
void note_on ( int preset, int note, float volume )

Signals

  • loop_finished ( )

Emitted when the MIDI song finishes playing one loop. This signal is emitted only if looping is true.

Note: When not looping, a finished signal is emitted instead and the MidiPlayer will automatically stop itself when reaching the end of the song.

Property Descriptions

Default true
Setter set_looping(value)
Getter is_looping()

When set to true, midi file will loop forever.

Setter set_midi(value)
Getter get_midi()

This is the MidiFile resource that contains the SoundFont data.

Default 1.0
Setter set_midi_speed(value)
Getter get_midi_speed()

Controls the midi file playback speed.

Setter set_soundfont(value)
Getter get_soundfont()

This is the MidiFile resource that contains the idi song data.

Method Descriptions

Returns the left-right panning of the specified channel.

  • float channel_get_pitchrange ( int channel )

Get the pitch range of a channel.

  • int channel_get_pitchwheel ( int channel )

Get the pitch wheel value for the specified channel.

  • int channel_get_preset_bank ( int channel )

Get the preset sample bank for the specified channel.

  • int channel_get_preset_index ( int channel )

Get the preset index for the specified channel.

  • int channel_get_preset_number ( int channel )

Get the preset number for the specified channel.

  • float channel_get_tuning ( int channel )

Get the tuning of a channel.

  • float channel_get_volume ( int channel )

Get the volume of a channel.

  • void channel_midi_control ( int channel, int control, int value )

MIDI controls are used to produce specialized effects.

  • void channel_note_off ( int channel, int note )

Stop playing a specific note on a specific channel.

  • void channel_note_off_all ( int channel )

Stop all notes on a channel.

  • void channel_note_on ( int channel, int note, float volume )

Start playing a note on a specific channel.

  • void channel_set_bank ( int channel, int bank )

Defines the bank number for the specified channel. Bank is a collection of sound samples.

  • int channel_set_bank_preset ( int channel, int bank, int preset )

Defines the bank and preset for a channel.

  • void channel_set_pan ( int channel, float pan )

Defines left and right panning of a channel.

  • void channel_set_pitchrange ( int channel, float pitchrange )

The the pitch range for a channel.

  • void channel_set_pitchwheel ( int channel, int pitchwheel )

Set the pitch wheel value for a channel.

  • void channel_set_preset_index ( int channel, int preset_index )

Set the preset index for a channel.

  • int channel_set_preset_number ( int channel, int preset_number, int drums )

Set the preset number of a channel. Drums is usually preset 10.

  • void channel_set_tuning ( int channel, float tuning )

Set the tuning of a channel. Tuning is a float value between -1.0 and 1.0.

  • void channel_set_volume ( int channel, float volume )

Set volume of a channel.

Returns a list of preset names stored in the SoundFont.

  • void note_off ( int preset, int note )

Stop playing a specific note.

  • void note_off_all ( )

Stop playing all notes.

Start playing a single note.