midi-communications-macos 0.5.0

data/lib/midi-communications-macos/device.rb

@@ -0,0 +1,110 @@
+module MIDICommunicationsMacOS
+  # 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 a MIDI entity.
+  #
+  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  class Device
+    attr_reader :entities,
+                :id, # Unique Numeric id
+                :name # Device name from midi-communications-macos
+
+    # @param [Integer] id The ID for the device
+    # @param [Object] device_pointer The underlying device pointer
+    # @param [Boolean] include_offline Whether to include offline entities (default: false)
+    def initialize(id, device_pointer, include_offline: false)
+      @id = id
+      @resource = device_pointer
+      @entities = []
+      populate(include_offline: include_offline)
+    end
+
+    # Endpoints for this device
+    # @return [Array<Endpoint>]
+    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
+
+    # Assign all of this Device's endpoints an consecutive local id
+    # @param [Integer] last_id The highest already used endpoint ID
+    # @return [Integer] The highest used endpoint ID after populating this device's endpoints
+    def populate_endpoint_ids(last_id)
+      id = 0
+      entities.each { |entity| id += entity.populate_endpoint_ids(id + last_id) }
+      id
+    end
+
+    # All cached devices
+    # @param [Hash] options The options to select devices with
+    # @option options [Boolean] :cache If false, the device list will never be cached. This would be useful if one needs to alter the device list (e.g. plug in a USB MIDI interface) while their program is running.
+    # @option options [Boolean] :include_offline If true, devices marked offline by midi-communications-macos will be included in the list
+    # @return [Array<Device>] All cached devices
+    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
+
+    # Refresh the Device cache. This is needed if, for example a USB MIDI device is plugged in while the program is running
+    # @return [Array<Device>] The Device cache
+    def self.refresh
+      @devices.clear
+      @devices
+    end
+
+    # Has the device list been populated?
+    def self.populated?
+      defined?(@devices) && !@devices.nil? && !@devices.empty?
+    end
+
+    private
+
+    # Populate the device name
+    def populate_name
+      @name = API.get_string(@resource, 'name')
+      raise "Can't get device name" unless @name
+    end
+
+    # All of the endpoints for all devices a consecutive local id
+    def self.populate_endpoint_ids
+      counter = 0
+      all.each { |device| counter += device.populate_endpoint_ids(counter) }
+      counter
+    end
+
+    # Populates the entities for this device. These entities are in turn used to gather the endpoints.
+    # @param [Hash] options
+    # @option options [Boolean] :include_offline Whether to include offline entities (default: false)
+    # @return [Integer] The number of entities populated
+    def populate_entities(options = {})
+      include_if_offline = options[:include_offline] || false
+      i = 0
+      while !(entity_pointer = API.MIDIDeviceGetEntity(@resource, i)).null?
+        @entities << Entity.new(entity_pointer, include_offline: include_if_offline)
+        i += 1
+      end
+      i
+    end
+
+    # Populate the instance
+    def populate(include_offline:)
+      populate_name
+      populate_entities(include_offline: include_offline)
+    end
+  end
+end

data/lib/midi-communications-macos/endpoint.rb

@@ -0,0 +1,109 @@
+module MIDICommunicationsMacOS
+  # A source or destination of a 16-channel MIDI stream
+  #
+  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  module Endpoint
+    extend Forwardable
+
+    attr_reader :enabled, # has the endpoint been initialized?
+                :entity,
+                :id, # unique local Numeric id of the endpoint
+                :resource_id, # :input or :output
+                :type
+
+    def_delegators :entity, :manufacturer, :model, :name, :display_name
+
+    alias enabled? enabled
+
+    # @param [Integer] resource_id
+    # @param [Entity] entity
+    def initialize(resource_id, entity)
+      @entity = entity
+      @resource_id = resource_id
+      @type = get_type
+      @enabled = false
+
+      @name = nil
+
+      @threads_sync_semaphore = Mutex.new
+      @threads_waiting = []
+    end
+
+    # Is this endpoint online?
+    # @return [Boolean]
+    def online?
+      @entity.online? && connect?
+    end
+
+    # Set the id for this endpoint (the id is immutable)
+    # @param [Integer] id
+    # @return [Integer]
+    def id=(id)
+      @id ||= id
+    end
+
+    # Select the first endpoint of the specified type
+    # @return [Destination, Source]
+    def self.first(type)
+      all_by_type[type].first
+    end
+
+    # Select the last endpoint of the specified type
+    # @return [Destination, Source]
+    def self.last(type)
+      all_by_type[type].last
+    end
+
+    # All source endpoints
+    # @return [Array<Source>]
+    def self.sources
+      Device.all.map { |d| d.endpoints[:source] }.flatten
+    end
+
+    # All destination endpoints
+    # @return [Array<Destination>]
+    def self.destinations
+      Device.all.map { |d| d.endpoints[:destination] }.flatten
+    end
+
+    # A Hash of :source and :destination endpoints
+    # @return [Hash]
+    def self.all_by_type
+      {
+        source: sources,
+        destination: destinations
+      }
+    end
+
+    # All endpoints of both types
+    # @return [Array<Destination, Source>]
+    def self.all
+      Device.all.map(&:endpoints).flatten
+    end
+
+    # Get the class for the given endpoint type name
+    # @param [Symbol] type The endpoint type eg :source, :destination
+    # @return [Class] eg Source, Destination
+    def self.get_class(type)
+      case type
+      when :source then Source
+      when :destination then Destination
+      end
+    end
+
+    protected
+
+    # Constructs the endpoint type (eg source, destination) for easy consumption
+    def get_type
+      class_name = self.class.name.split('::').last
+      class_name.downcase.to_sym
+    end
+
+    # Enables the midi-communications-macos MIDI client that will go with this endpoint
+    def enable_client
+      client = API.create_midi_client(@resource_id, @name)
+      @client = client[:resource]
+      client[:error]
+    end
+  end
+end

data/lib/midi-communications-macos/entity.rb

@@ -0,0 +1,106 @@
+module MIDICommunicationsMacOS
+  # A MIDI entity can have any number of MIDI endpoints, each of which is a source or destination
+  # of a 16-channel MIDI stream. By grouping a device's endpoints into entities, the system has
+  # enough information for an application to make reasonable default assumptions about how to
+  # communicate in a bi-directional manner with each entity, as is necessary in MIDI librarian
+  # applications.
+  #
+  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  class Entity
+    attr_reader :endpoints,
+                :manufacturer,
+                :model,
+                :name,
+                :resource
+
+    # @param [FFI::Pointer] resource A pointer to the underlying entity
+    # @param [Boolean] include_offline Include offline endpoints in the list
+    def initialize(resource, include_offline: false)
+      @endpoints = {
+        source: [],
+        destination: []
+      }
+      @resource = resource
+      populate(include_offline: include_offline)
+    end
+
+    # Assign all of this Entity's endpoints an consecutive local id
+    # @param [Integer] starting_id
+    # @return [Integer]
+    def populate_endpoint_ids(starting_id)
+      counter = 0
+      @endpoints.values.flatten.each do |endpoint|
+        endpoint.id = counter + starting_id
+        counter += 1
+      end
+      counter
+    end
+
+    # Is the entity online?
+    # @return [Boolean]
+    def online?
+      get_int(:offline).zero?
+    end
+
+    # Construct a display name for the entity
+    # @return [String]
+    def display_name
+      "#{@manufacturer} #{@model} (#{@name})"
+    end
+
+    private
+
+    # Populate endpoints of a specified type for this entity
+    # @param [Symbol] type The endpoint type eg :source, :destination
+    # @param [Boolean] include_offline Include offline endpoints in the list
+    # @return [Integer]
+    def populate_endpoints_by_type(type, include_offline:)
+      endpoint_class = Endpoint.get_class(type)
+      num_endpoints = number_of_endpoints(type)
+      (0..num_endpoints).each do |i|
+        endpoint = endpoint_class.new(i, self)
+        @endpoints[type] << endpoint if endpoint.online? || include_offline
+      end
+      @endpoints[type].size
+    end
+
+    # Populate the endpoints for this entity
+    # @param [Boolean] include_offline Include offline endpoints in the list
+    # @return [Integer]
+    def populate_endpoints(include_offline:)
+      @endpoints.keys.map { |type| populate_endpoints_by_type(type, include_offline: include_offline) }.reduce(&:+)
+    end
+
+    # The number of endpoints for this entity
+    # @param [Symbol] type The endpoint type eg :source, :destination
+    def number_of_endpoints(type)
+      case type
+      when :source then API.MIDIEntityGetNumberOfSources(@resource)
+      when :destination then API.MIDIEntityGetNumberOfDestinations(@resource)
+      end
+    end
+
+    # A CFString property from the underlying entity
+    # @param [Symbol, String] name The property name
+    # @return [String, nil]
+    def get_string(name)
+      API.get_string(@resource, name)
+    end
+
+    # An Integer property from the underlying entity
+    # @param [Symbol, String] name The property name
+    # @return [Integer, nil]
+    def get_int(name)
+      API.get_int(@resource, name)
+    end
+
+    # Populate the entity properties from the underlying resource
+    # @param [Boolean] include_offline Include offline endpoints in the list
+    def populate(include_offline:)
+      @manufacturer = get_string(:manufacturer)
+      @model = get_string(:model)
+      @name = get_string(:name)
+      populate_endpoints(include_offline: include_offline)
+    end
+  end
+end

data/lib/midi-communications-macos/source.rb

@@ -0,0 +1,234 @@
+module MIDICommunicationsMacOS
+  # Type of endpoint used for input
+  class Source
+    include Endpoint
+
+    #
+    # 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
+    #
+    # @return [Array<Hash>]
+    def gets
+      get_queue_new_messages
+    end
+    alias read gets
+
+    # Same as Source#gets except that it returns message data as string of hex
+    # digits as such:
+    #   [
+    #     { data: "904060", timestamp: 904 },
+    #     { data: "804060", timestamp: 1150 },
+    #     { data: "90447F", timestamp: 1300 }
+    #   ]
+    #
+    # @return [Array<Hash>]
+    def gets_s
+      messages = gets
+      messages.each do |message|
+        message[:data] = TypeConversion.numeric_bytes_to_hex_string(message[:data])
+      end
+      messages
+    end
+    alias gets_bytestr gets_s
+
+    # Enable this the input for use; can be passed a block
+    # @return [Source]
+    def enable
+      @enabled ||= true
+      if block_given?
+        begin
+          yield(self)
+        ensure
+          close
+        end
+      end
+      self
+    end
+    alias open enable
+    alias start enable
+
+    # Close this input
+    # @return [Boolean]
+    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
+
+    # Shortcut to the first available input endpoint
+    # @return [Source]
+    def self.first
+      Endpoint.first(:source)
+    end
+
+    # Shortcut to the last available input endpoint
+    # @return [Source]
+    def self.last
+      Endpoint.last(:source)
+    end
+
+    # All input endpoints
+    # @return [Array<Source>]
+    def self.all
+      Endpoint.all_by_type[:source]
+    end
+
+    protected
+
+    # Gets new received messages from the callback queue
+    def get_queue_new_messages
+      messages = []
+
+      if @queue.empty?
+        @threads_sync_semaphore.synchronize do
+          @threads_waiting << Thread.current
+        end
+        sleep
+      end
+
+      messages << @queue.pop until @queue.empty?
+
+      messages
+    end
+
+    # Base initialization for this endpoint -- done whether or not the endpoint is enabled to check whether
+    # it is truly available for use
+    def connect
+      enable_client
+      initialize_port
+      @resource = API.MIDIEntityGetSource(@entity.resource, @resource_id)
+      error = API.MIDIPortConnectSource(@handle, @resource, nil)
+
+      @queue = Queue.new
+      @sysex_buffer = []
+
+      error.zero?
+    end
+    alias connect? connect
+
+    private
+
+    # Add a single message to the callback queue
+    # @param [Array<Fixnum>] bytes Message data
+    # @param [Float] timestamp The system float timestamp
+    # @return [Array<Hash>] The resulting buffer
+    def enqueue_message(bytes, timestamp)
+      if bytes.first.eql?(0xF0) || !@sysex_buffer.empty?
+        @sysex_buffer += bytes
+        if bytes.last.eql?(0xF7)
+          bytes = @sysex_buffer.dup
+          @sysex_buffer.clear
+        end
+      end
+      message = get_message_formatted(bytes, timestamp)
+      @queue << message
+
+      @threads_sync_semaphore.synchronize do
+        @threads_waiting.each(&:run)
+        @threads_waiting.clear
+      end
+
+      message
+    end
+
+    # The callback fired by midi-communications-macos when new MIDI messages are received
+    def get_event_callback
+      Thread.abort_on_exception = true
+      proc do |new_packets, _refcon_ptr, _connrefcon_ptr|
+        begin
+          # p "packets received: #{new_packets[:numPackets]}"
+          timestamp = Time.now.to_f
+          messages = get_messages(new_packets)
+          messages.each do |message|
+            enqueue_message(message, timestamp)
+          end
+        rescue Exception => exception
+          Thread.main.raise(exception)
+        end
+      end
+    end
+
+    # Get MIDI messages from the given CoreMIDI packet list
+    # @param [API::MIDIPacketList] packet_list The packet list
+    # @return [Array<Array<Fixnum>>] A collection of MIDI messages
+    def get_messages(packet_list)
+      count = packet_list[:numPackets]
+      first = packet_list[:packet][0]
+      data = first[:data].to_a
+      messages = []
+      messages << data.slice!(0, first[:length])
+      (count - 1).times do |i|
+        length_index = find_next_length_index(data)
+        message_length = data[length_index]
+
+        next if message_length.nil?
+
+        packet_start_index = length_index + 2
+        packet_end_index = packet_start_index + message_length
+
+        next unless data.length >= packet_end_index + 1
+
+        packet = data.slice!(0..packet_end_index)
+        message = packet.slice(packet_start_index, message_length)
+        messages << message
+      end
+      messages
+    end
+
+    # Get the next index for "length" from the blob of MIDI data
+    # @param [Array<Fixnum>] data
+    # @return [Fixnum]
+    def find_next_length_index(data)
+      last_is_zero = false
+      data.each_with_index do |num, i|
+        if num.zero?
+          if last_is_zero
+            return i + 1
+          else
+            last_is_zero = true
+          end
+        else
+          last_is_zero = false
+        end
+      end
+    end
+
+    # Give a message its timestamp and package it in a Hash
+    # @return [Hash]
+    def get_message_formatted(raw, time)
+      {
+        data: raw,
+        timestamp: time
+      }
+    end
+
+    # Initialize a midi-communications-macos port for this endpoint
+    # @return [Boolean]
+    def initialize_port
+      @callback = get_event_callback
+      port = API.create_midi_input_port(@client, @resource_id, @name, @callback)
+      @handle = port[:handle]
+      raise "MIDIInputPortCreate returned error code #{port[:error]}" unless port[:error].zero?
+
+      true
+    end
+  end
+end

data/lib/midi-communications-macos/type_conversion.rb

@@ -0,0 +1,18 @@
+module MIDICommunicationsMacOS
+  # Helper for convertig MIDI data
+  module TypeConversion
+    extend self
+
+    # Convert an array of numeric byes to a hex string (e.g. [0x90, 0x40, 0x40] becomes "904040")
+    # @param [Array<Integer>] bytes
+    # @return [String]
+    def numeric_bytes_to_hex_string(bytes)
+      string_bytes = bytes.map do |byte|
+        str = byte.to_s(16).upcase
+        str = "0#{str}" if byte < 16
+        str
+      end
+      string_bytes.join
+    end
+  end
+end

data/lib/midi-communications-macos.rb

@@ -0,0 +1,26 @@
+#
+# midi-communications-macos
+# Realtime MIDI IO with Ruby for OSX
+#
+# (c)2021 Javier Sánchez Yeste for the modifications, licensed under LGPL 3.0 License
+# (c)2011-2017 Ari Russo
+#
+
+# Libs
+require 'ffi'
+require 'forwardable'
+
+# Modules
+require 'midi-communications-macos/api'
+require 'midi-communications-macos/endpoint'
+require 'midi-communications-macos/type_conversion'
+
+# Classes
+require 'midi-communications-macos/entity'
+require 'midi-communications-macos/device'
+require 'midi-communications-macos/source'
+require 'midi-communications-macos/destination'
+
+module MIDICommunicationsMacOS
+  VERSION = '0.5.0'.freeze
+end

data/midi-communications-macos.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name        = 'midi-communications-macos'
+  s.version     = '0.5.0'
+  s.date        = '2021-11-15'
+  s.summary     = 'Realtime MIDI IO with Ruby for OSX'
+  s.description = 'Access the Apple Core MIDI framework API with Ruby.'
+  s.authors     = ['Javier Sánchez Yeste']
+  s.email       = ['javier.sy@gmail.com']
+  s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  s.homepage    = 'http://rubygems.org/gems/midi-communications-macos'
+  s.license     = 'LGPL-3.0'
+
+  s.required_ruby_version = '~> 2.7'
+
+  s.add_runtime_dependency 'ffi', '~> 1.15', '>= 1.15.4'
+
+  # TODO
+  #s.metadata    = {
+  # "source_code_uri" => "https://",
+  # "homepage_uri" => "",
+  # "documentation_uri" => "",
+  # "changelog_uri" => ""
+  #}
+end