Class: MIDICommunications::Input

Inherits:
Object
  • Object
show all
Extended by:
Device::ClassMethods
Includes:
Device::InstanceMethods, StreamReader
Defined in:
lib/midi-communications/input.rb,
lib/midi-communications/input/stream_reader.rb

Overview

A MIDI input device for receiving MIDI messages.

Input devices receive MIDI data from external controllers, instruments, or other MIDI sources. Use the class methods to discover and select available input devices.

Examples:

List available inputs

MIDICommunications::Input.list

Open the first input and read messages

input = MIDICommunications::Input.first
messages = input.gets
# => [{ data: [144, 60, 100], timestamp: 1024 }]

Interactive selection

input = MIDICommunications::Input.gets

Find by name

input = MIDICommunications::Input.find_by_name("USB MIDI Device")
input.open

See Also:

Defined Under Namespace

Modules: StreamReader

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#direction ⇒ Symbol (readonly) Originally defined in module Device::InstanceMethods

Returns the device direction (:input or :output).

Returns:

  • (Symbol) —

    the device direction (:input or :output)

#display_name ⇒ String (readonly) Originally defined in module Device::InstanceMethods

Returns the device display name.

Returns:

  • (String) —

    the device display name

#enabled ⇒ Boolean (readonly) Originally defined in module Device::InstanceMethods

Returns whether the device is currently open.

Returns:

  • (Boolean) —

    whether the device is currently open

#id ⇒ Integer (readonly) Originally defined in module Device::InstanceMethods

Returns the device ID.

Returns:

  • (Integer) —

    the device ID

#manufacturer ⇒ String (readonly) Originally defined in module Device::InstanceMethods

Returns the device manufacturer name.

Returns:

  • (String) —

    the device manufacturer name

#model ⇒ String (readonly) Originally defined in module Device::InstanceMethods

Returns the device model name.

Returns:

  • (String) —

    the device model name

#name ⇒ String (readonly) Originally defined in module Device::InstanceMethods

Returns the device name.

Returns:

  • (String) —

    the device name

Class Method Details

.all ⇒ Array<Input>

Returns all available MIDI input devices.

Examples:

inputs = MIDICommunications::Input.all
inputs.each { |i| puts i.name }

Returns:

  • (Array<Input>) —

    array of input devices



41
42
43
 
# File 'lib/midi-communications/input.rb', line 41

def self.all
  Loader.devices(direction: :input)
end

.at(index) ⇒ Input, Output Also known as: [] Originally defined in module Device::ClassMethods

Returns the device at the given index without opening it.

Examples:

device = MIDICommunications::Output.at(0)
device.open if device

Parameters:

  • index (Integer) —

    device index

Returns:

.each {|device| ... } ⇒ Enumerator Originally defined in module Device::ClassMethods

Iterates over all devices of this type.

Examples:

MIDICommunications::Output.each { |o| puts o.name }

Yields:

  • (device) —

    each device

Yield Parameters:

Returns:

  • (Enumerator) —

    if no block given

.find_by_name(name) ⇒ Input, ... Originally defined in module Device::ClassMethods

Finds a device by its name.

Examples:

output = MIDICommunications::Output.find_by_name("IAC Driver Bus 1")

Parameters:

  • name (String, Symbol) —

    the device name to search for

Returns:

  • (Input, Output, nil) —

    the matching device or nil if not found

.first {|device| ... } ⇒ Input, Output Originally defined in module Device::ClassMethods

Selects and opens the first available device.

Examples:

output = MIDICommunications::Output.first

Yields:

  • (device) —

    optional block to execute with the device

Yield Parameters:

Returns:

.gets {|device| ... } ⇒ Input, Output Originally defined in module Device::ClassMethods

Interactive console prompt for device selection.

Displays available devices and waits for user input. When a valid selection is received, the device is opened and returned.

Examples:

output = MIDICommunications::Output.gets
# Select a MIDI output...
# 0) IAC Driver Bus 1
# > 0

Yields:

  • (device) —

    optional block to execute with the opened device

Yield Parameters:

Returns:

.last {|device| ... } ⇒ Input, Output Originally defined in module Device::ClassMethods

Selects and opens the last available device.

Examples:

output = MIDICommunications::Output.last

Yields:

  • (device) —

    optional block to execute with the device

Yield Parameters:

Returns:

.list ⇒ Array<String> Originally defined in module Device::ClassMethods

Prints the ID and name of each device to the console.

Examples:

MIDICommunications::Output.list
# 0) IAC Driver Bus 1
# 1) USB MIDI Device

Returns:

  • (Array<String>) —

    array of formatted device names

.use(index) {|device| ... } ⇒ Input, Output Also known as: open Originally defined in module Device::ClassMethods

Selects and opens the device at the given index.

Examples:

output = MIDICommunications::Output.use(0)

Parameters:

  • index (Integer, Symbol) —

    device index or :first/:last

Yields:

  • (device) —

    optional block to execute with the device

Yield Parameters:

Returns:

Instance Method Details

#close(*args) ⇒ Boolean Originally defined in module Device::InstanceMethods

Closes the device.

Examples:

output.close

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Returns:

  • (Boolean) —

    true if the device was closed, false if already closed

#closed? ⇒ Boolean Originally defined in module Device::InstanceMethods

Returns true if the device is closed (not enabled).

Returns:

  • (Boolean) —

    true if device is closed

#enabled? ⇒ Boolean Originally defined in module Device::InstanceMethods

Returns alias for #enabled.

Returns:

#gets(*args) ⇒ Array<Hash> Originally defined in module StreamReader

Reads MIDI messages from the input buffer.

Returns all messages received since the last read. Each message includes the MIDI data and a timestamp.

Examples:

messages = input.gets
# => [{ data: [144, 60, 100], timestamp: 1024 },
#     { data: [128, 60, 100], timestamp: 1100 }]

Process messages in a loop

loop do
  messages = input.gets
  messages.each { |m| puts m[:data].inspect }
  sleep(0.01)
end

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Returns:

  • (Array<Hash>) —

    array of message hashes with :data and :timestamp keys

#gets_data(*args) ⇒ Array<Integer> Originally defined in module StreamReader

Reads MIDI data as a flat array of bytes.

Returns all message data concatenated into a single array, without timestamps.

Examples:

data = input.gets_data
# => [144, 60, 100, 128, 60, 100, 144, 40, 120]

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Returns:

  • (Array<Integer>) —

    flat array of all MIDI bytes

#gets_data_s(*args) ⇒ String Also known as: gets_data_bytestr, gets_data_hex Originally defined in module StreamReader

Reads MIDI data as a concatenated hex string.

Returns all message data concatenated into a single hex string, without timestamps.

Examples:

data = input.gets_data_s
# => "90406080406090447F"

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Returns:

  • (String) —

    concatenated hex string of all MIDI data

#gets_s(*args) ⇒ Array<Hash> Also known as: gets_bytestr, gets_hex Originally defined in module StreamReader

Reads MIDI messages as hex strings.

Similar to #gets but returns data as hex strings instead of byte arrays.

Examples:

messages = input.gets_s
# => [{ data: "904060", timestamp: 904 },
#     { data: "804060", timestamp: 1150 }]

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Returns:

  • (Array<Hash>) —

    array of message hashes with :data (String) and :timestamp keys

#initialize(device) ⇒ Object Originally defined in module Device::InstanceMethods

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new device wrapper.

Parameters:

  • device (Object) —

    platform-specific device object

#open(*args) {|device| ... } ⇒ Input, Output Originally defined in module Device::InstanceMethods

Opens the device for use.

When a block is given, the device is automatically closed when the block exits. Otherwise, the device is closed at program exit.

Examples:

Open and close automatically with block

output.open do |o|
  o.puts(0x90, 60, 100)
end  # device closed here

Open manually (closed at program exit)

output.open
output.puts(0x90, 60, 100)

Parameters:

  • args (Object) —

    arguments passed to the underlying device

Yields:

  • (device) —

    optional block to execute with the open device

Yield Parameters:

Returns:

#type ⇒ Symbol Originally defined in module Device::InstanceMethods

Returns alias for #direction.

Returns: