Module: AMS::MIDI

Defined in:
Documentation/ams/midi.rb

Overview

Note:

All methods below were made compatible with Mac OS X since 3.4.0 unless otherwise stated.

This namespace contains functions associated with the MIDI output interface.

Since:

  • 2.0.0

Class Method Summary collapse

Class Method Details

.change_channel_controller(channel, cnum, cval) ⇒ Boolean

Set note controller.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • cnum (Fixnum)

    Controller number, a value between 0 and 127.

  • cval (Fixnum)

    Controller value, a value between 0 and 127.

Returns:

  • (Boolean)

    success

See Also:

Since:

  • 2.0.0


158
159
# File 'Documentation/ams/midi.rb', line 158

def change_channel_controller(channel, cnum, cval)
end

.change_channel_expression(channel, expression) ⇒ Boolean

Set channel expression. This is used for dynamics within a single track.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • expression (Fixnum)

    A value between 0 and 127.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


180
181
# File 'Documentation/ams/midi.rb', line 180

def change_channel_expression(channel, expression)
end

.change_channel_instrument(channel, instrument) ⇒ Boolean

Change channel program.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • instrument (Fixnum)

    A value between 0 and 127.

Returns:

  • (Boolean)

    success

Since:

  • 3.3.0


203
204
# File 'Documentation/ams/midi.rb', line 203

def change_channel_instrument(channel, instrument)
end

.change_channel_position(channel, pos, max_hearing_range) ⇒ Boolean

Note:

Same as set_note_position but takes channel instead of id as parameter.

Set channel position in 3d space.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • pos (Geom::Point3d, Array<Numeric>)

    MIDI note position in global space.

  • max_hearing_range (Numeric)

    MIDI note maximum hearing range in meters.

Returns:

  • (Boolean)

    success

Since:

  • 3.3.0


239
240
# File 'Documentation/ams/midi.rb', line 239

def change_channel_position(channel, pos, max_hearing_range)
end

.change_channel_stereo_pan(channel, pan) ⇒ Boolean

Distribute channel volume between left and right speakers.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • pan (Fixnum)

    A value between 0 and 127. 0 is far left, 64 is center, and 127 is far right.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


173
174
# File 'Documentation/ams/midi.rb', line 173

def change_channel_stereo_pan(channel, pan)
end

.change_channel_volume(channel, volume) ⇒ Boolean

Set channel volume.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • volume (Fixnum)

    A value between 0 (soft) and 127 (loud).

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


165
166
# File 'Documentation/ams/midi.rb', line 165

def change_channel_volume(channel, volume)
end

.close_deviceBoolean

Close MIDI device.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


27
28
# File 'Documentation/ams/midi.rb', line 27

def close_device
end

.get_device_handleFixnum?

Get handle to an open MIDI device.

Returns:

  • (Fixnum, nil)

Since:

  • 3.0.0


11
12
# File 'Documentation/ams/midi.rb', line 11

def get_device_handle
end

.get_volumeArray<Numeric>?

Note:

Doesn't work on Mac OS X; return [1.0, 1.0]

Get volume of both channels.

Returns:

  • (Array<Numeric>, nil)

    [left, right] Each value is between 0.00 and 1.00. This function returns nil if MIDI device is invalid or not open.

Since:

  • 2.0.0


50
51
# File 'Documentation/ams/midi.rb', line 50

def get_volume
end

.is_device_open?Boolean

Determine whether the device is open.

Returns:

  • (Boolean)

Since:

  • 3.4.0


17
18
# File 'Documentation/ams/midi.rb', line 17

def is_device_open?
end

.open_deviceBoolean

Open MIDI device.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


22
23
# File 'Documentation/ams/midi.rb', line 22

def open_device
end

.out_message(arg0, arg1, arg2) ⇒ Boolean .out_message(arg0, arg1) ⇒ Boolean .out_message(arg0) ⇒ Boolean

Send MIDI message.

Overloads:

  • .out_message(arg0, arg1, arg2) ⇒ Boolean

    Parameters:

    • arg0 (Fixnum)

      A value between 0 and 127.

    • arg1 (Fixnum)

      A value between 0 and 127.

    • arg2 (Fixnum)

      A value between 0 and 127.

  • .out_message(arg0, arg1) ⇒ Boolean

    Parameters:

    • arg0 (Fixnum)

      A value between 0 and 127.

    • arg1 (Fixnum)

      A value between 0 and 127.

  • .out_message(arg0) ⇒ Boolean

    Parameters:

    • arg0 (Fixnum)

      A value between 0 and 127.

Returns:

  • (Boolean)

    success

Since:

  • 3.4.0


42
43
# File 'Documentation/ams/midi.rb', line 42

def out_message(*args)
end

.play_note(instrument, note, channel = 0, volume = 127) ⇒ Fixnum?

Note:

Setting channel to 9 will play midi notes from the “General MIDI Percussion Key Map.” Any other channel will play midi notes from the “General MIDI Instrument Patch Map”. If channel is set to 9, the instrument parameter will have no effect and the note parameter will be used to play particular percussion sound, if note's value is between 27 and 87. According to my experiments, values outside that 27-87 range won't yield any sounds.

Note:

Some instruments have notes that never seem to end. For this reason it might come in handy to use stop_note function when needed.

Play MIDI note.

Parameters:

  • instrument (Fixnum)

    A value between 0 and 127. See link below for supported instruments and their identifiers.

  • note (Fixnum)

    A value between 0 and 127. Each instrument has a maximum of 128 notes.

  • channel (Fixnum) (defaults to: 0)

    A value between 0 and 15. Each note has a maximum of 16 channels. To play multiple sounds of same type at the same time, change channel value to an unused one. Remember that channel 9 is subjected to different instrument patch and it will change the behaviour of this function; see note above.

  • volume (Fixnum) (defaults to: 127)

    A value between 0 and 127. 0 means quiet/far and 127 means close/loud.

Returns:

  • (Fixnum, nil)

    Midi note ID or nil if MIDI interface failed to play the note.

See Also:

Since:

  • 3.0.0


95
96
# File 'Documentation/ams/midi.rb', line 95

def play_note(instrument, note, channel = 0, volume = 127)
end

.play_note2(channel, note, volume) ⇒ Boolean

Turn on MIDI note.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • note (Fixnum)

    A value between 0 and 127. Each instrument has a maximum of 128 notes.

  • volume (Fixnum)

    A value between 0 (soft) and 127 (loud).

Returns:

  • (Boolean)

    success

Since:

  • 3.3.0


213
214
# File 'Documentation/ams/midi.rb', line 213

def play_note2(channel, note, volume)
end

.resetBoolean

Stop all playing notes.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


67
68
# File 'Documentation/ams/midi.rb', line 67

def reset
end

.reset_channel_controllers(channel) ⇒ Boolean

Reset channel controllers.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0


195
196
# File 'Documentation/ams/midi.rb', line 195

def reset_channel_controllers(channel)
end

.set_note_position(id, pos, max_hearing_range) ⇒ Boolean

Note:

Sound volume and panning is not adjusted automatically with respect to camera orientation. It is required to manually call this function every frame until the note is stopped or has finished playing. Sometimes it's just enough to call this function once after playing the note. Other times, when the note is endless or pretty long, it might be useful to update position of the note every frame until the note ends or is stopped. Meantime, there is no function to determine when the note ends. It is up to the user to decide for how long to call this function or when to stop calling this function.

Note:

When it comes to setting 3D positions of multiple sounds, make sure to play each sound on separate channel. That is, play sound 1 on channel 0, sound 2 on channel 1, sound 3 on channel 2, and etcetera until channel gets to 15, as there are only 15 channels available. Read the note below to find out why each sound is supposed to be played on separate channel. I think it would make more sense if the function was renamed to set_channel_position and had the 'id' parameter replaced with 'channel'.

Note:

This function works by adjusting panning and volume of the note's and instrument's channel, based on camera's angle and distance to the origin of the sound. Now, there is only one function that adjusts stereo and panning, but it adjusts panning and volume of all notes and instruments that are played on same channel. As of my research, I haven't found a way to adjust panning and volume of channel that belongs to particular note and instrument. There's only a function that can adjust panning and volume of channel that belongs to all notes and instruments that are played on particular channel. For instance, if you play instrument 1 and instrument 2, both on channel zero, they will still play simultaneously, without cancelling out each other, as if they are playing on separate channels, but when it comes to adjusting panning and volume of one of them, the properties of both sounds will be adjusted. This means that this function is only limited to playing 16 3D sounds, with each sound played on different channel. Otherwise, sounds played on same channel at different locations, will endup being tuned as if they are playing from the same location.

Set MIDI note position in 3D space.

Parameters:

  • id (Fixnum)

    A MIDI note identifier returned by the play_note function.

  • pos (Geom::Point3d, Array<Numeric>)

    MIDI note position in global space.

  • max_hearing_range (Numeric)

    MIDI note maximum hearing range in meters.

Returns:

  • (Boolean)

    success

Since:

  • 3.0.0


149
150
# File 'Documentation/ams/midi.rb', line 149

def set_note_position(id, pos, max_hearing_range)
end

.set_volume(left, right) ⇒ Boolean .set_volume(volume) ⇒ Boolean

Overloads:

  • .set_volume(left, right) ⇒ Boolean

    Set volume of each channel.

    Parameters:

    • left (Numeric)

      This value is clamped between 0.0 and 1.0.

    • right (Numeric)

      This value is clamped between 0.0 and 1.0.

    Returns:

    • (Boolean)

      success

  • .set_volume(volume) ⇒ Boolean

    Apply same volume to both channels.

    Parameters:

    • volume (Numeric)

      This value is clamped between 0.0 and 1.0.

    Returns:

    • (Boolean)

      success

Since:

  • 2.0.0


62
63
# File 'Documentation/ams/midi.rb', line 62

def set_volume(*args)
end

.stop_note(id) ⇒ Boolean

Stop MIDI note.

Parameters:

  • id (Fixnum)

    A MIDI note identifier returned by the play_note function. Pass -1 to stop all midi notes.

Returns:

  • (Boolean)

    success

Since:

  • 3.0.0


103
104
# File 'Documentation/ams/midi.rb', line 103

def stop_note(id)
end

.stop_note2(channel, note, volume) ⇒ Boolean

Note:

The volume parameter isn't logically necessary to stop a note, but it could be used to fade out the note. Pass zero to stop the note immediately.

Turn off MIDI note.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • note (Fixnum)

    A value between 0 and 127. Each instrument has a maximum of 128 notes.

  • volume (Fixnum)

    A value between 0 (soft) and 127 (loud).

Returns:

  • (Boolean)

    success

Since:

  • 3.3.0


226
227
# File 'Documentation/ams/midi.rb', line 226

def stop_note2(channel, note, volume)
end

.sustain_channel_pedal(channel, state) ⇒ Boolean

Note:

Message must be sent prior to the note it affects.

Control channel pedal.

Parameters:

  • channel (Fixnum)

    A value between 0 and 15.

  • state (Boolean)

    true for pedal down; false for pedal up.

Returns:

  • (Boolean)

    success

Since:

  • 3.0.0


189
190
# File 'Documentation/ams/midi.rb', line 189

def sustain_channel_pedal(channel, state)
end