webmidi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc76ddd4eadafc9aeedd43adf4f2a7df4389f3145e8ab92ad826a07def6a2fdb
+  data.tar.gz: 3c55c45cba163273c17e5691a11fd7fe8d76bbacf0a8c4adda66d73bf7618431
+SHA512:
+  metadata.gz: 6edb7b915fbc4a97446aa418a65bd914ae23502688e7d8bab47a79696daf7ad373d28a9f1c941424853024ad82223bd35e72589d90116fa3a6bf82a88f67e514
+  data.tar.gz: c589a81b550df457c2c98d6e4ba9fd22d7d8a14fd64d5cc65b208656f95db24b0b6128f599acc60acefc1fe9333f501fb4c045ce234cec3a069e25fe61c55887

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-05-25
+
+- 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,73 @@
+# Webmidi
+
+Webmidi is a pure-Ruby MIDI library inspired by the W3C Web MIDI API.
+It provides MIDI messages, ports, Standard MIDI File I/O, middleware,
+network MIDI, and MIDI 2.0 UMP support with zero runtime dependencies.
+
+## Requirements
+
+- Ruby 3.2 or newer
+
+## Installation
+
+```ruby
+gem "webmidi"
+```
+
+## Quick Start
+
+```ruby
+require "webmidi"
+
+loopback = Webmidi::Virtual::Loopback.create(name: "Demo")
+
+loopback.input.on_message do |message|
+  puts message.to_hex
+end
+
+loopback.output.note_on(60, velocity: 100)
+loopback.output.note_off(60)
+
+loopback.close
+```
+
+## Core APIs
+
+```ruby
+# MIDI messages
+message = Webmidi::Message.note_on(:C4, velocity: 100, channel: 0)
+message.to_bytes # => [0x90, 60, 100]
+
+parsed = Webmidi::Message.from_bytes(0x90, 60, 100)
+
+# Standard MIDI Files
+sequence = Webmidi::SMF::Sequence.read("input.mid")
+sequence.write("output.mid")
+
+# MIDI 2.0 UMP
+ump = Webmidi::Message.upgrade(message)
+midi1 = Webmidi::Message.downgrade(ump)
+```
+
+## Included
+
+- MIDI 1.0 channel and system messages
+- MIDI byte parsing, stream parsing, and running status support
+- Virtual input/output ports and loopback ports
+- Standard MIDI File format 0/1 reader and writer
+- Middleware for filtering, transposition, velocity changes, logging, recording, and routing
+- Music helpers for notes, chords, scales, rhythm, and frequencies
+- RTP-MIDI, AppleMIDI negotiation, and OSC bridging
+- MIDI 2.0 Universal MIDI Packet parsing and MIDI 1.0 conversion
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+bundle exec rake release:check
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "tmpdir"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :coverage do
+  ENV["COVERAGE"] = "1"
+  Rake::Task[:spec].invoke
+end
+
+task :mutation do
+  unless Gem::Specification.find_all_by_name("mutant-rspec").any?
+    warn "mutant-rspec is not installed; skipping mutation run"
+    next
+  end
+
+  sh "bundle exec mutant run --use rspec Webmidi*"
+end
+
+task :standard do
+  ENV["RUBOCOP_CACHE_ROOT"] ||= File.expand_path("tmp/rubocop_cache", __dir__)
+  sh "standardrb"
+end
+
+task :smoke_require do
+  ruby "-Ilib", "-e", "require 'webmidi'"
+end
+
+task :build_gem do
+  Dir.mktmpdir("webmidi-gem-build") do |dir|
+    sh "gem build webmidi.gemspec --output #{File.join(dir, "webmidi.gem")}"
+  end
+end
+
+namespace :release do
+  task check: [:standard, :spec, :smoke_require, :build_gem] do
+    spec = Gem::Specification.load("webmidi.gemspec")
+    raise "Missing version" if spec.version.to_s.empty?
+    raise "CHANGELOG.md is missing" unless File.exist?("CHANGELOG.md")
+    raise "MFA metadata is required" unless spec.metadata["rubygems_mfa_required"] == "true"
+    raise "gemspec must be included in package files" unless spec.files.include?("webmidi.gemspec")
+  end
+end
+
+task default: :spec

data/lib/webmidi/access.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "callback_subscription"
+
+module Webmidi
+  class Access
+    include Enumerable
+
+    attr_reader :sysex_enabled
+
+    alias_method :sysex_enabled?, :sysex_enabled
+
+    def initialize(sysex: false, transport: nil)
+      @sysex_enabled = sysex
+      @transport = transport ? Transport.send(:resolve_transport!, transport) : Transport.auto_detect
+      @inputs = Port::Map.new
+      @outputs = Port::Map.new
+      @state_change_callbacks = []
+      @port_state_subscriptions = []
+      @mutex = Mutex.new
+      refresh_ports
+    end
+
+    def inputs
+      @mutex.synchronize { @inputs.snapshot }
+    end
+
+    def outputs
+      @mutex.synchronize { @outputs.snapshot }
+    end
+
+    def input(name_or_id)
+      @mutex.synchronize { @inputs[name_or_id] }
+    end
+
+    def output(name_or_id)
+      @mutex.synchronize { @outputs[name_or_id] }
+    end
+
+    def fetch_input!(name_or_id)
+      input(name_or_id) || raise(PortNotFoundError, "Input port not found: #{name_or_id}")
+    end
+
+    def fetch_output!(name_or_id)
+      output(name_or_id) || raise(PortNotFoundError, "Output port not found: #{name_or_id}")
+    end
+
+    def on_state_change(&block)
+      raise ArgumentError, "on_state_change requires a block" unless block
+
+      @mutex.synchronize { @state_change_callbacks << block }
+      CallbackSubscription.new do
+        @mutex.synchronize { @state_change_callbacks.delete(block) }
+      end
+    end
+
+    def close
+      each(&:disconnect)
+      self
+    end
+
+    def each(&block)
+      ports = @mutex.synchronize { @inputs.to_a + @outputs.to_a }
+      ports.each(&block)
+    end
+
+    def create_input(name)
+      handle = @transport.create_virtual_input(name)
+      port = Port::Input.new(
+        id: handle.device_info.id,
+        name: handle.device_info.name,
+        manufacturer: handle.device_info.manufacturer,
+        version: handle.device_info.version,
+        transport_handle: handle,
+        sysex_enabled: @sysex_enabled
+      )
+      register_port(port, @inputs)
+      port
+    end
+
+    def create_output(name)
+      handle = @transport.create_virtual_output(name)
+      port = Port::Output.new(
+        id: handle.device_info.id,
+        name: handle.device_info.name,
+        manufacturer: handle.device_info.manufacturer,
+        version: handle.device_info.version,
+        transport_handle: handle,
+        sysex_enabled: @sysex_enabled
+      )
+      register_port(port, @outputs)
+      port
+    end
+
+    def refresh_ports
+      sync_ports(@inputs, @transport.list_inputs, Port::Input, :open_input)
+      sync_ports(@outputs, @transport.list_outputs, Port::Output, :open_output)
+      self
+    end
+
+    private
+
+    def sync_ports(map, infos, port_class, open_method)
+      current_ids = infos.map(&:id)
+      removed = []
+      added = []
+
+      @mutex.synchronize do
+        map.to_a.reject { |port| current_ids.include?(port.id) }.each do |port|
+          map.remove(port)
+          removed << port
+        end
+
+        infos.each do |info|
+          next if map[info.id]
+
+          handle = @transport.respond_to?(open_method) ? @transport.public_send(open_method, info) : nil
+          port = port_class.new(
+            id: info.id, name: info.name,
+            manufacturer: info.manufacturer, version: info.version,
+            transport_handle: handle,
+            sysex_enabled: @sysex_enabled
+          )
+          map.add(port)
+          watch_port(port)
+          added << port
+        end
+      end
+
+      removed.each do |port|
+        port.disconnect
+        notify_state_change(port)
+      end
+      added.each { |port| notify_state_change(port) }
+    end
+
+    def register_port(port, map)
+      @mutex.synchronize do
+        map.add(port)
+        watch_port(port)
+      end
+      notify_state_change(port)
+    end
+
+    def watch_port(port)
+      subscription = port.on_state_change { |changed_port| notify_state_change(changed_port) }
+      @port_state_subscriptions << subscription
+    end
+
+    def notify_state_change(port)
+      callbacks = @mutex.synchronize { @state_change_callbacks.dup }
+      callbacks.each { |cb| cb.call(port) }
+    end
+  end
+
+  class << self
+    def request_access(sysex: Webmidi.configuration.sysex, &block)
+      access = Access.new(sysex: sysex)
+      if block
+        begin
+          block.call(access)
+        ensure
+          access.close
+        end
+      else
+        access
+      end
+    end
+  end
+end

data/lib/webmidi/callback_subscription.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Webmidi
+  class CallbackSubscription
+    def initialize(&unsubscribe)
+      @unsubscribe = unsubscribe
+      @active = true
+      @mutex = Mutex.new
+    end
+
+    def unsubscribe
+      callback = @mutex.synchronize do
+        return false unless @active
+
+        @active = false
+        @unsubscribe
+      end
+      callback.call
+      true
+    end
+
+    def active?
+      @mutex.synchronize { @active }
+    end
+  end
+end

data/lib/webmidi/clock.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "callback_subscription"
+
+module Webmidi
+  class Clock
+    PPQN = 24
+
+    attr_reader :bpm, :running
+
+    alias_method :running?, :running
+
+    def initialize(bpm: 120)
+      validate_bpm!(bpm)
+      @bpm = bpm
+      @running = false
+      @callbacks = []
+      @error_callbacks = []
+      @mutex = Mutex.new
+      @thread = nil
+      @tick_count = 0
+    end
+
+    def bpm=(new_bpm)
+      validate_bpm!(new_bpm)
+      @mutex.synchronize { @bpm = new_bpm }
+    end
+
+    def start
+      @mutex.synchronize do
+        return self if @running
+
+        @running = true
+        @tick_count = 0
+        @thread = Thread.new { clock_loop }
+      end
+      self
+    end
+
+    def stop
+      thread = @mutex.synchronize do
+        @running = false
+        @thread
+      end
+      thread&.join(1) if thread && thread != Thread.current
+      @mutex.synchronize { @thread = nil if @thread == thread }
+      self
+    end
+
+    def on_tick(&block)
+      raise ArgumentError, "on_tick requires a block" unless block
+
+      @mutex.synchronize { @callbacks << block }
+      CallbackSubscription.new do
+        @mutex.synchronize { @callbacks.delete(block) }
+      end
+    end
+
+    def on_error(&block)
+      raise ArgumentError, "on_error requires a block" unless block
+
+      @mutex.synchronize { @error_callbacks << block }
+      CallbackSubscription.new do
+        @mutex.synchronize { @error_callbacks.delete(block) }
+      end
+    end
+
+    def pipe_to(output)
+      on_tick { output.send(Message.clock) }
+    end
+
+    def start_message
+      Message.start
+    end
+
+    def stop_message
+      Message.stop
+    end
+
+    def tick_count
+      @mutex.synchronize { @tick_count }
+    end
+
+    def beat_count
+      @mutex.synchronize { @tick_count / PPQN }
+    end
+
+    private
+
+    def clock_loop
+      next_tick = monotonic_now
+      loop do
+        running, interval = @mutex.synchronize { [@running, 60.0 / (@bpm * PPQN)] }
+        break unless running
+
+        next_tick += interval
+        sleep_time = next_tick - monotonic_now
+        sleep(sleep_time) if sleep_time.positive?
+
+        callbacks, tick = @mutex.synchronize do
+          next [nil, nil] unless @running
+
+          @tick_count += 1
+          [@callbacks.dup, @tick_count]
+        end
+        next unless callbacks
+
+        callbacks.each { |cb| safely_call(cb, tick) }
+      end
+    end
+
+    def safely_call(callback, tick)
+      callback.call(tick)
+    rescue => e
+      error_callbacks = @mutex.synchronize { @error_callbacks.dup }
+      error_callbacks.each { |cb| cb.call(e, tick) }
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def validate_bpm!(bpm)
+      return if bpm.is_a?(Numeric) && bpm.positive?
+
+      raise InvalidMessageError, "BPM must be positive, got #{bpm.inspect}"
+    end
+  end
+end

data/lib/webmidi/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Webmidi
+  class Configuration
+    attr_accessor :transport, :fallback_transport,
+      :default_channel, :default_velocity,
+      :default_group,
+      :sysex,
+      :logger, :log_level,
+      :timestamp_source
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      @transport = :auto
+      @fallback_transport = :virtual
+      @default_channel = 0
+      @default_velocity = 100
+      @default_group = 0
+      @sysex = false
+      @logger = nil
+      @log_level = :info
+      @timestamp_source = :monotonic
+      self
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/webmidi/error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Webmidi
+  class Error < StandardError; end
+
+  # Port-related errors
+  class PortNotFoundError < Error; end
+  class PortOpenError < Error; end
+  class PortClosedError < Error; end
+
+  # Message-related errors
+  class InvalidMessageError < Error; end
+  class SysExNotPermittedError < Error; end
+
+  # File-related errors
+  class InvalidSMFError < Error; end
+  class UnsupportedFormatError < Error; end
+
+  # Network-related errors
+  class NetworkError < Error; end
+  class ConnectionTimeoutError < NetworkError; end
+
+  # Transport-related errors
+  class TransportNotAvailableError < Error; end
+  class TransportError < Error; end
+end

data/lib/webmidi/message/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Webmidi
+  module Message
+    class Base
+      attr_reader :timestamp
+
+      def initialize(timestamp: nil)
+        @timestamp = timestamp || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        freeze
+      end
+
+      def to_bytes
+        raise NotImplementedError, "#{self.class}#to_bytes must be implemented"
+      end
+
+      def to_hex
+        to_bytes.map { |b| format("%02X", b) }.join(" ")
+      end
+
+      def to_binary
+        to_bytes.pack("C*").b
+      end
+
+      def channel
+        nil
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && same_bytes?(other)
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      def hash
+        [self.class, to_bytes].hash
+      end
+
+      def same_bytes?(other)
+        other.respond_to?(:to_bytes) && to_bytes == other.to_bytes
+      end
+
+      def same_event?(other)
+        other.is_a?(self.class) && same_bytes?(other) && timestamp == other.timestamp
+      end
+
+      def with(**changes)
+        changes = changes.dup
+        next_timestamp = changes.key?(:timestamp) ? changes.delete(:timestamp) : @timestamp
+        self.class.new(**deconstruct_keys(nil).merge(changes), timestamp: next_timestamp)
+      end
+
+      def deconstruct
+        to_bytes
+      end
+
+      def deconstruct_keys(keys)
+        {}
+      end
+    end
+  end
+end