Class: MIDICommunicationsMacOS::Source

Inherits:
Object
  • Object
show all
Includes:
Endpoint
Defined in:
lib/midi-communications-macos/source.rb

Overview

MIDI input endpoint for receiving MIDI messages.

A Source represents a MIDI input that can receive messages from external MIDI devices or software. Messages are queued and can be retrieved using #gets or #gets_s.

Examples:

Open and read from the first input

input = MIDICommunicationsMacOS::Source.first
input.open
messages = input.gets
# => [{ data: [144, 60, 100], timestamp: 1234567890.123 }]

Read messages as hex strings

messages = input.gets_s
# => [{ data: "903C64", timestamp: 1234567890.123 }]

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#enabled ⇒ Boolean (readonly) Also known as: enabled? Originally defined in module Endpoint

Returns whether the endpoint has been initialized.

Returns:

  • (Boolean) —

    whether the endpoint has been initialized

#entity ⇒ Entity (readonly) Originally defined in module Endpoint

Returns the parent entity.

Returns:

  • (Entity) —

    the parent entity

#id ⇒ Integer Originally defined in module Endpoint

Returns unique local numeric ID of the endpoint.

Returns:

  • (Integer) —

    unique local numeric ID of the endpoint

#resource_id ⇒ Integer (readonly) Originally defined in module Endpoint

Returns Core MIDI resource identifier.

Returns:

  • (Integer) —

    Core MIDI resource identifier

#type ⇒ Object (readonly) Originally defined in module Endpoint

Class Method Details

.all ⇒ Array<Source>

Returns all available input endpoints.

Examples:

inputs = MIDICommunicationsMacOS::Source.all
inputs.each { |i| puts i.display_name }

Returns:

  • (Array<Source>) —

    all sources



150
151
152
 
# File 'lib/midi-communications-macos/source.rb', line 150

def self.all
  Endpoint.all_by_type[:source]
end

.first ⇒ Source

Returns the first available input endpoint.

Examples:

input = MIDICommunicationsMacOS::Source.first

Returns:

  • (Source) —

    the first source



132
133
134
 
# File 'lib/midi-communications-macos/source.rb', line 132

def self.first
  Endpoint.first(:source)
end

.last ⇒ Source

Returns the last available input endpoint.

Returns:

  • (Source) —

    the last source



139
140
141
 
# File 'lib/midi-communications-macos/source.rb', line 139

def self.last
  Endpoint.last(:source)
end

Instance Method Details

#close ⇒ Boolean

Closes this input.

Returns:

  • (Boolean) —

    true if closed, false if already closed



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/midi-communications-macos/source.rb', line 109

def close
  #error = API.MIDIPortDisconnectSource( @handle, @resource )
  #raise "MIDIPortDisconnectSource returned error code #{error}" unless error.zero?
  #error = API.MIDIClientDispose(@handle)
  #raise "MIDIClientDispose returned error code #{error}" unless error.zero?
  #error = API.MIDIPortDispose(@handle)
  #raise "MIDIPortDispose returned error code #{error}" unless error.zero?
  #error = API.MIDIEndpointDispose(@resource)
  #raise "MIDIEndpointDispose returned error code #{error}" unless error.zero?
  if @enabled
    @enabled = false
    true
  else
    false
  end
end

#display_name ⇒ String Originally defined in module Endpoint

Returns formatted display name (delegated to entity).

Returns:

  • (String) —

    formatted display name (delegated to entity)

#enable {|source| ... } ⇒ Source Also known as: open, start

Opens this input for use.

When a block is given, the input is automatically closed when the block exits.

Examples:

Open with automatic close

input.open do |i|
  messages = i.gets
end

Open manually

input.open
messages = input.gets

Yields:

  • (source) —

    optional block to execute with the open input

Yield Parameters:

Returns:



92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/midi-communications-macos/source.rb', line 92

def enable
  @enabled ||= true
  if block_given?
    begin
      yield(self)
    ensure
      close
    end
  end
  self
end

#gets ⇒ Array<Hash> Also known as: read

Reads MIDI messages from the input buffer.

Returns an array of MIDI event hashes. Each hash contains:

  • :data - Array of numeric bytes (e.g., [144, 60, 100])
  • :timestamp - Float timestamp when the message was received

This method blocks until at least one message is available.

An array of MIDI event hashes as such: [ { data: [144, 60, 100], timestamp: 1024 }, { data: [128, 60, 100], timestamp: 1100 }, { data: [144, 40, 120], timestamp: 1200 } ]

The data is an array of Numeric bytes The timestamp is the number of millis since this input was enabled

Examples:

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

Returns:

  • (Array<Hash>) —

    array of MIDI event hashes

  • (Array<Hash>) 


50
51
52
 
# File 'lib/midi-communications-macos/source.rb', line 50

def gets
  get_queue_new_messages
end

#gets_s ⇒ Array<Hash> Also known as: gets_bytestr

Reads MIDI messages as hex strings.

Same as #gets but returns message data as hex strings instead of byte arrays.

Examples:

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

Returns:

  • (Array<Hash>) —

    array of MIDI event hashes with hex string data



66
67
68
69
70
71
72
 
# File 'lib/midi-communications-macos/source.rb', line 66

def gets_s
  messages = gets
  messages.each do |message|
    message[:data] = TypeConversion.numeric_bytes_to_hex_string(message[:data])
  end
  messages
end

#initialize(resource_id, entity) ⇒ Object Originally defined in module Endpoint

Parameters:

  • resource_id (Integer)
  • entity (Entity)

#manufacturer ⇒ String Originally defined in module Endpoint

Returns device manufacturer name (delegated to entity).

Returns:

  • (String) —

    device manufacturer name (delegated to entity)

#model ⇒ String Originally defined in module Endpoint

Returns device model name (delegated to entity).

Returns:

  • (String) —

    device model name (delegated to entity)

#name ⇒ String Originally defined in module Endpoint

Returns endpoint name (delegated to entity).

Returns:

  • (String) —

    endpoint name (delegated to entity)

#online? ⇒ Boolean Originally defined in module Endpoint

Is this endpoint online?

Returns:

  • (Boolean)