Module: AMS::MIDI

Defined in:
docs/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 (Integer) —

    A value between 0 and 15.

  • cnum (Integer) —

    Controller number, a value between 0 and 127.

  • cval (Integer) —

    Controller value, a value between 0 and 127.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.change_channel_expression(channel, expression) ⇒ Boolean

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

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • expression (Integer) —

    A value between 0 and 127.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.change_channel_instrument(channel, instrument) ⇒ Boolean

Change channel program.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • instrument (Integer) —

    A value between 0 and 127.

Returns:

  • (Boolean) —

    success

Since:

  • 3.3.0

.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 (Integer) —

    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

.change_channel_stereo_pan(channel, pan) ⇒ Boolean

Distribute channel volume between left and right speakers.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • pan (Integer) —

    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

.change_channel_volume(channel, volume) ⇒ Boolean

Set channel volume.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • volume (Integer) —

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

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.close_device ⇒ Boolean

Close MIDI device.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.get_device_handle ⇒ Integer?

Get handle to an open MIDI device.

Returns:

  • (Integer, nil)

Since:

  • 3.0.0

.get_volume ⇒ Array<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

.is_device_open? ⇒ Boolean

Determine whether the device is open.

Returns:

  • (Boolean)

Since:

  • 3.4.0

.open_device ⇒ Boolean

Open MIDI device.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.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 (Integer) —

      A value between 0 and 127.

    • arg1 (Integer) —

      A value between 0 and 127.

    • arg2 (Integer) —

      A value between 0 and 127.

  • .out_message(arg0, arg1) ⇒ Boolean

    Parameters:

    • arg0 (Integer) —

      A value between 0 and 127.

    • arg1 (Integer) —

      A value between 0 and 127.

  • .out_message(arg0) ⇒ Boolean

    Parameters:

    • arg0 (Integer) —

      A value between 0 and 127.

Returns:

  • (Boolean) —

    success

Since:

  • 3.4.0

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

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 (Integer) —

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

  • note (Integer) —

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

  • channel (Integer) (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 (Integer) (defaults to: 127) —

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

Returns:

  • (Integer, nil) —

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

See Also:

Since:

  • 3.0.0

.play_note2(channel, note, volume) ⇒ Boolean

Turn on MIDI note.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • note (Integer) —

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

  • volume (Integer) —

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

Returns:

  • (Boolean) —

    success

Since:

  • 3.3.0

.reset ⇒ Boolean

Stop all playing notes.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.reset_channel_controllers(channel) ⇒ Boolean

Reset channel controllers.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.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 (Integer) —

    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

.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

.stop_note(id) ⇒ Boolean

Stop MIDI note.

Parameters:

  • id (Integer) —

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

Returns:

  • (Boolean) —

    success

Since:

  • 3.0.0

.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 (Integer) —

    A value between 0 and 15.

  • note (Integer) —

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

  • volume (Integer) —

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

Returns:

  • (Boolean) —

    success

Since:

  • 3.3.0

.sustain_channel_pedal(channel, state) ⇒ Boolean

Note:

Message must be sent prior to the note it affects.

Control channel pedal.

Parameters:

  • channel (Integer) —

    A value between 0 and 15.

  • state (Boolean) —

    true for pedal down; false for pedal up.

Returns:

  • (Boolean) —

    success

Since:

  • 3.0.0