native_audio 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf44a7a337d94bcc47dc2cb5904837cd36984e9ea1b80768d1c5f624cc77dc3
-  data.tar.gz: ddaece9c35182a2935d4c1d3f1da13d9dbfb7d4f2c0e41b385da8216b2927b05
+  metadata.gz: a9a953a3fe6e4bd23e99278c28dbd273bc08268105382a4dae34854e3917aa64
+  data.tar.gz: af2a5c84a91fa2957984d4c36637bbe914f38fab7d26903406051eb2456dbc96
 SHA512:
-  metadata.gz: d11e81e4ecd9de4b8eef28dbcc5a9405e6b366117c11971e74bbaa683ea40ce5751be264d23ca04a0f099e02435f5b84eea405cc0fc0f0f0dc26a07d277622a3
-  data.tar.gz: 71b722055b3d9ed5054bad005470828a691f7d1082723c0237645930a816923d77de97d4a681a89d68bbbb9b8f818cf987b196f761dea9beba874bf7de394839
+  metadata.gz: '094beb2919f1a5e0b9e18ea7ac5e5776f5f5ed5eb213f9aac5c976ec3e74cb740ba73632f3bab2acb589afc4d2f12a1fe8485b3ddd59b5bc71d8d21fa758f357'
+  data.tar.gz: b0c335b765410df6cfbae2a730f921388e5761639f96b329113ef398527dd46f9067680a55e0fb7541cf801784158f07b744f07e9570251ea0485503b573c81f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Max Hatfull
+
+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,152 @@
+# What is native_audio?
+
+Native audio is a thin wrapper around miniaudio for simple audio playback from Ruby, with built-in support for delay and reverb effects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'native_audio'
+```
+And then execute:
+
+    $ bundle
+
+## Usage
+
+```ruby
+require 'native_audio'
+
+# Load a clip
+clip = NativeAudio::Clip.new('path/to/sound.wav')
+
+# Check duration
+clip.duration  # => seconds
+
+# Create an audio source to manage playback
+source = NativeAudio::AudioSource.new(clip)
+
+# Play the clip
+source.play
+
+# Pause and resume
+source.pause
+source.resume
+
+# Set pitch (1.0 = normal, 0.5 = octave down, 2.0 = octave up)
+source.set_pitch(1.5)
+
+# Set position relative to listener (angle: 0-360, distance: 0-255)
+source.set_pos(90, 200)  # right side, mid distance
+
+# Set volume (0-128)
+source.set_volume(64)
+
+# Loop playback
+source.set_looping(true)
+
+# Stop the clip
+source.stop
+```
+
+## Effects
+
+Each audio source has a built-in effects chain:
+
+```
+sound ──▶ delay ──▶ reverb ──▶ output
+```
+
+### Delay Taps
+
+Add discrete echo effects with up to 16 taps per source:
+
+```ruby
+source.play
+
+# Add delay taps (returns a DelayTap object)
+tap1 = source.add_delay_tap(time_ms: 200, volume: 0.5)
+tap2 = source.add_delay_tap(time_ms: 400, volume: 0.3)
+
+# Modify taps at runtime
+tap1.volume = 0.4
+tap1.time_ms = 250
+
+# Remove a tap
+tap2.remove
+
+# Query active taps
+source.delay_taps  # => [tap1]
+```
+
+### Reverb
+
+Add room ambience with a Schroeder reverb:
+
+```ruby
+source.play
+
+# Enable reverb with custom settings
+source.set_reverb(
+  room_size: 0.7,  # 0.0 = small room, 1.0 = large hall
+  damping: 0.5,    # 0.0 = bright, 1.0 = muffled
+  wet: 0.4,        # reverb signal level
+  dry: 1.0         # original signal level
+)
+
+# Or just enable with defaults
+source.enable_reverb
+source.enable_reverb(false)  # disable
+```
+
+### Combining Effects
+
+Delay and reverb work together - each echo gets reverb applied:
+
+```ruby
+source.play
+
+# Slapback echo with room reverb
+source.add_delay_tap(time_ms: 150, volume: 0.4)
+source.set_reverb(room_size: 0.5, wet: 0.3, dry: 1.0)
+```
+
+## Environment Variables
+
+### `NATIVE_AUDIO_DRIVER`
+
+Set `NATIVE_AUDIO_DRIVER=null` to use miniaudio's null backend. This initializes the audio engine but outputs no sound - useful for CI/testing on systems without audio hardware.
+
+```bash
+NATIVE_AUDIO_DRIVER=null ruby your_script.rb
+```
+
+### `DUMMY_AUDIO_BACKEND`
+
+Set `DUMMY_AUDIO_BACKEND=true` to bypass miniaudio entirely and use a pure Ruby dummy backend. The C extension still loads (validating it compiles correctly), but no audio engine is initialized and all audio calls are no-ops.
+
+```bash
+DUMMY_AUDIO_BACKEND=true ruby your_script.rb
+```
+
+> **Note:** On Windows Server (e.g., GitHub Actions runners), miniaudio's null backend crashes due to threading issues in headless environments. Use `DUMMY_AUDIO_BACKEND=true` instead. macOS and Linux work fine with `NATIVE_AUDIO_DRIVER=null`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake compile
+```
+
+To test:
+
+```bash
+ruby test_audio.rb
+```
+
+## Releasing
+
+1. Update the version in `native_audio.gemspec`
+2. Go to GitHub Actions → "Release to RubyGems"
+3. Click "Run workflow" → "Run workflow"