native_audio 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa64178bae1a55555de56fc3e8faedcd719472d81d72fe0768672aa69701cb8f
-  data.tar.gz: 5ae18b3ba3e5f20f09877b261513654afa88cd1a050ed0754b9d198fec0f9c4e
+  metadata.gz: 1f5b017594ea0c5b0b94f2e3c36c057ccdd55275c133f5ffc77ef9dfca5a4b7c
+  data.tar.gz: a42b15d0bdf8fa4bfd6f673d3b0f638409653d061e640eb559f433bad2ae6f18
 SHA512:
-  metadata.gz: c20e84e9d147faa6f8ac31e32a0ad1152a4d66b28f3c8f4868e56743f4b0a68ee9191b69bef0e650d3fb451d4310d79412d5fb1dfda45639af5768b6f6aa861c
-  data.tar.gz: d46152b36dc8f120b52df2af64b1cca301b06fcf0c2685e72dc3d4cfd14df8020bd83f4b311c5cad0404241f649d290d789a96b33088b05cea5d6f48f9f066c8
+  metadata.gz: cb6eb51f84784da896c21258f32393014845d5dcf47109e0ddc83f972c43e3353431c0addb42a8b9c14fed5397f9a8aaf1ce372549e7a321961a715afa577ceb
+  data.tar.gz: 82fe331ea3a1adb7a6281afe2978c62f7b9fc37c9836ed7ededda965034237af0a7acd54ca313973bb12ed1b22127d504981c70391ce0377ccf51898da99399a

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,87 @@
+# What is native_audio?
+
+Native audio is a thin wrapper around miniaudio for simple audio playback from Ruby.
+
+## 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
+audio_source = NativeAudio::AudioSource.new(clip)
+
+# Play the clip
+audio_source.play
+
+# Pause and resume
+audio_source.pause
+audio_source.resume
+
+# Set pitch (1.0 = normal, 0.5 = octave down, 2.0 = octave up)
+audio_source.set_pitch(1.5)
+
+# Set position relative to listener (angle: 0-360, distance: 0-255)
+audio_source.set_pos(90, 200)  # right side, mid distance
+
+# Set volume (0-128)
+audio_source.set_volume(64)
+
+# Stop the clip
+audio_source.stop
+```
+
+## 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"

data/ext/audio/audio.c

@@ -0,0 +1,354 @@
+// ============================================================================
+// native_audio - Ruby audio library using miniaudio
+// ============================================================================
+
+#include <ruby.h>
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define MINIAUDIO_IMPLEMENTATION
+#include "miniaudio.h"
+
+// ============================================================================
+// Constants & Globals
+// ============================================================================
+
+#define MAX_SOUNDS 1024
+#define MAX_CHANNELS 1024
+
+static ma_engine engine;
+static ma_context context;
+static ma_sound *sounds[MAX_SOUNDS];      // Loaded audio clips
+static ma_sound *channels[MAX_CHANNELS];  // Playback instances
+static int sound_count = 0;
+static int engine_initialized = 0;
+static int context_initialized = 0;
+static int using_null_backend = 0;
+
+// ============================================================================
+// Cleanup (called on Ruby exit)
+// ============================================================================
+
+static void cleanup_audio(VALUE unused)
+{
+    (void)unused;
+
+    if (!engine_initialized) {
+        return;
+    }
+
+    // Stop and clean up all channels
+    for (int i = 0; i < MAX_CHANNELS; i++) {
+        if (channels[i] != NULL) {
+            ma_sound_stop(channels[i]);
+            ma_sound_uninit(channels[i]);
+            free(channels[i]);
+            channels[i] = NULL;
+        }
+    }
+
+    // Stop and clean up all loaded sounds
+    for (int i = 0; i < sound_count; i++) {
+        if (sounds[i] != NULL) {
+            ma_sound_stop(sounds[i]);
+            ma_sound_uninit(sounds[i]);
+            free(sounds[i]);
+            sounds[i] = NULL;
+        }
+    }
+
+    // On Windows, ma_engine_uninit crashes with the null backend
+    // Since null backend has no real resources, we can skip cleanup
+#ifdef _WIN32
+    if (using_null_backend) {
+        engine_initialized = 0;
+        context_initialized = 0;
+        return;
+    }
+#endif
+
+    ma_engine_uninit(&engine);
+    engine_initialized = 0;
+
+    if (context_initialized) {
+        ma_context_uninit(&context);
+        context_initialized = 0;
+    }
+}
+
+// ============================================================================
+// Audio Loading
+// ============================================================================
+
+// Audio.load(path) - Load an audio file, returns clip ID
+VALUE audio_load(VALUE self, VALUE file)
+{
+    const char *path = StringValueCStr(file);
+
+    ma_sound *sound = (ma_sound *)malloc(sizeof(ma_sound));
+    if (sound == NULL) {
+        rb_raise(rb_eRuntimeError, "Failed to allocate memory for sound");
+        return Qnil;
+    }
+
+    ma_result result = ma_sound_init_from_file(&engine, path, MA_SOUND_FLAG_DECODE, NULL, NULL, sound);
+    if (result != MA_SUCCESS) {
+        free(sound);
+        rb_raise(rb_eRuntimeError, "Failed to load audio file: %s", path);
+        return Qnil;
+    }
+
+    int id = sound_count;
+    sounds[id] = sound;
+    sound_count++;
+
+    return rb_int2inum(id);
+}
+
+// Audio.duration(clip) - Get duration of clip in seconds
+VALUE audio_duration(VALUE self, VALUE clip)
+{
+    int clip_id = NUM2INT(clip);
+
+    if (clip_id < 0 || clip_id >= sound_count || sounds[clip_id] == NULL) {
+        rb_raise(rb_eArgError, "Invalid clip ID: %d", clip_id);
+        return Qnil;
+    }
+
+    float length;
+    ma_result result = ma_sound_get_length_in_seconds(sounds[clip_id], &length);
+    if (result != MA_SUCCESS) {
+        return Qnil;
+    }
+
+    return rb_float_new(length);
+}
+
+// ============================================================================
+// Playback Controls
+// ============================================================================
+
+// Audio.play(channel, clip) - Play a clip on a channel
+VALUE audio_play(VALUE self, VALUE channel_id, VALUE clip)
+{
+    int channel = NUM2INT(channel_id);
+    int clip_id = NUM2INT(clip);
+
+    if (clip_id < 0 || clip_id >= sound_count || sounds[clip_id] == NULL) {
+        rb_raise(rb_eArgError, "Invalid clip ID: %d", clip_id);
+        return Qnil;
+    }
+
+    if (channel < 0 || channel >= MAX_CHANNELS) {
+        rb_raise(rb_eArgError, "Invalid channel ID: %d", channel);
+        return Qnil;
+    }
+
+    // Clean up existing sound on this channel
+    if (channels[channel] != NULL) {
+        ma_sound_stop(channels[channel]);
+        ma_sound_uninit(channels[channel]);
+        free(channels[channel]);
+        channels[channel] = NULL;
+    }
+
+    // Create a copy of the sound for playback
+    ma_sound *playback = (ma_sound *)malloc(sizeof(ma_sound));
+    if (playback == NULL) {
+        rb_raise(rb_eRuntimeError, "Failed to allocate memory for playback");
+        return Qnil;
+    }
+
+    ma_result result = ma_sound_init_copy(&engine, sounds[clip_id], 0, NULL, playback);
+    if (result != MA_SUCCESS) {
+        free(playback);
+        rb_raise(rb_eRuntimeError, "Failed to create sound copy for playback");
+        return Qnil;
+    }
+
+    channels[channel] = playback;
+    ma_sound_start(playback);
+
+    return rb_int2inum(channel);
+}
+
+// Audio.stop(channel) - Stop playback and rewind
+VALUE audio_stop(VALUE self, VALUE channel_id)
+{
+    int channel = NUM2INT(channel_id);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    ma_sound_stop(channels[channel]);
+    ma_sound_seek_to_pcm_frame(channels[channel], 0);
+
+    return Qnil;
+}
+
+// Audio.pause(channel) - Pause playback
+VALUE audio_pause(VALUE self, VALUE channel_id)
+{
+    int channel = NUM2INT(channel_id);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    ma_sound_stop(channels[channel]);
+
+    return Qnil;
+}
+
+// Audio.resume(channel) - Resume playback
+VALUE audio_resume(VALUE self, VALUE channel_id)
+{
+    int channel = NUM2INT(channel_id);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    ma_sound_start(channels[channel]);
+
+    return Qnil;
+}
+
+// ============================================================================
+// Audio Effects
+// ============================================================================
+
+// Audio.set_volume(channel, volume) - Set volume (0-128)
+VALUE audio_set_volume(VALUE self, VALUE channel_id, VALUE volume)
+{
+    int channel = NUM2INT(channel_id);
+    int vol = NUM2INT(volume);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    float normalized_volume = vol / 128.0f;
+    ma_sound_set_volume(channels[channel], normalized_volume);
+
+    return Qnil;
+}
+
+// Audio.set_pitch(channel, pitch) - Set pitch (1.0 = normal)
+VALUE audio_set_pitch(VALUE self, VALUE channel_id, VALUE pitch)
+{
+    int channel = NUM2INT(channel_id);
+    float p = (float)NUM2DBL(pitch);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    ma_sound_set_pitch(channels[channel], p);
+
+    return Qnil;
+}
+
+// Audio.set_pos(channel, angle, distance) - Set 3D position
+// angle: 0=front, 90=right, 180=back, 270=left
+// distance: 0=close, 255=far
+VALUE audio_set_pos(VALUE self, VALUE channel_id, VALUE angle, VALUE distance)
+{
+    int channel = NUM2INT(channel_id);
+    int ang = NUM2INT(angle);
+    int dist = NUM2INT(distance);
+
+    if (channel < 0 || channel >= MAX_CHANNELS || channels[channel] == NULL) {
+        return Qnil;
+    }
+
+    // Convert polar to cartesian
+    float rad = ang * (MA_PI / 180.0f);
+    float normalized_dist = dist / 255.0f;
+    float x = normalized_dist * sinf(rad);
+    float z = -normalized_dist * cosf(rad);
+
+    ma_sound_set_position(channels[channel], x, 0.0f, z);
+
+    return Qnil;
+}
+
+// ============================================================================
+// Engine Initialization
+// ============================================================================
+
+// Audio.init - Initialize the audio engine
+VALUE audio_init(VALUE self)
+{
+    if (engine_initialized) {
+        return Qnil;
+    }
+
+    // Check for null driver (for CI environments without audio devices)
+    // Usage: NATIVE_AUDIO_DRIVER=null ruby script.rb
+    const char *driver = getenv("NATIVE_AUDIO_DRIVER");
+    int use_null = (driver != NULL && strcmp(driver, "null") == 0);
+
+    ma_engine_config config = ma_engine_config_init();
+    config.listenerCount = 1;
+
+    if (use_null) {
+        ma_backend backends[] = { ma_backend_null };
+        ma_result ctx_result = ma_context_init(backends, 1, NULL, &context);
+        if (ctx_result != MA_SUCCESS) {
+            rb_raise(rb_eRuntimeError, "Failed to initialize null audio context");
+            return Qnil;
+        }
+        context_initialized = 1;
+        using_null_backend = 1;
+        config.pContext = &context;
+    }
+
+    ma_result result = ma_engine_init(&config, &engine);
+
+    if (result != MA_SUCCESS) {
+        if (context_initialized) {
+            ma_context_uninit(&context);
+            context_initialized = 0;
+        }
+        rb_raise(rb_eRuntimeError, "Failed to initialize audio engine");
+        return Qnil;
+    }
+
+    engine_initialized = 1;
+    rb_set_end_proc(cleanup_audio, Qnil);
+
+    return Qnil;
+}
+
+// ============================================================================
+// Ruby Module Setup
+// ============================================================================
+
+void Init_audio(void)
+{
+    for (int i = 0; i < MAX_SOUNDS; i++) sounds[i] = NULL;
+    for (int i = 0; i < MAX_CHANNELS; i++) channels[i] = NULL;
+
+    VALUE mAudio = rb_define_module("Audio");
+
+    // Initialization
+    rb_define_singleton_method(mAudio, "init", audio_init, 0);
+
+    // Loading
+    rb_define_singleton_method(mAudio, "load", audio_load, 1);
+    rb_define_singleton_method(mAudio, "duration", audio_duration, 1);
+
+    // Playback
+    rb_define_singleton_method(mAudio, "play", audio_play, 2);
+    rb_define_singleton_method(mAudio, "stop", audio_stop, 1);
+    rb_define_singleton_method(mAudio, "pause", audio_pause, 1);
+    rb_define_singleton_method(mAudio, "resume", audio_resume, 1);
+
+    // Effects
+    rb_define_singleton_method(mAudio, "set_volume", audio_set_volume, 2);
+    rb_define_singleton_method(mAudio, "set_pitch", audio_set_pitch, 2);
+    rb_define_singleton_method(mAudio, "set_pos", audio_set_pos, 3);
+}

data/ext/audio/extconf.rb

@@ -0,0 +1,17 @@
+require 'mkmf'
+
+# miniaudio linking requirements per platform:
+# - macOS:   CoreFoundation, CoreAudio, AudioToolbox frameworks
+# - Linux:   pthread, dl, m (math)
+# - Windows: uses native APIs via runtime linking, no extra libs needed
+
+case RUBY_PLATFORM
+when /darwin/
+  $LDFLAGS << " -framework CoreFoundation -framework CoreAudio -framework AudioToolbox "
+when /linux/
+  $LDFLAGS << " -ldl -lpthread -lm "
+when /mingw|mswin/
+  # Windows uses runtime linking to native audio APIs
+end
+
+create_makefile('audio')