portaudio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a1f4649d2439f0148beb887fac7bfa2c5d52f769c246381212a145b7cb26ef1
+  data.tar.gz: ddb39d4f70a5e3e7263c38162809955c6b0d88e5b745565b70085e7e011f8f3e
+SHA512:
+  metadata.gz: '0967e0db0a6e6d00573bba8e39f73c70956f61daaaee09f2ed514c7f2be74d4bb56dd524e5bae22d8488be25dca04ba1f6d304a5f195bcfdf8fa26e9df935a3e'
+  data.tar.gz: ccc47eef65f9ef870cf8f0c5e9f178401488dd38a943fd68044e4a3c0546cf7b37ee9efab6a0b70c8602d6e6c01e2c4c28897790aa7979199158a995330ade68

data/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    env:
+      PORTAUDIO_RUN_INTEGRATION: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+        ruby:
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0'
+          - 'head'
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Install PortAudio (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libportaudio2 portaudio19-dev
+      - name: Install PortAudio (macOS)
+        if: runner.os == 'macOS'
+        run: brew install portaudio
+      - name: Run test suite
+        run: bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-03-05
+
+- Initial release.

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "ffi", ">= 1.15"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"

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,388 @@
+# portaudio
+
+`portaudio` is a Ruby FFI binding for PortAudio V19.
+
+It exposes the low-level PortAudio API under `PortAudio::C` and a small set of Ruby wrappers for common tasks such as device discovery, host API discovery, blocking streams, callback streams, and buffer conversion.
+
+## Public API overview
+
+| API | Purpose |
+| --- | --- |
+| `PortAudio` | Lifecycle helpers such as `init`, `terminate`, `with_portaudio`, and `check_error!` |
+| `PortAudio::Device` | Enumerate devices, inspect defaults, and search by name |
+| `PortAudio::HostAPI` | Enumerate host APIs and access their devices |
+| `PortAudio::BlockingStream` | Blocking `read` / `write` streams |
+| `PortAudio::Stream` | Callback-based streams |
+| `PortAudio::Buffer` | Convert between raw PortAudio bytes and Ruby float arrays |
+| `PortAudio::C` | Low-level functions, constants, enums, and structs |
+| `PortAudio::C::HostAPI` | Low-level host API extension bindings |
+
+`Portaudio` remains available as a compatibility alias for `PortAudio`.
+
+## Requirements
+
+- Ruby `>= 3.1`
+- `ffi >= 1.15`
+- A PortAudio shared library installed on the system
+
+## Install PortAudio
+
+Install the runtime and development files first:
+
+- macOS: `brew install portaudio`
+- Ubuntu/Debian: `sudo apt-get install -y libportaudio2 portaudio19-dev`
+- Windows (RubyInstaller2 UCRT): `ridk exec pacman -S mingw-w64-ucrt-x86_64-portaudio`
+- Windows (RubyInstaller2 MINGW): `ridk exec pacman -S mingw-w64-x86_64-portaudio`
+
+On Windows, make one of these DLLs available on `PATH`:
+
+- `portaudio.dll`
+- `libportaudio.dll`
+- `libportaudio-2.dll`
+- `portaudio_x64.dll`
+
+You can also point the gem at a specific library file with `PORTAUDIO_LIBRARY_PATH` or `PortAudio::Configuration.library_path`.
+
+## Install the gem
+
+```bash
+bundle add portaudio
+```
+
+or:
+
+```bash
+gem install portaudio
+```
+
+## Configuration
+
+The shared library is loaded lazily on first use. If loading fails, the gem raises `PortAudio::LibraryNotLoadedError`.
+
+### Override the library path
+
+Use an environment variable:
+
+```bash
+export PORTAUDIO_LIBRARY_PATH=/custom/path/libportaudio.so
+```
+
+or configure it in Ruby:
+
+```ruby
+PortAudio::Configuration.library_path = "/custom/path/libportaudio.so"
+```
+
+Set the path before the first PortAudio call when possible.
+
+### Warning handling for blocking streams
+
+`PortAudio::BlockingStream#read` and `#write` treat overflow/underflow warning codes specially.
+
+- `PortAudio::Configuration.strict_warnings = false` is the default
+- When strict mode is off, warning codes are stored in `stream.last_warning`
+- When strict mode is on, warning codes raise normal Ruby exceptions such as `PortAudio::InputOverflowError`
+
+You can set this globally:
+
+```ruby
+PortAudio::Configuration.strict_warnings = true
+```
+
+or per call:
+
+```ruby
+chunk = stream.read(256, strict: false)
+```
+
+## Lifecycle
+
+Use `PortAudio.with_portaudio` for normal code. It initializes PortAudio, yields to your block, and terminates it in `ensure`.
+
+```ruby
+PortAudio.with_portaudio do
+  puts PortAudio.initialized? # => true
+end
+```
+
+`PortAudio.init` / `PortAudio.terminate` are reference-counted, so nested usage is safe.
+
+## Device and host API discovery
+
+```ruby
+PortAudio.with_portaudio do
+  puts "Host APIs:"
+  PortAudio::HostAPI.all.each do |host_api|
+    puts "#{host_api.index}: #{host_api.name} (#{host_api.type_symbol})"
+  end
+
+  puts
+  puts "Devices:"
+  PortAudio::Device.all.each do |device|
+    puts [
+      "#{device.index}: #{device.name}",
+      "host_api=#{device.host_api.name}",
+      "in=#{device.max_input_channels}",
+      "out=#{device.max_output_channels}",
+      "rate=#{device.default_sample_rate}"
+    ].join(" ")
+  end
+
+  default_input = PortAudio::Device.default_input
+  default_output = PortAudio::Device.default_output
+
+  p default_input
+  p default_output
+end
+```
+
+Useful helpers:
+
+- `PortAudio::Device.count`
+- `PortAudio::Device.find_by_name("built-in")`
+- `PortAudio::HostAPI.default`
+- `PortAudio::HostAPI.find_by_type(:paCoreAudio)` or another PortAudio host API type symbol
+
+## Stream parameter hashes
+
+Both `PortAudio::BlockingStream` and `PortAudio::Stream` accept `input:` and `output:` hashes with the same shape:
+
+```ruby
+{
+  device: device_or_index,
+  channels: 2,
+  format: :float32,
+  latency: 0.0,
+  host_api_stream_info: pointer_or_struct
+}
+```
+
+Notes:
+
+- `device` accepts either a `PortAudio::Device` object or a device index
+- `channels` defaults to `1`
+- `format` defaults to `:float32`
+- `latency` defaults to `0.0`
+- `host_api_stream_info` must be `FFI::Pointer`-compatible
+
+Supported sample format symbols:
+
+- `:float32`
+- `:int32`
+- `:int24`
+- `:int16`
+- `:int8`
+- `:uint8`
+
+## Blocking streams
+
+Use `PortAudio::BlockingStream` for explicit reads and writes.
+
+### Write audio to the default output device
+
+```ruby
+PortAudio.with_portaudio do
+  output = PortAudio::Device.default_output
+  raise "No default output device" unless output
+
+  stream = PortAudio::BlockingStream.new(
+    output: { device: output, channels: 1, format: :float32 },
+    sample_rate: output.default_sample_rate,
+    frames_per_buffer: 256
+  )
+
+  samples = Array.new(256, 0.0)
+
+  stream.start
+  100.times { stream.write(samples) }
+  stream.stop
+  stream.close
+end
+```
+
+`write` accepts either:
+
+- A packed binary `String`
+- An `Array` of sample values, which is converted according to the configured output format
+
+### Read input and decode it with `PortAudio::Buffer`
+
+```ruby
+PortAudio.with_portaudio do
+  input = PortAudio::Device.default_input
+  raise "No default input device" unless input
+
+  stream = PortAudio::BlockingStream.new(
+    input: { device: input, channels: 1, format: :float32 },
+    sample_rate: input.default_sample_rate,
+    frames_per_buffer: 128
+  )
+
+  stream.start
+  raw = stream.read(128)
+  stream.stop
+  stream.close
+
+  buffer = PortAudio::Buffer.new(frames: 128, channels: 1, format: :float32)
+  buffer.pointer.put_bytes(0, raw)
+
+  p buffer.to_float_array.first(8)
+end
+```
+
+`read` returns raw bytes. `PortAudio::Buffer` is the convenience wrapper for converting those bytes into floats.
+
+## Callback streams
+
+Use `PortAudio::Stream` when PortAudio should pull audio from a callback.
+
+```ruby
+PortAudio.with_portaudio do
+  output = PortAudio::Device.default_output
+  raise "No default output device" unless output
+  remaining_frames = (output.default_sample_rate * 0.2).round
+
+  stream = PortAudio::Stream.new(
+    output: { device: output, channels: 1, format: :float32 },
+    sample_rate: output.default_sample_rate,
+    frames_per_buffer: 128
+  ) do |_input_ptr, output_ptr, frame_count, _time_info, _status_flags, _user_data|
+    samples = Array.new(frame_count) do
+      remaining_frames -= 1 if remaining_frames.positive?
+      0.0
+    end
+
+    output_ptr.put_array_of_float(0, samples)
+    remaining_frames.zero? ? :complete : :continue
+  end
+
+  stream.on_finished { puts "stream finished" }
+
+  stream.start
+  sleep 0.1 while stream.active?
+  stream.close
+
+  raise stream.callback_error if stream.callback_error
+end
+```
+
+Callback return values can be either PortAudio symbols or the normalized Ruby aliases:
+
+- `:paContinue` or `:continue`
+- `:paComplete` or `:complete`
+- `:paAbort` or `:abort`
+
+If the callback raises, the stream aborts and the exception is stored in `stream.callback_error`.
+
+### `Stream.open` convenience helper
+
+Use `PortAudio::Stream.open` to start a stream inside a block and always close it afterward:
+
+```ruby
+PortAudio.with_portaudio do
+  output = PortAudio::Device.default_output
+  raise "No default output device" unless output
+  remaining_frames = (output.default_sample_rate * 0.2).round
+
+  callback = proc do |_input_ptr, output_ptr, frame_count, *_rest|
+    samples = Array.new(frame_count) do
+      remaining_frames -= 1 if remaining_frames.positive?
+      0.0
+    end
+
+    output_ptr.put_array_of_float(0, samples)
+    remaining_frames.zero? ? :complete : :continue
+  end
+
+  PortAudio::Stream.open(
+    output: { device: output, channels: 1, format: :float32 },
+    sample_rate: output.default_sample_rate,
+    frames_per_buffer: 128,
+    callback: callback
+  ) do |stream|
+    stream.start
+    sleep 0.1 while stream.active?
+  end
+end
+```
+
+## Buffer helper
+
+`PortAudio::Buffer` allocates a PortAudio-sized memory region and exposes a few convenience methods:
+
+- `pointer`
+- `bytesize`
+- `write_floats`
+- `to_float_array`
+- `clear`
+
+`to_float_array` and `write_floats` currently support `:float32`, `:int16`, and `:int32`.
+
+## Errors
+
+All negative `PaError` codes are mapped to Ruby exceptions through `PortAudio.check_error!`.
+
+Common examples:
+
+- `PortAudio::InvalidDeviceError`
+- `PortAudio::FormatNotSupportedError`
+- `PortAudio::DeviceUnavailableError`
+- `PortAudio::InputOverflowError`
+- `PortAudio::OutputUnderflowError`
+- `PortAudio::HostApiError`
+
+`PortAudio::HostApiError` also exposes:
+
+- `code`
+- `host_error_info`
+
+If you call low-level functions directly, use `PortAudio.check_error!(code)` on the return value.
+
+## Low-level bindings
+
+The gem exposes low-level PortAudio bindings under:
+
+- `PortAudio::C::Functions`
+- `PortAudio::C::Constants`
+- `PortAudio::C::Enums`
+- `PortAudio::C::Structs`
+
+Platform-specific host API extension bindings are available under `PortAudio::C::HostAPI`:
+
+- `ALSA`
+- `ASIO`
+- `CoreAudio`
+- `DirectSound`
+- `JACK`
+- `PulseAudio`
+- `WASAPI`
+- `WDMKS`
+- `WaveFormat`
+- `WMME`
+
+If the loaded PortAudio library does not export a specific extension symbol, calling that Ruby method raises `PortAudio::UnsupportedFunctionError`.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the default test suite:
+
+```bash
+bundle exec rspec
+bundle exec rake
+```
+
+Integration specs use real audio hardware and are opt-in:
+
+```bash
+PORTAUDIO_RUN_INTEGRATION=1 bundle exec rspec spec/integration
+```
+
+## License
+
+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/host_api_info.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+PortAudio.with_portaudio do
+  apis = PortAudio::HostAPI.all
+
+  if apis.empty?
+    warn "No host APIs detected"
+    next
+  end
+
+  apis.each do |api|
+    puts "#{api.index}: #{api.name} (#{api.type}) devices=#{api.device_count}"
+  end
+end

data/examples/level_meter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+duration_seconds = 1.0
+
+PortAudio.with_portaudio do
+  input = PortAudio::Device.default_input
+  unless input
+    warn "No default input device available"
+    next
+  end
+
+  frames = 256
+  remaining_frames = (input.default_sample_rate * duration_seconds).round
+
+  stream = PortAudio::BlockingStream.new(
+    input: { device: input.index, channels: 1, format: :float32 },
+    sample_rate: input.default_sample_rate,
+    frames_per_buffer: frames
+  )
+
+  begin
+    stream.start
+
+    while remaining_frames.positive?
+      frame_count = [remaining_frames, frames].min
+      raw = stream.read(frame_count)
+      samples = raw.unpack("e*")
+      peak = samples.map(&:abs).max || 0.0
+      bars = (peak * 50).round
+      puts format("%0.3f %s", peak, "#" * bars)
+      remaining_frames -= frame_count
+    end
+  ensure
+    stream.stop if stream.active?
+    stream.close unless stream.closed?
+  end
+end

data/examples/list_devices.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+PortAudio.with_portaudio do
+  devices = PortAudio::Device.all
+
+  if devices.empty?
+    warn "No audio devices detected"
+    next
+  end
+
+  devices.each do |device|
+    puts format("%3d %-40s in=%2d out=%2d rate=%0.1f", device.index, device.name, device.max_input_channels,
+                device.max_output_channels, device.default_sample_rate)
+  end
+end

data/examples/passthrough.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+duration_seconds = 1.0
+
+PortAudio.with_portaudio do
+  input = PortAudio::Device.default_input
+  output = PortAudio::Device.default_output
+  unless input && output
+    warn "No default input/output device available"
+    next
+  end
+
+  sample_rate = [input.default_sample_rate, output.default_sample_rate].min
+  frames = 256
+  remaining_frames = (sample_rate * duration_seconds).round
+
+  stream = PortAudio::BlockingStream.new(
+    input: { device: input.index, channels: 1, format: :float32 },
+    output: { device: output.index, channels: 1, format: :float32 },
+    sample_rate: sample_rate,
+    frames_per_buffer: frames
+  )
+
+  begin
+    stream.start
+
+    while remaining_frames.positive?
+      frame_count = [remaining_frames, frames].min
+      data = stream.read(frame_count)
+      stream.write(data, frame_count)
+      remaining_frames -= frame_count
+    end
+  ensure
+    stream.stop if stream.active?
+    stream.close unless stream.closed?
+  end
+end

data/examples/record_to_file.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+duration_seconds = 1.0
+output_path = "recording.raw.f32"
+
+PortAudio.with_portaudio do
+  input = PortAudio::Device.default_input
+  unless input
+    warn "No default input device available"
+    next
+  end
+
+  sample_rate = input.default_sample_rate
+  frames = 256
+  remaining_frames = (sample_rate * duration_seconds).round
+
+  stream = PortAudio::BlockingStream.new(
+    input: { device: input.index, channels: 1, format: :float32 },
+    sample_rate: sample_rate,
+    frames_per_buffer: frames
+  )
+
+  raw = +""
+
+  begin
+    stream.start
+
+    while remaining_frames.positive?
+      frame_count = [remaining_frames, frames].min
+      raw << stream.read(frame_count)
+      remaining_frames -= frame_count
+    end
+  ensure
+    stream.stop if stream.active?
+    stream.close unless stream.closed?
+  end
+
+  File.binwrite(output_path, raw)
+  puts "Wrote #{output_path} (#{raw.bytesize} bytes)"
+end

data/examples/sine_wave.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "portaudio"
+
+frequency = 440.0
+phase = 0.0
+duration_ms = 2_000
+
+PortAudio.with_portaudio do
+  output = PortAudio::Device.default_output
+  unless output
+    warn "No default output device available"
+    next
+  end
+
+  sample_rate = output.default_sample_rate
+  remaining_frames = (sample_rate * (duration_ms / 1000.0)).round
+
+  stream = PortAudio::Stream.new(
+    output: { device: output.index, channels: 1, format: :float32 },
+    sample_rate: sample_rate,
+    frames_per_buffer: 256
+  ) do |_in_ptr, out_ptr, frame_count, _time_info, _status, _user_data|
+    samples = Array.new(frame_count) do
+      next 0.0 unless remaining_frames.positive?
+
+      value = Math.sin(phase * 2.0 * Math::PI)
+      phase += frequency / sample_rate
+      phase -= 1.0 if phase >= 1.0
+      remaining_frames -= 1
+      value
+    end
+
+    out_ptr.put_array_of_float(0, samples)
+    remaining_frames.zero? ? :paComplete : :paContinue
+  end
+
+  begin
+    stream.start
+    sleep 0.1 while stream.active?
+    raise stream.callback_error if stream.callback_error
+  ensure
+    stream.abort if stream.active?
+    stream.close unless stream.closed?
+  end
+end