native_audio 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf44a7a337d94bcc47dc2cb5904837cd36984e9ea1b80768d1c5f624cc77dc3
-  data.tar.gz: ddaece9c35182a2935d4c1d3f1da13d9dbfb7d4f2c0e41b385da8216b2927b05
+  metadata.gz: 1f5b017594ea0c5b0b94f2e3c36c057ccdd55275c133f5ffc77ef9dfca5a4b7c
+  data.tar.gz: a42b15d0bdf8fa4bfd6f673d3b0f638409653d061e640eb559f433bad2ae6f18
 SHA512:
-  metadata.gz: d11e81e4ecd9de4b8eef28dbcc5a9405e6b366117c11971e74bbaa683ea40ce5751be264d23ca04a0f099e02435f5b84eea405cc0fc0f0f0dc26a07d277622a3
-  data.tar.gz: 71b722055b3d9ed5054bad005470828a691f7d1082723c0237645930a816923d77de97d4a681a89d68bbbb9b8f818cf987b196f761dea9beba874bf7de394839
+  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

@@ -1,80 +1,354 @@
+// ============================================================================
+// native_audio - Ruby audio library using miniaudio
+// ============================================================================
+
 #include <ruby.h>
-#include "extconf.h"
-#include <SDL2/SDL.h>
-#include <SDL2/SDL_mixer.h>
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
 
-Mix_Chunk *sounds[1024];
-int sound_count = 0;
+#define MINIAUDIO_IMPLEMENTATION
+#include "miniaudio.h"
 
-VALUE audio_play(VALUE self, VALUE channel_id, VALUE clip)
+// ============================================================================
+// 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)
 {
-  Mix_Chunk *sound = sounds[NUM2INT(clip)];
-  int channel = Mix_PlayChannel(NUM2INT(channel_id), sound, 0);
-  return rb_int2inum(channel);
+    (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)
 {
-  Mix_Chunk *sound = NULL;
-  sound = Mix_LoadWAV(StringValueCStr(file));
-  if(sound == NULL)
-  {
-    fprintf(stderr, "Unable to load WAV file: %s\n", Mix_GetError());
-  }
+    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;
+    }
 
-  sounds[0] = sound;
-  sound_count++;
+    int id = sound_count;
+    sounds[id] = sound;
+    sound_count++;
 
-  return rb_int2inum(sound_count - 1);
+    return rb_int2inum(id);
 }
 
-VALUE audio_set_pos(VALUE self, VALUE channel_id, VALUE angle, VALUE distance)
+// 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)
 {
-  Mix_SetPosition(NUM2INT(channel_id), NUM2INT(angle), NUM2INT(distance));
-  return Qnil;
+    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)
 {
-  Mix_HaltChannel(NUM2INT(channel_id));
-  return Qnil;
+    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)
 {
-  Mix_Pause(NUM2INT(channel_id));
-  return Qnil;
+    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)
 {
-  Mix_Resume(NUM2INT(channel_id));
-  return Qnil;
+    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)
 {
-  Mix_Volume(NUM2INT(channel_id), NUM2INT(volume));
-  return Qnil;
+    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;
 }
 
-void Init_audio()
+// Audio.set_pitch(channel, pitch) - Set pitch (1.0 = normal)
+VALUE audio_set_pitch(VALUE self, VALUE channel_id, VALUE pitch)
 {
-  if (SDL_Init(SDL_INIT_AUDIO) != 0) { exit(1); }
-
-  int audio_rate = 22050;
-  Uint16 audio_format = AUDIO_S16SYS;
-  int audio_channels = 2;
-  int audio_buffers = 4096;
-
-  if(Mix_OpenAudio(audio_rate, audio_format, audio_channels, audio_buffers) != 0) { exit(1); }
-
-  VALUE mAudio = rb_define_module("Audio");
-  rb_define_singleton_method(mAudio, "load", audio_load, 1);
-  rb_define_singleton_method(mAudio, "play", audio_play, 2);
-  rb_define_singleton_method(mAudio, "set_pos", audio_set_pos, 3);
-  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);
-  rb_define_singleton_method(mAudio, "set_volume", audio_set_volume, 2);
+    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

@@ -1,115 +1,17 @@
 require 'mkmf'
 
-# Get the root directory of the gem (two levels up from ext/audio/)
-ROOT_DIR = File.expand_path('../..', __dir__)
-ASSETS_DIR = File.join(ROOT_DIR, 'assets')
-
-# Detect platform
-PLATFORM = case RUBY_PLATFORM
-when /darwin/ then :macos
-when /linux/  then :linux
-when /mingw/  then :windows
-end
-
-def add_flags(type, flags)
-  case type
-  when :c  then $CFLAGS << " #{flags} "
-  when :ld then $LDFLAGS << " #{flags} "
-  end
+# 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
 
-def check_sdl
-  return if have_library('SDL2') && have_library('SDL2_mixer')
-
-  msg = ["SDL2 libraries not found."]
-
-  if PLATFORM == :linux
-    if system('which apt >/dev/null 2>&1')
-      msg << "Install with: sudo apt install libsdl2-dev libsdl2-mixer-dev"
-    elsif system('which dnf >/dev/null 2>&1') || system('which yum >/dev/null 2>&1')
-      msg << "Install with: sudo dnf install SDL2-devel SDL2_mixer-devel"
-    elsif system('which pacman >/dev/null 2>&1')
-      msg << "Install with: sudo pacman -S sdl2 sdl2_mixer"
-    elsif system('which zypper >/dev/null 2>&1')
-      msg << "Install with: sudo zypper install libSDL2-devel libSDL2_mixer-devel"
-    end
-  end
-
-  abort msg.join("\n")
-end
-
-def set_linux_flags
-  check_sdl
-  add_flags(:ld, "-lSDL2 -lSDL2_mixer -lm")
-end
-
-def use_dev_libs
-  case PLATFORM
-  when :macos
-    add_flags(:c, `sdl2-config --cflags`)
-    add_flags(:c, '-I/opt/homebrew/include')
-    add_flags(:ld, `sdl2-config --libs`)
-    add_flags(:ld, '-lSDL2 -lSDL2_mixer')
-  when :windows
-    add_flags(:ld, '-lSDL2 -lSDL2_mixer')
-  when :linux
-    set_linux_flags
-  end
-end
-
-def use_bundled_libs
-  add_flags(:c, '-std=c11')
-
-  case PLATFORM
-  when :macos
-    add_flags(:c, "-I#{ASSETS_DIR}/include")
-    ldir = "#{ASSETS_DIR}/macos/universal/lib"
-
-    add_flags(:ld, "#{ldir}/libSDL2.a #{ldir}/libSDL2_mixer.a")
-    add_flags(:ld, "#{ldir}/libmpg123.a #{ldir}/libogg.a #{ldir}/libFLAC.a")
-    add_flags(:ld, "#{ldir}/libvorbis.a #{ldir}/libvorbisfile.a #{ldir}/libmodplug.a")
-    add_flags(:ld, "-lz -liconv -lstdc++")
-
-    frameworks = %w[Cocoa Carbon GameController ForceFeedback
-                    AudioToolbox CoreAudio IOKit CoreHaptics CoreVideo Metal]
-    add_flags(:ld, frameworks.map { |f| "-Wl,-framework,#{f}" }.join(' '))
-
-  when :windows
-    add_flags(:c, "-I#{ASSETS_DIR}/include")
-
-    ldir = if RUBY_PLATFORM =~ /ucrt/
-      "#{ASSETS_DIR}/windows/mingw-w64-ucrt-x86_64/lib"
-    else
-      "#{ASSETS_DIR}/windows/mingw-w64-x86_64/lib"
-    end
-
-    add_flags(:ld, "-Wl,--start-group")
-    add_flags(:ld, "#{ldir}/libSDL2.a #{ldir}/libSDL2_mixer.a")
-    add_flags(:ld, "#{ldir}/libmpg123.a #{ldir}/libFLAC.a #{ldir}/libvorbis.a")
-    add_flags(:ld, "#{ldir}/libvorbisfile.a #{ldir}/libogg.a #{ldir}/libmodplug.a")
-    add_flags(:ld, "#{ldir}/libopus.a #{ldir}/libopusfile.a #{ldir}/libsndfile.a")
-    add_flags(:ld, "#{ldir}/libstdc++.a #{ldir}/libz.a")
-    add_flags(:ld, '-lmingw32 -lole32 -loleaut32 -limm32')
-    add_flags(:ld, '-lversion -lwinmm -lrpcrt4 -mwindows -lsetupapi -ldwrite')
-    add_flags(:ld, "-Wl,--end-group")
-
-  when :linux
-    set_linux_flags
-
-  else
-    use_dev_libs
-  end
-end
-
-# Main configuration
-if ARGV.include?('dev')
-  use_dev_libs
-else
-  use_bundled_libs
-end
-
-$CFLAGS.gsub!(/\n/, ' ')
-$LDFLAGS.gsub!(/\n/, ' ')
-
-create_header
 create_makefile('audio')