From 8723d116c4274de9e60c96bcc8471a0e6c8cbab6 Mon Sep 17 00:00:00 2001 From: Micky Date: Sun, 31 Dec 2023 18:47:18 +0100 Subject: [PATCH] Overhaul documentation about MIDI support --- doc/classes/@GlobalScope.xml | 43 +++++++++++++---------- doc/classes/InputEventMIDI.xml | 64 +++++++++++++++++++--------------- 2 files changed, 59 insertions(+), 48 deletions(-) diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index b74ca4b035e0..9a814f484da2 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -2522,61 +2522,66 @@ The maximum number of game controller axes: OpenVR supports up to 5 Joysticks making a total of 10 axes. - Enum value which doesn't correspond to any MIDI message. This is used to initialize [enum MIDIMessage] properties with a generic state. + Does not correspond to any MIDI message. This is the default value of [member InputEventMIDI.message]. - MIDI note OFF message. Not all MIDI devices send this event; some send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs. + MIDI message sent when a note is released. + [b]Note:[/b] Not all MIDI devices send this message; some may send [constant MIDI_MESSAGE_NOTE_ON] with [member InputEventMIDI.velocity] set to [code]0[/code]. - MIDI note ON message. Some MIDI devices send this event with velocity zero instead of [constant MIDI_MESSAGE_NOTE_OFF], but implementations vary. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs. + MIDI message sent when a note is pressed. - MIDI aftertouch message. This message is most often sent by pressing down on the key after it "bottoms out". + MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch. - MIDI control change message. This message is sent when a controller value changes. Controllers include devices such as pedals and levers. + MIDI message sent when a controller value changes. In a MIDI device, a controller is any input that doesn't play notes. These may include sliders for volume, balance, and panning, as well as switches and pedals. See the [url=https://en.wikipedia.org/wiki/General_MIDI#Controller_events]General MIDI specification[/url] for a small list. - MIDI program change message. This message sent when the program patch number changes. + MIDI message sent when the MIDI device changes its current instrument (also called [i]program[/i] or [i]preset[/i]). - MIDI channel pressure message. This message is most often sent by pressing down on the key after it "bottoms out". This message is different from polyphonic after-touch as it indicates the highest pressure across all keys. + MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of [constant MIDI_MESSAGE_AFTERTOUCH]. - MIDI pitch bend message. This message is sent to indicate a change in the pitch bender (wheel or lever, typically). + MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device. - MIDI system exclusive message. This has behavior exclusive to the device you're receiving input from. Getting this data is not implemented in Godot. + MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. - MIDI quarter frame message. Contains timing information that is used to synchronize MIDI devices. Getting this data is not implemented in Godot. + MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to [constant MIDI_MESSAGE_TIMING_CLOCK]. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. - MIDI song position pointer message. Gives the number of 16th notes since the start of the song. Getting this data is not implemented in Godot. + MIDI message sent to jump onto a new position in the current sequence or song. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. - MIDI song select message. Specifies which sequence or song is to be played. Getting this data is not implemented in Godot. + MIDI message sent to select a sequence or song to play. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. - MIDI tune request message. Upon receiving a tune request, all analog synthesizers should tune their oscillators. + MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message. - MIDI timing clock message. Sent 24 times per quarter note when synchronization is required. + MIDI message sent 24 times after [constant MIDI_MESSAGE_QUARTER_FRAME], to keep connected MIDI devices synchronized. - MIDI start message. Start the current sequence playing. This message will be followed with Timing Clocks. + MIDI message sent to start the current sequence or song from the beginning. - MIDI continue message. Continue at the point the sequence was stopped. + MIDI message sent to resume from the point the current sequence or song was paused. - MIDI stop message. Stop the current sequence. + MIDI message sent to pause the current sequence or song. - MIDI active sensing message. This message is intended to be sent repeatedly to tell the receiver that a connection is alive. + MIDI message sent repeatedly while the MIDI device is idle, to tell the receiver that the connection is alive. Most MIDI devices do not send this message. - MIDI system reset message. Reset all receivers in the system to power-up status. It should not be sent on power-up itself. + MIDI message sent to reset a MIDI device to its default state, as if it was just turned on. It should not be sent when the MIDI device is being turned on. Methods that return [enum Error] return [constant OK] when no error occurred. diff --git a/doc/classes/InputEventMIDI.xml b/doc/classes/InputEventMIDI.xml index 8e2ad5280184..0f0b75665127 100644 --- a/doc/classes/InputEventMIDI.xml +++ b/doc/classes/InputEventMIDI.xml @@ -1,12 +1,12 @@ - Represents an input event from a MIDI device, such as a piano. + Represents a MIDI message from a MIDI device, such as a musical keyboard. - InputEventMIDI allows receiving input events from MIDI (Musical Instrument Digital Interface) devices such as a piano. - MIDI signals can be sent over a 5-pin MIDI connector or over USB, if your device supports both be sure to check the settings in the device to see which output it's using. - To receive input events from MIDI devices, you need to call [method OS.open_midi_inputs]. You can check which devices are detected using [method OS.get_connected_midi_inputs]. + InputEventMIDI stores information about messages from [url=https://en.wikipedia.org/wiki/MIDI]MIDI[/url] (Musical Instrument Digital Interface) devices. These may include musical keyboards, synthesizers, and drum machines. + MIDI messages can be received over a 5-pin MIDI connector or over USB. If your device supports both be sure to check the settings in the device to see which output it is using. + By default, Godot does not detect MIDI devices. You need to call [method OS.open_midi_inputs], first. You can check which devices are detected with [method OS.get_connected_midi_inputs], and close the connection with [method OS.close_midi_inputs]. [codeblocks] [gdscript] func _ready(): @@ -17,16 +17,16 @@ if input_event is InputEventMIDI: _print_midi_info(input_event) - func _print_midi_info(midi_event: InputEventMIDI): + func _print_midi_info(midi_event): print(midi_event) - print("Channel " + str(midi_event.channel)) - print("Message " + str(midi_event.message)) - print("Pitch " + str(midi_event.pitch)) - print("Velocity " + str(midi_event.velocity)) - print("Instrument " + str(midi_event.instrument)) - print("Pressure " + str(midi_event.pressure)) - print("Controller number: " + str(midi_event.controller_number)) - print("Controller value: " + str(midi_event.controller_value)) + print("Channel ", midi_event.channel) + print("Message ", midi_event.message) + print("Pitch ", midi_event.pitch) + print("Velocity ", midi_event.velocity) + print("Instrument ", midi_event.instrument) + print("Pressure ", midi_event.pressure) + print("Controller number: ", midi_event.controller_number) + print("Controller value: ", midi_event.controller_value) [/gdscript] [csharp] public override void _Ready() @@ -35,9 +35,9 @@ GD.Print(OS.GetConnectedMidiInputs()); } - public override void _Input(InputEvent @event) + public override void _Input(InputEvent inputEvent) { - if (@event is InputEventMIDI midiEvent) + if (inputEvent is InputEventMIDI midiEvent) { PrintMIDIInfo(midiEvent); } @@ -57,7 +57,7 @@ } [/csharp] [/codeblocks] - Note that Godot does not currently support MIDI output, so there is no way to emit MIDI signals from Godot. Only MIDI input works. + [b]Note:[/b] Godot does not support MIDI output, so there is no way to emit MIDI messages from Godot. Only MIDI input is supported. https://www.midi.org/specifications-old/item/table-2-expanded-messages-list-status-bytes @@ -66,33 +66,39 @@ - The MIDI channel of this input event. There are 16 channels, so this value ranges from 0 to 15. MIDI channel 9 is reserved for the use with percussion instruments, the rest of the channels are for non-percussion instruments. + The MIDI channel of this message, ranging from [code]0[/code] to [code]15[/code]. MIDI channel [code]9[/code] is reserved for percussion instruments. - If the message is [constant MIDI_MESSAGE_CONTROL_CHANGE], this indicates the controller number, otherwise this is zero. Controllers include devices such as pedals and levers. + The unique number of the controller, if [member message] is [constant MIDI_MESSAGE_CONTROL_CHANGE], otherwise this is [code]0[/code]. This value can be used to identify sliders for volume, balance, and panning, as well as switches and pedals on the MIDI device. See the [url=https://en.wikipedia.org/wiki/General_MIDI#Controller_events]General MIDI specification[/url] for a small list. - If the message is [constant MIDI_MESSAGE_CONTROL_CHANGE], this indicates the controller value, otherwise this is zero. Controllers include devices such as pedals and levers. + The value applied to the controller. If [member message] is [constant MIDI_MESSAGE_CONTROL_CHANGE], this value ranges from [code]0[/code] to [code]127[/code], otherwise it is [code]0[/code]. See also [member controller_value]. - The instrument of this input event. This value ranges from 0 to 127. Refer to the instrument list for [url=https://en.wikipedia.org/wiki/General_MIDI#Program_change_events]General MIDI[/url] to see a list of instruments, except that this value is 0-index, so subtract one from every number on that chart. A standard piano will have an instrument number of 0. + The instrument (also called [i]program[/i] or [i]preset[/i]) used on this MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. + To see what each value means, refer to the [url=https://en.wikipedia.org/wiki/General_MIDI#Program_change_events]General MIDI's instrument list[/url]. Keep in mind that the list is off by 1 because it does not begin from 0. A value of [code]0[/code] corresponds to the acoustic grand piano. - Returns a value indicating the type of message for this MIDI signal. This is a member of the [enum MIDIMessage] enum. - For MIDI messages between 0x80 and 0xEF, only the left half of the bits are returned as this value, as the other part is the channel (ex: 0x94 becomes 0x9). For MIDI messages from 0xF0 to 0xFF, the value is returned as-is. - Notes will return [constant MIDI_MESSAGE_NOTE_ON] when activated, but they might not always return [constant MIDI_MESSAGE_NOTE_OFF] when deactivated, therefore your code should treat the input as stopped if some period of time has passed. - Some MIDI devices may send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead of [constant MIDI_MESSAGE_NOTE_OFF]. - For more information, see the note in [member velocity] and the MIDI message status byte list chart linked above. + Represents the type of MIDI message (see the [enum MIDIMessage] enum). + For more information, see the [url=https://www.midi.org/specifications-old/item/table-2-expanded-messages-list-status-bytes]MIDI message status byte list chart[/url]. - The pitch index number of this MIDI signal. This value ranges from 0 to 127. On a piano, middle C is 60, and A440 is 69, see the "MIDI note" column of the piano key frequency chart on Wikipedia for more information. + The pitch index number of this MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. + On a piano, the [b]middle C[/b] is [code]60[/code], followed by a [b]C-sharp[/b] ([code]61[/code]), then a [b]D[/b] ([code]62[/code]), and so on. Each octave is split in offsets of 12. See the "MIDI note number" column of the [url=https://en.wikipedia.org/wiki/Piano_key_frequencies]piano key frequency chart[/url] a full list. - The pressure of the MIDI signal. This value ranges from 0 to 127. For many devices, this value is always zero. + The strength of the key being pressed. This value ranges from [code]0[/code] to [code]127[/code]. + [b]Note:[/b] For many devices, this value is always [code]0[/code]. Other devices such as musical keyboards may simulate pressure by changing the [member velocity], instead. - The velocity of the MIDI signal. This value ranges from 0 to 127. For a piano, this corresponds to how quickly the key was pressed, and is rarely above about 110 in practice. - [b]Note:[/b] Some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with zero velocity and expect this to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message, but device implementations vary so Godot reports event data exactly as received. Depending on the hardware and the needs of the game/app, this MIDI quirk can be handled robustly with a couple lines of script (check for [constant MIDI_MESSAGE_NOTE_ON] with velocity zero). + The velocity of the MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. For a musical keyboard, this corresponds to how quickly the key was pressed, and is rarely above [code]110[/code] in practice. + [b]Note:[/b] Some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with [code]0[/code] velocity and expect it to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message. If necessary, this can be handled with a few lines of code: + [codeblock] + func _input(event): + if event is InputEventMIDI: + if event.message == MIDI_MESSAGE_NOTE_ON and event.velocity > 0: + print("Note pressed!") + [/codeblock]