rtmidi-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7893d826f1f417ce7a5b056e0a008ac45f3ff3f42fb1efab5444df197925433
+  data.tar.gz: 436013485d4e4faf7f33eaddf01b42422abba0ede737a6a2df49c9969eeed67a
+SHA512:
+  metadata.gz: 5ab907249073716156bfc7638d69c1967f5c7fb2a21eb5fbd8545317d3964862bb71792c4354198373ea94e08b3c1152bff3ecec62a2f3580299831d178e7944
+  data.tar.gz: 94cb6a7900b92b1efe38ada1f0d717b55273b2be13497c8f55e644ba5c6dd8aa37b2525a559a49d84c566c903d83d8c3026e762d57ac9e5baa8aed493f5037cb

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-07
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,327 @@
+# rtmidi-ruby
+
+`rtmidi-ruby` is a Ruby FFI binding for the RtMidi C API (`rtmidi_c.h`).
+It exposes the low-level C bindings through `Rtmidi::Native` and a higher-level
+Ruby API through `Rtmidi::MidiIn`, `Rtmidi::MidiOut`, and `Rtmidi::Message`.
+
+## Features
+
+- `Rtmidi.version`, `Rtmidi.compiled_apis`, and API name helpers
+- low-level access to the RtMidi C API via `Rtmidi::Native`
+- `Rtmidi::MidiIn` with callback and polling based input
+- `Rtmidi::MidiOut` helpers for channel, system common, and realtime messages
+- typed MIDI messages through `Rtmidi::Message`
+- virtual port support
+
+## Requirements
+
+- Ruby 3.1+
+- a system `librtmidi` that provides the RtMidi C API
+
+Install `librtmidi` with your package manager:
+
+- macOS: `brew install rtmidi`
+- Ubuntu/Debian: `sudo apt install librtmidi-dev`
+- Fedora: `sudo dnf install rtmidi-devel`
+- Arch: `sudo pacman -S rtmidi`
+- Windows: install an RtMidi DLL and make sure it is on `PATH`
+
+If the library is installed in a non-standard location, set `RTMIDI_LIB_PATH`.
+
+```bash
+RTMIDI_LIB_PATH=/path/to/librtmidi.dylib bundle exec ruby your_script.rb
+```
+
+Some `librtmidi` builds do not expose `rtmidi_set_error_callback`. In that case,
+normal MIDI I/O still works, but `on_error` callbacks are unavailable.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "rtmidi-ruby"
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+Or install the gem directly:
+
+```bash
+gem install rtmidi-ruby
+```
+
+## Quick Start
+
+```ruby
+require "rtmidi"
+
+puts "RtMidi version: #{Rtmidi.version}"
+puts "Compiled APIs: #{Rtmidi.compiled_apis.inspect}"
+```
+
+### List Ports
+
+```ruby
+require "rtmidi"
+
+out = Rtmidi::MidiOut.new
+puts "Output ports:"
+out.port_names.each_with_index { |name, index| puts "  #{index}: #{name}" }
+out.close
+
+input = Rtmidi::MidiIn.new
+puts "Input ports:"
+input.port_names.each_with_index { |name, index| puts "  #{index}: #{name}" }
+input.close
+```
+
+### Send Note On/Off
+
+```ruby
+require "rtmidi"
+
+out = Rtmidi::MidiOut.new
+
+if out.port_count.zero?
+  warn "No output ports available."
+else
+  begin
+    out.open_port(0)
+    out.note_on(0, 60, 100)
+    sleep 0.5
+    out.note_off(0, 60)
+  ensure
+    out.close
+  end
+end
+```
+
+### Receive With Callback
+
+```ruby
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+
+if midi_in.port_count.zero?
+  warn "No input ports available."
+  midi_in.close
+  exit 0
+end
+
+begin
+  midi_in.ignore_types(sysex: false, timing: false, active_sensing: false)
+  midi_in.open_port(0)
+
+  midi_in.on_message do |message, timestamp|
+    puts "#{timestamp}: #{message.map { |byte| format('%02X', byte) }.join(' ')}"
+  end
+
+  puts "Listening... (Ctrl-C to quit)"
+  sleep
+ensure
+  midi_in&.close
+end
+```
+
+### Receive With Polling
+
+```ruby
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+
+if midi_in.port_count.zero?
+  warn "No input ports available."
+  midi_in.close
+  exit 0
+end
+
+begin
+  midi_in.open_port(0)
+
+  loop do
+    packet = midi_in.get_message
+    next if packet.nil?
+
+    message, timestamp = packet
+    puts "#{timestamp}: #{message.inspect}"
+
+    sleep 0.001
+  end
+ensure
+  midi_in&.close
+end
+```
+
+### Typed Messages
+
+`Rtmidi::Message` can parse raw bytes into typed structs and `MidiOut#send_message`
+accepts either raw byte arrays or typed messages.
+
+```ruby
+require "rtmidi"
+
+message = Rtmidi::Message.parse([0x92, 64, 96])
+p message
+# => #<struct Rtmidi::Message::NoteOn channel=2, note=64, velocity=96>
+
+out = Rtmidi::MidiOut.new
+
+if out.port_count.zero?
+  warn "No output ports available."
+else
+  begin
+    out.open_port(0)
+    out.send_message(Rtmidi::Message::ProgramChange.new(channel: 1, program: 10))
+  ensure
+    out.close
+  end
+end
+```
+
+For typed input callbacks:
+
+```ruby
+midi_in.on_message(parsed: true) do |message, timestamp|
+  p [message.class, message, timestamp]
+end
+```
+
+### System/Common and Realtime Helpers
+
+`Rtmidi::MidiOut` includes helpers for common output messages:
+
+- `sysex`
+- `control_change`
+- `program_change`
+- `pitch_bend`
+- `channel_aftertouch`
+- `poly_aftertouch`
+- `time_code_quarter_frame`
+- `song_position_pointer`
+- `song_select`
+- `tune_request`
+- `timing_clock`
+- `start`
+- `continue`
+- `stop`
+- `active_sensing`
+- `system_reset`
+- `nrpn`
+
+Example:
+
+```ruby
+require "rtmidi"
+
+out = Rtmidi::MidiOut.new
+
+if out.port_count.zero?
+  warn "No output ports available."
+else
+  begin
+    out.open_port(0)
+    out.sysex([0x7D, 0x01])
+    out.song_select(3)
+    out.start
+    out.nrpn(0, 0x1234, 0x0567)
+  ensure
+    out.close
+  end
+end
+```
+
+### Virtual Ports
+
+```ruby
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+midi_out = Rtmidi::MidiOut.new
+
+begin
+  midi_in.open_virtual_port(name: "Rtmidi Ruby Virtual In")
+  midi_out.open_virtual_port(name: "Rtmidi Ruby Virtual Out")
+
+  puts "Virtual ports opened."
+  sleep
+ensure
+  midi_out&.close
+  midi_in&.close
+end
+```
+
+### Low-Level C API
+
+```ruby
+require "rtmidi"
+
+handle = nil
+
+begin
+  handle = Rtmidi::Native.rtmidi_out_create_default
+  Rtmidi::Native.check_error(handle)
+
+  count = Rtmidi::Native.rtmidi_get_port_count(handle)
+  Rtmidi::Native.check_error(handle)
+
+  puts "#{count} output ports found"
+ensure
+  Rtmidi::Native.rtmidi_out_free(handle) if handle && !handle.null?
+end
+```
+
+## Error Handling
+
+Synchronous operations raise `Rtmidi::Error` subclasses where possible, including:
+
+- `Rtmidi::NoDevicesError`
+- `Rtmidi::InvalidPortError`
+- `Rtmidi::InvalidUseError`
+- `Rtmidi::DriverError`
+
+Validation failures use `ArgumentError`.
+
+If a callback raises, the exception is stored and surfaced on the next locked API call.
+
+## Callback Notes
+
+- Keep callback processing lightweight.
+- For heavier work, pass the event to a `Queue` and handle it in another thread.
+- Do not call `close` or `close_port` from inside an input callback.
+- `parsed: true` yields `Rtmidi::Message::*` structs instead of raw byte arrays.
+
+## Examples
+
+The repository includes runnable examples in [`examples/`](examples):
+
+- `examples/list_ports.rb`
+- `examples/send_note.rb`
+- `examples/sysex_send.rb`
+- `examples/receive_callback.rb`
+- `examples/receive_polling.rb`
+- `examples/virtual_port.rb`
+
+Run them against the local checkout with:
+
+```bash
+bundle exec ruby -Ilib examples/list_ports.rb
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake
+```
+
+## License
+
+Released under the MIT License. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/list_ports.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+puts "RtMidi version: #{Rtmidi.version}"
+puts "Compiled APIs: #{Rtmidi.compiled_apis.inspect}"
+
+out = Rtmidi::MidiOut.new
+puts "Output ports:"
+out.port_names.each_with_index { |name, index| puts "  #{index}: #{name}" }
+out.close
+
+input = Rtmidi::MidiIn.new
+puts "Input ports:"
+input.port_names.each_with_index { |name, index| puts "  #{index}: #{name}" }
+input.close

data/examples/receive_callback.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+
+if midi_in.port_count.zero?
+  warn "No input ports available."
+  midi_in.close
+  exit 0
+end
+
+begin
+  midi_in.ignore_types(sysex: false, timing: false, active_sensing: false)
+  midi_in.open_port(0)
+
+  midi_in.on_message do |message, timestamp|
+    puts "#{timestamp}: #{message.map { |b| format('%02X', b) }.join(' ')}"
+  end
+
+  puts "Listening... (Ctrl-C to quit)"
+  sleep
+ensure
+  midi_in&.close
+end

data/examples/receive_polling.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+
+if midi_in.port_count.zero?
+  warn "No input ports available."
+  midi_in.close
+  exit 0
+end
+
+begin
+  midi_in.open_port(0)
+
+  loop do
+    packet = midi_in.get_message
+    if packet
+      message, timestamp = packet
+      puts "#{timestamp}: #{message.inspect}"
+    end
+
+    sleep 0.001
+  end
+ensure
+  midi_in&.close
+end

data/examples/send_note.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+out = Rtmidi::MidiOut.new
+
+if out.port_count.zero?
+  warn "No output ports available."
+else
+  begin
+    out.open_port(0)
+    out.note_on(0, 60, 100)
+    sleep 0.5
+    out.note_off(0, 60)
+  ensure
+    out.close
+  end
+end

data/examples/sysex_send.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+# Example SysEx payload (manufacturer-specific example):
+# F0 7D 10 01 F7
+message = [0xF0, 0x7D, 0x10, 0x01, 0xF7]
+
+out = Rtmidi::MidiOut.new
+
+if out.port_count.zero?
+  warn "No output ports available."
+else
+  begin
+    out.open_port(0)
+    out.send_message(message)
+  ensure
+    out.close
+  end
+end

data/examples/virtual_port.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rtmidi"
+
+midi_in = Rtmidi::MidiIn.new
+midi_out = Rtmidi::MidiOut.new
+
+begin
+  midi_in.open_virtual_port(name: "Rtmidi Ruby Virtual In")
+  midi_out.open_virtual_port(name: "Rtmidi Ruby Virtual Out")
+
+  puts "Virtual ports opened."
+  puts "Connect them from your MIDI patchbay / DAW, then send/receive as needed."
+
+  sleep
+ensure
+  midi_out&.close
+  midi_in&.close
+end

data/lib/rtmidi/api.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Rtmidi
+  module Api
+    VALUES = {
+      unspecified: 0,
+      macosx_core: 1,
+      linux_alsa: 2,
+      unix_jack: 3,
+      windows_mm: 4,
+      rtmidi_dummy: 5,
+      web_midi_api: 6,
+      windows_uwp: 7,
+      android_amidi: 8,
+      num_apis: 9
+    }.freeze
+
+    NUMBERS = VALUES.invert.freeze
+
+    class << self
+      def normalize(api)
+        case api
+        when Symbol
+          symbol_for(api)
+        when Integer
+          symbol_for(api)
+        else
+          nil
+        end || raise(ArgumentError, "unknown API: #{api.inspect}")
+      end
+
+      def symbol_for(api)
+        return api if api.is_a?(Symbol) && VALUES.key?(api)
+        return NUMBERS[api] if api.is_a?(Integer)
+
+        nil
+      end
+    end
+  end
+
+  class << self
+    def version
+      Native.rtmidi_get_version
+    end
+
+    def compiled_apis
+      Native.ensure_loaded!
+
+      count = Native.rtmidi_get_compiled_api(nil, 0).to_i
+      return [] if count <= 0
+
+      buffer = FFI::MemoryPointer.new(:int, count)
+      written = Native.rtmidi_get_compiled_api(buffer, count).to_i
+      length = [written, count].min
+      return [] if length <= 0
+
+      buffer.read_array_of_int(length).filter_map { |value| Api.symbol_for(value) }
+    end
+
+    def api_name(api)
+      Native.rtmidi_api_name(Api.normalize(api))
+    end
+
+    def api_display_name(api)
+      Native.rtmidi_api_display_name(Api.normalize(api))
+    end
+
+    def api_by_name(name)
+      value = Native.rtmidi_compiled_api_by_name(name.to_s)
+      Api.symbol_for(value) || :unspecified
+    end
+  end
+end

data/lib/rtmidi/error.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Rtmidi
+  class Error < StandardError
+    attr_reader :type
+
+    def initialize(message = "RtMidi error", type: :unspecified)
+      @type = type.to_sym
+      super(message)
+    end
+  end
+
+  class NoDevicesError < Error; end
+  class InvalidPortError < Error; end
+  class DriverError < Error; end
+  class MemoryError < Error; end
+  class InvalidUseError < Error; end
+
+  ERROR_MAP = {
+    no_devices_found: NoDevicesError,
+    invalid_device: InvalidPortError,
+    memory_error: MemoryError,
+    invalid_parameter: ArgumentError,
+    invalid_use: InvalidUseError,
+    driver_error: DriverError,
+    system_error: Error,
+    thread_error: Error,
+    warning: nil,
+    debug_warning: nil,
+    unspecified: Error
+  }.freeze
+
+  WARNING_TYPES = %i[warning debug_warning].freeze
+
+  class << self
+    def warning_type?(type)
+      WARNING_TYPES.include?(type.to_sym)
+    end
+
+    def error_class_for(type)
+      ERROR_MAP.fetch(type.to_sym, Error)
+    end
+
+    def error_for(type, message)
+      klass = error_class_for(type)
+      return Error.new(message, type: type) if klass.nil?
+      return klass.new(message) unless klass <= Error
+
+      klass.new(message, type: type)
+    end
+  end
+end