jack-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: deb5b3c37204593146aa576d510d9c62a32c9849fd764ccf2a7ef445c1b6bdee
+  data.tar.gz: 81274b63cc67a48af0acd4666eaa5b0d504f743c6852822585049452d94de9c8
+SHA512:
+  metadata.gz: 95cd674bef67eca949b8c949f36bffddb06ac71d8a107b09dac04402e4b852b98d54586893a136eb5c772bea13deff2d0335e9f79c0c7f0fb612950560fb16aa
+  data.tar.gz: d54bf327e2f5bb61a648847c56a43bf2bb3f55c6eda2b878592c253ae26e04d80e0c0dff2cda9f32899406a4ded797b4c74a8a95f1d01f5e7558856cf0206a07

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-06
+
+### Added
+
+- Complete FFI bindings for JACK Audio Connection Kit (JACK1 and JACK2)
+- FFI type definitions, structs, and callback types (`Jack::FFI::Types`, `Jack::FFI::Structs`)
+- Library detection for Linux, macOS, and Windows (`Jack::FFI::LibJack`)
+- High-level `Jack::Client` with open/close/activate lifecycle management
+- `Jack::AudioPort` for audio buffer read/write
+- `Jack::MidiPort` for MIDI event read/write
+- `Jack::Midi::Event` with message parsing helpers (note on/off, CC, pitch bend, etc.)
+- `Jack::Transport` for transport control (start/stop/locate/query)
+- `Jack::Session` for session management
+- `Jack::RingBuffer` for lock-free inter-thread communication
+- `Jack::Metadata` for JACK2 metadata API (optional)
+- `Jack::CallbackManager` for GC-safe callback reference management
+- Comprehensive error classes (`ClientOpenFailed`, `ConnectionFailed`, etc.)
+- JACK1/JACK2 compatibility via `attach_optional` for version-specific APIs
+- Example scripts for common use cases

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,205 @@
+# Jack
+
+Ruby FFI bindings for the core [JACK Audio Connection Kit](https://jackaudio.org/) client APIs.
+
+This gem targets `libjack` from both JACK1 and JACK2. It covers client lifecycle, audio and MIDI ports, callbacks, transport, session management, metadata, ring buffers, UUID helpers, thread/statistics helpers, and internal client APIs.
+
+`net.h` / NetJACK (`libjacknet`) is a separate library and is not currently bound by this gem.
+
+## Installation
+
+Add the gem with Bundler:
+
+```bash
+bundle add jack-ruby
+```
+
+Or install it directly:
+
+```bash
+gem install jack-ruby
+```
+
+JACK itself must already be installed:
+
+- macOS: `brew install jack`
+- Ubuntu/Debian: `sudo apt-get install jackd2 libjack-jackd2-dev`
+- Fedora: `sudo dnf install jack-audio-connection-kit-devel`
+
+## Quick Start
+
+```ruby
+require "jack"
+
+puts "JACK #{Jack.version_string}"
+
+Jack::Client.open("simple") do |client|
+  puts "Client name: #{client.name}"
+  puts "Sample rate: #{client.sample_rate}"
+  puts "Buffer size: #{client.buffer_size}"
+  puts "Realtime: #{client.realtime?}"
+
+  client.activate
+
+  client.get_ports.each do |port_name|
+    puts port_name
+  end
+end
+```
+
+## Examples
+
+### Audio Passthrough
+
+```ruby
+require "jack"
+
+Jack::Client.open("passthrough") do |client|
+  input = client.register_audio_input("in")
+  output = client.register_audio_output("out")
+
+  client.on_process do |nframes|
+    in_buf = input.buffer_pointer(nframes)
+    out_buf = output.buffer_pointer(nframes)
+    out_buf.write_bytes(in_buf.read_bytes(nframes * 4))
+    0
+  end
+
+  client.activate
+
+  capture = client.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsOutput).first
+  playback = client.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsInput).first
+  client.connect(capture, "passthrough:in") if capture
+  client.connect("passthrough:out", playback) if playback
+
+  sleep
+end
+```
+
+### MIDI Monitor
+
+```ruby
+require "jack"
+
+Jack::Client.open("midi_monitor") do |client|
+  midi_in = client.register_midi_input("in")
+
+  client.on_process do |nframes|
+    midi_in.read_all_events(nframes).each do |event|
+      puts "Note ON #{event.note}" if event.note_on?
+      puts "Note OFF #{event.note}" if event.note_off?
+    end
+    0
+  end
+
+  client.activate
+  sleep
+end
+```
+
+### Transport Control
+
+```ruby
+require "jack"
+
+Jack::Client.open("transport_ctl") do |client|
+  transport = client.transport
+
+  client.activate
+  transport.locate(0)
+  transport.start
+
+  sleep 2
+
+  position = transport.query
+  puts "State: #{transport.state}"
+  puts "Frame: #{position[:frame]}"
+
+  transport.stop
+end
+```
+
+More runnable examples live in `examples/`:
+
+- `audio_passthrough.rb`
+- `meter.rb`
+- `midi_generator.rb`
+- `midi_monitor.rb`
+- `port_connector.rb`
+- `ringbuffer_recorder.rb`
+- `simple_client.rb`
+- `sine_generator.rb`
+- `transport_control.rb`
+
+## API Overview
+
+| API | Description |
+|---|---|
+| `Jack` | Library-wide helpers like `version`, `version_string`, `client_pid`, `on_error`, `on_info` |
+| `Jack::Client` | Client open/close, activation, port registration, connection management, callbacks, stats, RT scheduling, internal clients |
+| `Jack::Port` | Common port metadata, aliases, monitor control, latency helpers, legacy tie/untie support |
+| `Jack::AudioPort` | Raw audio buffer access |
+| `Jack::MidiPort` | MIDI event read/write, buffer reset/clear helpers |
+| `Jack::Midi::Event` | MIDI message inspection helpers |
+| `Jack::Transport` | Transport query/control, sync callback, timebase callback, legacy transport info helpers |
+| `Jack::Session` | Session callback, notify/reply, UUID and reservation helpers |
+| `Jack::Metadata` | Property set/get/remove and property change callback |
+| `Jack::RingBuffer` | Lock-free ring buffer, vectors, mlock, reset/reset_size |
+| `Jack::UUID` | UUID generation, parse/unparse, compare/copy/clear helpers |
+
+## Optional APIs and Compatibility
+
+JACK exports some symbols conditionally depending on the server and library version. When a method relies on an optional symbol and that symbol is not present, this gem raises `Jack::NotImplementedError`.
+
+Common examples:
+
+- `Jack::Metadata` methods on JACK installations without metadata support
+- `Jack::Port#rename` on older JACK versions
+- `Jack::RingBuffer#reset_size`
+- Legacy compatibility helpers such as `Jack::Port#latency`, `Jack::Port#total_latency`, and `Jack::Transport#legacy_info`
+
+The gem supports both JACK1 and JACK2 `libjack`, but some helpers are only available on JACK2 or newer JACK releases.
+
+## Top-Level Helpers
+
+```ruby
+require "jack"
+
+Jack.on_error { |message| warn "JACK error: #{message}" }
+Jack.on_info { |message| puts "JACK info: #{message}" }
+
+p Jack.version
+puts Jack.version_string
+puts Jack.client_pid("system")
+
+uuid = Jack::UUID.generate_client
+puts Jack::UUID.unparse(uuid)
+```
+
+## Development
+
+Install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Integration tests require a running JACK server and are only enabled when `JACK_TEST=1` is set:
+
+```bash
+jackd -d dummy &
+JACK_TEST=1 bundle exec rspec spec/integration/
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/jack.
+
+## Environment Variables
+
+- `JACK_LIB_PATH`: override the `libjack` path loaded by FFI
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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/audio_passthrough.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("passthrough") do |jack|
+  input  = jack.register_audio_input("in")
+  output = jack.register_audio_output("out")
+
+  jack.on_process do |nframes|
+    in_buf  = input.buffer_pointer(nframes)
+    out_buf = output.buffer_pointer(nframes)
+    out_buf.write_bytes(in_buf.read_bytes(nframes * 4))
+    0
+  end
+
+  jack.on_shutdown do |_code, reason|
+    puts "JACK shutdown: #{reason}"
+    exit
+  end
+
+  jack.activate
+
+  capture = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsOutput).first
+  playback = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsInput).first
+  jack.connect(capture, "passthrough:in") if capture
+  jack.connect("passthrough:out", playback) if playback
+
+  puts "Audio passthrough running... Press Ctrl-C to quit"
+  sleep
+end

data/examples/meter.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("meter") do |jack|
+  input = jack.register_audio_input("in")
+
+  jack.on_process do |nframes|
+    buf = input.buffer_pointer(nframes)
+    samples = buf.read_array_of_float(nframes)
+    peak = samples.map(&:abs).max || 0.0
+    db = peak > 0 ? 20.0 * Math.log10(peak) : -Float::INFINITY
+
+    bar_len = [(peak * 50).to_i, 50].min
+    bar = "#" * bar_len + " " * (50 - bar_len)
+    $stdout.write "\r[#{bar}] #{db.round(1)} dB  "
+    $stdout.flush
+    0
+  end
+
+  jack.activate
+
+  capture = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsOutput).first
+  jack.connect(capture, "meter:in") if capture
+
+  puts "Level meter running... Press Ctrl-C to quit"
+  sleep
+end

data/examples/midi_generator.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("midi_gen") do |jack|
+  midi_out = jack.register_midi_output("out")
+
+  note = 60
+  note_on = true
+  frame_count = 0
+  interval = jack.sample_rate / 2 # Toggle every 0.5 seconds
+
+  jack.on_process do |nframes|
+    midi_out.clear_buffer(nframes)
+
+    if frame_count >= interval
+      if note_on
+        midi_out.write_event(0, [0x90, note, 100], nframes)
+      else
+        midi_out.write_event(0, [0x80, note, 0], nframes)
+        note = (note + 1) % 128
+      end
+      note_on = !note_on
+      frame_count = 0
+    end
+
+    frame_count += nframes
+    0
+  end
+
+  jack.activate
+  puts "MIDI Generator running... Press Ctrl-C to quit"
+  sleep
+end

data/examples/midi_monitor.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("midi_monitor") do |jack|
+  midi_in = jack.register_midi_input("in")
+
+  jack.on_process do |nframes|
+    midi_in.read_all_events(nframes).each do |event|
+      if event.note_on?
+        puts "Note ON:  ch=#{event.channel} note=#{event.note} vel=#{event.velocity}"
+      elsif event.note_off?
+        puts "Note OFF: ch=#{event.channel} note=#{event.note}"
+      elsif event.control_change?
+        puts "CC: ch=#{event.channel} cc=#{event.controller} val=#{event.cc_value}"
+      elsif event.pitch_bend?
+        puts "Pitch Bend: ch=#{event.channel} val=#{event.pitch_bend_value}"
+      elsif event.program_change?
+        puts "Program Change: ch=#{event.channel} prog=#{event.note}"
+      end
+    end
+    0
+  end
+
+  jack.activate
+  puts "MIDI Monitor running... Press Ctrl-C to quit"
+  sleep
+end

data/examples/port_connector.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("connector") do |jack|
+  jack.activate
+
+  outputs = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsOutput)
+  inputs  = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsInput)
+
+  puts "Physical outputs: #{outputs}"
+  puts "Physical inputs:  #{inputs}"
+
+  # Connect first output to first input (loopback)
+  if outputs.first && inputs.first
+    jack.connect(outputs.first, inputs.first)
+    puts "Connected #{outputs.first} -> #{inputs.first}"
+  else
+    puts "No physical ports found"
+  end
+end

data/examples/ringbuffer_recorder.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+RECORD_SECONDS = 5
+
+Jack::Client.open("recorder") do |jack|
+  input = jack.register_audio_input("in")
+  rb = Jack::RingBuffer.new(jack.sample_rate * 4 * RECORD_SECONDS * 2)
+
+  jack.on_process do |nframes|
+    buf = input.buffer_pointer(nframes)
+    data = buf.read_bytes(nframes * 4)
+    rb.write(data)
+    0
+  end
+
+  jack.activate
+
+  capture = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsOutput).first
+  jack.connect(capture, "recorder:in") if capture
+
+  puts "Recording #{RECORD_SECONDS} seconds..."
+  sleep RECORD_SECONDS
+
+  total = rb.read_space
+  puts "Recorded #{total} bytes (#{total / 4} samples)"
+
+  data = rb.read(total)
+  File.binwrite("recording.raw", data)
+  puts "Saved to recording.raw (32-bit float, #{jack.sample_rate}Hz, mono)"
+
+  rb.free
+end

data/examples/simple_client.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("simple") do |jack|
+  puts "Client name: #{jack.name}"
+  puts "Sample rate: #{jack.sample_rate}"
+  puts "Buffer size: #{jack.buffer_size}"
+  puts "Realtime: #{jack.realtime?}"
+
+  jack.activate
+
+  ports = jack.get_ports
+  puts "\nAvailable ports:"
+  ports.each { |p| puts "  #{p}" }
+
+  puts "\nPress Ctrl-C to quit"
+  sleep
+end

data/examples/sine_generator.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+FREQUENCY = 440.0
+
+Jack::Client.open("sine_gen") do |jack|
+  output = jack.register_audio_output("out")
+  phase = 0.0
+  phase_inc = 2.0 * Math::PI * FREQUENCY / jack.sample_rate
+
+  jack.on_process do |nframes|
+    buf = output.buffer_pointer(nframes)
+    nframes.times do |i|
+      buf.put_float32(i * 4, Math.sin(phase))
+      phase += phase_inc
+      phase -= 2.0 * Math::PI if phase >= 2.0 * Math::PI
+    end
+    0
+  end
+
+  jack.activate
+
+  playback = jack.get_ports(flags: Jack::JackPortIsPhysical | Jack::JackPortIsInput).first
+  jack.connect("sine_gen:out", playback) if playback
+
+  puts "Generating #{FREQUENCY}Hz sine wave... Press Ctrl-C to quit"
+  sleep
+end

data/examples/transport_control.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jack"
+
+Jack::Client.open("transport_ctl") do |jack|
+  transport = jack.transport
+
+  jack.activate
+
+  transport.locate(0)
+  transport.start
+  sleep 2
+
+  pos = transport.query
+  puts "Position: frame=#{pos[:frame]} rate=#{pos[:frame_rate]}"
+  puts "State: #{transport.state}"
+
+  transport.stop
+  puts "Transport stopped"
+end

data/lib/jack/audio_port.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jack
+  class AudioPort < Port
+    def read_buffer(nframes)
+      ptr = buffer_pointer(nframes)
+      ptr.read_array_of_float(nframes)
+    end
+
+    def write_buffer(samples, nframes)
+      ptr = buffer_pointer(nframes)
+      ptr.write_array_of_float(samples[0, nframes])
+    end
+
+    def buffer_pointer(nframes)
+      FFI::LibJack.jack_port_get_buffer(@handle, nframes)
+    end
+  end
+end

data/lib/jack/callback_manager.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jack
+  class CallbackManager
+    def initialize
+      @callbacks = {}
+      @ffi_procs = {}
+      @mutex = Mutex.new
+    end
+
+    def register(type, proc_obj, ffi_func)
+      @mutex.synchronize do
+        @callbacks[type] = proc_obj
+        @ffi_procs[type] = ffi_func
+      end
+    end
+
+    def get(type)
+      @mutex.synchronize { @callbacks[type] }
+    end
+
+    def clear
+      @mutex.synchronize do
+        @callbacks.clear
+        @ffi_procs.clear
+      end
+    end
+  end
+end