Class: MIDICommunicationsMacOS::Device

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

Overview

Represents a physical or virtual MIDI device.

A MIDI device may have multiple logically distinct sub-components. For example, one device may encompass a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. Each such element of a device is called an Entity.

Devices contain entities, which in turn contain endpoints (sources and destinations).

Examples:

List all devices

MIDICommunicationsMacOS::Device.all.each do |device|
  puts device.name
end

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, device_pointer, include_offline: false) ⇒ Device

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:

  • id (Integer) —

    the device ID

  • device_pointer (FFI::Pointer) —

    pointer to the Core MIDI device

  • include_offline (Boolean) (defaults to: false) —

    whether to include offline entities



36
37
38
39
40
41
 
# File 'lib/midi-communications-macos/device.rb', line 36

def initialize(id, device_pointer, include_offline: false)
  @id = id
  @resource = device_pointer
  @entities = []
  populate(include_offline: include_offline)
end

Instance Attribute Details

#entities ⇒ Array<Entity> (readonly)

Returns the device's entities.

Returns:

  • (Array<Entity>) —

    the device's entities



26
27
28
 
# File 'lib/midi-communications-macos/device.rb', line 26

def entities
  @entities
end

#id ⇒ Integer (readonly)

Returns unique numeric ID.

Returns:

  • (Integer) —

    unique numeric ID



26
27
28
 
# File 'lib/midi-communications-macos/device.rb', line 26

attr_reader :entities,
:id,
:name

#name ⇒ Object (readonly) 



26
27
28
 
# File 'lib/midi-communications-macos/device.rb', line 26

attr_reader :entities,
:id,
:name

Class Method Details

.all(options = {}) ⇒ Array<Device>

Returns all available MIDI devices.

Devices are cached by default. Use cache: false to refresh, or call refresh to clear the cache.

Examples:

devices = MIDICommunicationsMacOS::Device.all
devices.each { |d| puts d.name }

Parameters:

  • options (Hash) (defaults to: {}) —

    options for device selection

Options Hash (options):

  • :cache (Boolean) — default: true —

    whether to use cached devices

  • :include_offline (Boolean) — default: false —

    include offline devices

Returns:

  • (Array<Device>) —

    all available devices



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/midi-communications-macos/device.rb', line 77

def self.all(options = {})
  use_cache = options[:cache] || true
  include_offline = options[:include_offline] || false
  if !populated? || !use_cache
    @devices = []
    counter = 0
    while !(device_pointer = API.MIDIGetDevice(counter)).null?
      device = new(counter, device_pointer, include_offline: include_offline)
      @devices << device
      counter += 1
    end
    populate_endpoint_ids
  end
  @devices
end

.populated? ⇒ Boolean

Has the device list been populated?

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/midi-communications-macos/device.rb', line 105

def self.populated?
  defined?(@devices) && !@devices.nil? && !@devices.empty?
end

.refresh ⇒ Array<Device>

Clears the device cache.

Call this when MIDI devices are plugged in or unplugged while the program is running, then call all to get the updated list.

Returns:

  • (Array<Device>) —

    the cleared cache (empty array)



99
100
101
102
 
# File 'lib/midi-communications-macos/device.rb', line 99

def self.refresh
  @devices.clear
  @devices
end

Instance Method Details

#endpoints ⇒ Hash{Symbol => Array<Endpoint>}

Returns all endpoints for this device, grouped by type.

Returns:

  • (Hash{Symbol => Array<Endpoint>}) —

    hash with :source and :destination keys



46
47
48
49
50
51
52
53
 
# File 'lib/midi-communications-macos/device.rb', line 46

def endpoints
  endpoints = { source: [], destination: [] }
  endpoints.each_key do |key|
    endpoint_group = entities.map { |entity| entity.endpoints[key] }.flatten
    endpoints[key] += endpoint_group
  end
  endpoints
end

#populate_endpoint_ids(last_id) ⇒ Integer

Assign all of this Device's endpoints an consecutive local id

Parameters:

  • last_id (Integer) —

    The highest already used endpoint ID

Returns:

  • (Integer) —

    The highest used endpoint ID after populating this device's endpoints



58
59
60
61
62
 
# File 'lib/midi-communications-macos/device.rb', line 58

def populate_endpoint_ids(last_id)
  id = 0
  entities.each { |entity| id += entity.populate_endpoint_ids(id + last_id) }
  id
end