awaaz 0.1.0

data/lib/awaaz/decoders/wavefile_decoder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Decoders
+    ##
+    # The WavefileDecoder is responsible for decoding `.wav` audio files
+    # into raw PCM data that can be processed by the Awaaz audio pipeline.
+    #
+    # This decoder supports multiple decoding strategies:
+    #
+    # 1. **Soundread** — a Ruby-level `.wav` file reader.
+    # 2. **Shell-based decoding** — for raw audio extraction.
+    #
+    # The decoder will choose a decoding method based on availability
+    # of decoders and the configured options.
+    #
+    # @see Awaaz::Decoders::BaseDecoder
+    # @see Awaaz::Utils::ViaShell
+    #
+    class WavefileDecoder < BaseDecoder
+      include Utils::ViaShell
+
+      # Sets the available decoding options for this decoder.
+      # Defaults to the base options plus the `:soundread` option.
+      #
+      # @!scope class
+      set_available_options default_available_options + [:soundread]
+
+      ##
+      # Loads and decodes a `.wav` file into raw PCM data.
+      #
+      # @raise [AgumentError]
+      #   if the file does not have a `.wav` extension.
+      #
+      # @return [Array<(Numo::NArray, Integer, Integer)>]
+      #   Returns an array containing:
+      #   - samples: A [Numo::NArray] of decoded audio samples
+      #   - sample_rate: Integer sample rate (Hz)
+      #   - channels: Integer number of audio channels
+      #
+      # @note The decoding method is chosen dynamically:
+      #   - If there are no available decoders, or if `:soundread` is enabled,
+      #     it will use the {#soundread} method.
+      #   - Otherwise, it will use shell based decoding.
+      #
+      def load
+        output_data = if no_decoders? || soundread?
+                        soundread
+                      else
+                        shell_load sox_options: { raw: true }
+                      end
+
+        process(*output_data)
+      end
+    end
+  end
+end

data/lib/awaaz/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+##
+# The Awaaz module serves as the top-level namespace for all components
+# of the Awaaz gem, which provides audio decoding, resampling, and analysis tools.
+#
+# This file defines the core exception classes used throughout the library.
+#
+# @see Awaaz::Config for configuration handling
+# @see Awaaz::Decoders for decoder implementations
+#
+module Awaaz
+  ##
+  # Raised when no suitable audio decoder is found on the system.
+  #
+  # This error is typically raised when attempting to decode an audio file
+  # but none of the configured or available decoders (e.g., `mpg123`, `ffmpeg`, `sox`)
+  # are detected or usable.
+  #
+  # @example
+  #   raise Awaaz::DecoderNotFound, "No decoders available"
+  #
+  class DecoderNotFound < ArgumentError; end
+
+  ##
+  # Raised when an error occurs during the resampling process.
+  #
+  # This error generally indicates an issue with the resampling library
+  # or invalid audio data being passed for resampling.
+  #
+  # @example
+  #   raise Awaaz::ResamplingError, "Invalid resampling ratio"
+  #
+  class ResamplingError < StandardError; end
+
+  ##
+  # Raised when the {https://github.com/beetbox/audioread audioread} backend
+  # encounters an error while decoding audio files.
+  #
+  # This can happen when the file format is unsupported or if
+  # the decoding process fails unexpectedly.
+  #
+  # @example
+  #   raise Awaaz::AudioreadError, "Failed to read audio file"
+  #
+  class AudioreadError < StandardError; end
+end

data/lib/awaaz/extensions/extensions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "soundfile"
+require_relative "samplerate"
+
+module Awaaz
+  # The Extensions namespace contains low-level bindings and helper classes
+  # for audio file reading and resampling.
+  #
+  # @note These extensions are generally implemented using {FFI}
+  #   and provide direct access to C libraries like `libsndfile` and `libsamplerate`.
+  #
+  # @see Extensions::Soundfile
+  # @see Extensions::Samplerate
+  module Extensions
+  end
+end

data/lib/awaaz/extensions/samplerate.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Awaaz
+  ##
+  # The Extensions module is a namespace for FFI-based bindings to external libraries.
+  module Extensions
+    ##
+    # The Samplerate module provides Ruby bindings to the `libsamplerate` C library
+    # using the FFI (Foreign Function Interface).
+    #
+    # This module enables high-quality audio resampling directly from Ruby.
+    #
+    # @see https://libsndfile.github.io/libsamplerate/api.html Official libsamplerate API documentation
+    module Samplerate
+      extend FFI::Library
+
+      # Load the libsamplerate shared library
+      ffi_lib "samplerate"
+
+      # rubocop:disable Naming/ClassAndModuleCamelCase
+
+      ##
+      # Structure representing the parameters for a sample rate conversion operation.
+      #
+      # Mirrors the C struct `SRC_DATA` from libsamplerate.
+      #
+      # @!attribute [rw] data_in
+      #   @return [FFI::Pointer] Pointer to the input audio buffer.
+      # @!attribute [rw] data_out
+      #   @return [FFI::Pointer] Pointer to the output audio buffer.
+      # @!attribute [rw] input_frames
+      #   @return [Integer] Number of input frames.
+      # @!attribute [rw] output_frames
+      #   @return [Integer] Number of output frames allocated.
+      # @!attribute [rw] input_frames_used
+      #   @return [Integer] Number of input frames actually used.
+      # @!attribute [rw] output_frames_gen
+      #   @return [Integer] Number of output frames generated.
+      # @!attribute [rw] end_of_input
+      #   @return [Integer] Flag (0 or 1) indicating whether this is the last block of input data.
+      # @!attribute [rw] src_ratio
+      #   @return [Float] Conversion ratio (output_sample_rate / input_sample_rate).
+      class SRC_DATA < FFI::Struct
+        layout :data_in, :pointer,
+               :data_out, :pointer,
+               :input_frames,      :long,
+               :output_frames,     :long,
+               :input_frames_used, :long,
+               :output_frames_gen, :long,
+               :end_of_input,      :int,
+               :src_ratio,         :double
+      end
+
+      # rubocop:enable Naming/ClassAndModuleCamelCase
+
+      ##
+      # Performs a simple sample rate conversion.
+      #
+      attach_function :src_simple, [SRC_DATA.by_ref, :int, :int], :int
+
+      ##
+      # Converts an error code to a human-readable error message.
+      #
+      # @return [String] Human-readable error message.
+      attach_function :src_strerror, [:int], :string
+
+      # --- Converter type constants ---
+
+      # Best quality sinc-based sample rate converter.
+      SRC_SINC_BEST_QUALITY = 0
+
+      # Medium quality sinc-based converter.
+      SRC_SINC_MEDIUM_QUALITY = 1
+
+      # Fastest sinc-based converter (lower quality).
+      SRC_SINC_FASTEST = 2
+
+      # Zero-order hold converter (lowest quality, fastest).
+      SRC_ZERO_ORDER_HOLD = 3
+
+      # Linear interpolation converter (low quality, very fast).
+      SRC_LINEAR = 4
+
+      class << self
+        ##
+        # Maps a symbolic or numeric option to a libsamplerate converter type constant.
+        #
+        # @param option [Integer, Symbol] Converter type, either as an integer constant
+        #   or a symbol (:sinc_best_quality, :linear, etc.).
+        # @return [Integer] The corresponding converter type constant.
+        # @raise [ArgumentError] If the option is not recognized.
+        #
+        # @example Using symbols
+        #   Extensions::Samplerate.resample_option(:sinc_best_quality)
+        #   # => 0
+        #
+        # @example Using integers
+        #   Extensions::Samplerate.resample_option(:linear)
+        #   # => 4
+        def resample_option(option)
+          case option
+          when 0, :sinc_best_quality then SRC_SINC_BEST_QUALITY
+          when 1, :sinc_medium_quality then SRC_SINC_MEDIUM_QUALITY
+          when 2, :sinc_fastest then SRC_SINC_FASTEST
+          when 3, :zero_order_hold then SRC_ZERO_ORDER_HOLD
+          when 4, :linear then SRC_LINEAR
+          else
+            raise ArgumentError, "Not found"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/awaaz/extensions/soundfile.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Awaaz
+  ##
+  # The Extensions module is a namespace for FFI-based bindings to external libraries.
+  module Extensions
+    ##
+    # The Soundfile module provides Ruby bindings to the `libsndfile` C library
+    # using the FFI (Foreign Function Interface).
+    #
+    # It allows reading audio file metadata and sample data directly from Ruby.
+    #
+    # @see http://www.mega-nerd.com/libsndfile/ Official libsndfile documentation
+    module Soundfile
+      extend FFI::Library
+
+      # Load the libsndfile shared library
+      ffi_lib "sndfile"
+
+      ##
+      # Open mode for reading sound files.
+      # @return [Integer] Bitmask flag for read mode.
+      SFM_READ = 0x10
+
+      # rubocop:disable Naming/ClassAndModuleCamelCase
+
+      ##
+      # Structure containing metadata about an audio file.
+      #
+      # Mirrors the C struct `SF_INFO` from libsndfile.
+      #
+      # @!attribute [rw] frames
+      #   @return [Integer] Total number of frames in the file.
+      # @!attribute [rw] samplerate
+      #   @return [Integer] Sample rate of the audio file (Hz).
+      # @!attribute [rw] channels
+      #   @return [Integer] Number of audio channels.
+      # @!attribute [rw] format
+      #   @return [Integer] Format identifier of the audio file.
+      # @!attribute [rw] sections
+      #   @return [Integer] Number of sections in the file.
+      # @!attribute [rw] seekable
+      #   @return [Integer] Whether the file is seekable (1) or not (0).
+      class SF_INFO < FFI::Struct
+        layout :frames, :long_long,
+               :samplerate, :int,
+               :channels,   :int,
+               :format,     :int,
+               :sections,   :int,
+               :seekable,   :int
+      end
+
+      # rubocop:enable Naming/ClassAndModuleCamelCase
+
+      ##
+      # Opens an audio file and returns a pointer to the file handle.
+      #
+      # @see http://www.mega-nerd.com/libsndfile/api.html#open
+      attach_function :sf_open, %i[string int pointer], :pointer
+
+      ##
+      # Reads floating-point audio frames from an open file.
+      #
+      # @return [Integer] Number of frames actually read.
+      attach_function :sf_readf_float, %i[pointer pointer long_long], :long_long
+
+      ##
+      # Closes an open audio file.
+      #
+      # @return [Integer] Zero on success, non-zero on error.
+      attach_function :sf_close, [:pointer], :int
+    end
+  end
+end

data/lib/awaaz/utils/resample.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Utils
+    ##
+    # Resample utilities for audio data represented as Numo::NArray.
+    # Wraps the `libsamplerate` bindings provided by {Extensions::Samplerate}.
+    #
+    # @note This module is intended for internal use, but `read_and_resample_numo`
+    #   is public for advanced users who need manual resampling.
+    module Resample
+      class << self
+        ##
+        # Resamples a Numo::SFloat array of audio samples from one sample rate to another.
+        #
+        # @param input_samples [Numo::SFloat] The audio samples to resample.
+        # @param input_rate [Integer] The original sample rate (Hz).
+        # @param output_rate [Integer] The desired sample rate (Hz).
+        # @param sampling_option [Symbol, Integer] The resampling quality option.
+        #   Can be one of:
+        #     * `:sinc_best_quality` (0)
+        #     * `:sinc_medium_quality` (1)
+        #     * `:sinc_fastest` (2)
+        #     * `:zero_order_hold` (3)
+        #     * `:linear` (4)
+        #
+        # @return [Numo::SFloat] The resampled audio data.
+        #
+        # @raise [ArgumentError] If inputs are invalid or ratio is out of range.
+        # @raise [Awaaz::ResampleError] If `libsamplerate` returns an error.
+        #
+        # @example Resample 44.1kHz mono audio to 48kHz
+        #   samples = Numo::SFloat.new(44100).rand
+        #   new_samples = Awaaz::Utils::Resample.read_and_resample_numo(samples, 44100, 48000)
+        def read_and_resample_numo(input_samples, input_rate, output_rate, sampling_option: :sinc_best_quality)
+          validate_inputs(input_samples, input_rate, output_rate)
+
+          ratio = calculate_ratio(input_rate, output_rate)
+          input_ptr, output_ptr, input_frames, output_frames = prepare_memory(input_samples, ratio)
+
+          data = build_src_data(input_ptr, output_ptr, input_frames, output_frames, ratio)
+          perform_resampling(data, sampling_option)
+
+          convert_to_numo(output_ptr, data[:output_frames_gen])
+        end
+
+        private
+
+        ##
+        # Validates that the provided inputs are of the correct type and configuration.
+        #
+        # @param samples [Numo::NArray] The input samples.
+        # @param input_rate [Integer]
+        # @param output_rate [Integer]
+        #
+        # @raise [ArgumentError] If samples are not a Numo::SFloat array.
+        def validate_inputs(samples, input_rate, output_rate)
+          return if input_rate != output_rate && samples.is_a?(Numo::NArray)
+
+          raise ArgumentError, "Input must be a Numo::SFloat array" unless samples.is_a?(Numo::NArray)
+        end
+
+        ##
+        # Calculates and validates the resampling ratio.
+        #
+        # @param input_rate [Integer]
+        # @param output_rate [Integer]
+        #
+        # @return [Float] The ratio of output_rate to input_rate.
+        # @raise [ArgumentError] If ratio is outside the allowed range.
+        def calculate_ratio(input_rate, output_rate)
+          ratio = output_rate / input_rate.to_f
+          raise ArgumentError, "Bad ratio" if ratio < 1.0 / 256 || ratio > 256
+
+          ratio
+        end
+
+        ##
+        # Allocates and prepares FFI memory for the input and output buffers.
+        #
+        # @param input_samples [Numo::NArray]
+        # @param ratio [Float] The resampling ratio.
+        #
+        # @return [Array<FFI::MemoryPointer, FFI::MemoryPointer, Integer, Integer>]
+        def prepare_memory(input_samples, ratio)
+          input_frames = input_samples.size
+          output_frames = (input_frames * ratio).to_i
+
+          input_ptr = FFI::MemoryPointer.new(:float, input_frames)
+          input_ptr.write_bytes(input_samples.to_string)
+
+          output_ptr = FFI::MemoryPointer.new(:float, output_frames)
+
+          [input_ptr, output_ptr, input_frames, output_frames]
+        end
+
+        ##
+        # Builds the {Extensions::Samplerate::SRC_DATA} struct for `libsamplerate`.
+        #
+        # @param input_ptr [FFI::MemoryPointer]
+        # @param output_ptr [FFI::MemoryPointer]
+        # @param input_frames [Integer]
+        # @param output_frames [Integer]
+        # @param ratio [Float]
+        #
+        # @return [Extensions::Samplerate::SRC_DATA]
+        def build_src_data(input_ptr, output_ptr, input_frames, output_frames, ratio)
+          Extensions::Samplerate::SRC_DATA.new.tap do |data|
+            data[:data_in] = input_ptr
+            data[:data_out] = output_ptr
+            data[:input_frames] = input_frames
+            data[:output_frames] = output_frames
+            data[:end_of_input] = 1
+            data[:src_ratio] = ratio
+          end
+        end
+
+        ##
+        # Performs the resampling using `libsamplerate`.
+        #
+        # @param data [Extensions::Samplerate::SRC_DATA]
+        # @param sampling_option [Symbol, Integer]
+        #
+        # @raise [Awaaz::ResampleError] If resampling fails.
+        def perform_resampling(data, sampling_option)
+          err = Extensions::Samplerate.src_simple(data, Extensions::Samplerate.resample_option(sampling_option), 1)
+          raise Awaaz::ResampleError, "Resampling failed: #{Extensions::Samplerate.src_strerror(err)}" if err != 0
+        end
+
+        ##
+        # Converts the output FFI pointer back into a Numo::SFloat array.
+        #
+        # @param output_ptr [FFI::MemoryPointer]
+        # @param size [Integer] Number of frames generated.
+        #
+        # @return [Numo::SFloat]
+        def convert_to_numo(output_ptr, size)
+          Numo::SFloat.cast(output_ptr.read_array_of_float(size))
+        end
+      end
+    end
+  end
+end

data/lib/awaaz/utils/shell_command_builder.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Utils
+    ##
+    # A utility class to construct shell commands in a safe and composable way.
+    #
+    # This class supports chaining methods to add arguments, flags, and options,
+    # and finally output the full shell command string.
+    #
+    # @example Build a simple FFmpeg command
+    #   cmd = ShellCommandBuilder.new(:ffmpeg)
+    #            .add_flag("-nostdin")
+    #            .add_option("-i", "input.mp3")
+    #            .add_option("-ar", 44100)
+    #            .command
+    #   # => "ffmpeg -nostdin -i input.mp3 -ar 44100"
+    #
+    class ShellCommandBuilder
+      ##
+      # Initializes a new shell command builder.
+      #
+      # @param base [String, Symbol, nil] The base command (e.g., `:ffmpeg` or `"ls"`).
+      #
+      def initialize(base = nil)
+        @args = [base.to_s]
+      end
+
+      ##
+      # Adds a positional argument to the command.
+      #
+      # @param arg [String, Symbol, Numeric] The argument to add.
+      # @return [ShellCommandBuilder] self, for chaining.
+      #
+      def add_arg(arg)
+        @args << arg.to_s.strip
+        self
+      end
+
+      ##
+      # Alias for {#add_arg}, used for flags.
+      #
+      # @see #add_arg
+      alias add_flag add_arg
+
+      ##
+      # Adds an option with a value to the command.
+      #
+      # @param option [String, Symbol] The option flag (e.g., `-i`).
+      # @param value [String, Symbol, Numeric] The value for the option.
+      # @param with_colon [Boolean] Whether to separate the option and value with a colon (`:`)
+      #   instead of a space.
+      # @return [ShellCommandBuilder] self, for chaining.
+      #
+      # @example Space-separated
+      #   builder.add_option("-i", "file.mp3")
+      #   # => "-i file.mp3"
+      #
+      # @example Colon-separated
+      #   builder.add_option("--volume", 10, with_colon: true)
+      #   # => "--volume:10"
+      #
+      def add_option(option, value, with_colon: false)
+        @args << "#{option}#{with_colon ? ":" : " "}#{value}"
+        self
+      end
+
+      ##
+      # Adds multiple arguments or options at once.
+      #
+      # @param args_array [Array<Array>] An array of argument definitions.
+      #   Each element should be `[type, args]` where:
+      #   - `type` is `:arg` or `:flag` for positional arguments/flags
+      #   - otherwise, treated as an option for {#add_option}
+      #
+      # @return [ShellCommandBuilder] self, for chaining.
+      #
+      # @example Adding multiple
+      #   builder.add_multiple_args([
+      #     [:flag, ["-q"]],
+      #     [:option, ["-i", "file.mp3"]],
+      #     [:arg, ["extra"]]
+      #   ])
+      #
+      def add_multiple_args(args_array)
+        args_array.each do |shell_args|
+          arg_type, args = shell_args
+          arg_type = arg_type.to_sym
+          %i[arg flag].include?(arg_type) ? add_arg(*args) : add_option(*args)
+        end
+        self
+      end
+
+      ##
+      # Builds and returns the complete shell command string.
+      #
+      # @return [String] The constructed command.
+      #
+      def command
+        @args.join(" ")
+      end
+    end
+  end
+end

data/lib/awaaz/utils/sound_config.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Utils
+    ##
+    # SoundConfig holds and validates configuration options used for audio processing.
+    #
+    # It ensures that only valid options are passed in and provides convenience
+    # accessors for common audio processing settings such as sample rate, channel count,
+    # amplification factor, and decoder preferences.
+    #
+    # @example Creating a SoundConfig with valid options
+    #   valid_keys = [:sample_rate, :mono, :amplification_factor, :decoder]
+    #   config = Awaaz::Utils::SoundConfig.new(valid_keys, sample_rate: 44100, mono: true)
+    #
+    class SoundConfig
+      ##
+      # Initializes a new SoundConfig instance.
+      #
+      # @param valid_options [Array<Symbol,String>] The list of allowed option keys.
+      # @param options [Hash] The configuration options to store.
+      # @option options [Integer] :sample_rate The audio sample rate in Hz.
+      # @option options [Boolean] :mono Whether to process audio in mono (true) or stereo (false).
+      # @option options [Boolean] :soundread Whether to use soundread for processing.
+      # @option options [Integer] :amplification_factor The amplification factor (default: 32768).
+      # @option options [Symbol,String] :decoder The preferred audio decoder.
+      #
+      # @raise [ArgumentError] If any provided option key is not in +valid_options+.
+      #
+      def initialize(valid_options, **options)
+        @options = options
+        @valid_options = valid_options
+
+        prepare
+      end
+
+      ##
+      # The sample rate for audio processing.
+      #
+      # @return [Integer] The sample rate in Hz (default: 22050).
+      #
+      def sample_rate
+        from_options(:sample_rate) || 22_050
+      end
+
+      ##
+      # Whether to process audio in mono.
+      #
+      # @return [Boolean] +true+ if mono, otherwise +false+.
+      #
+      def mono
+        from_options(:mono) || false
+      end
+
+      ##
+      # Convenience method to check if audio is mono.
+      #
+      # @return [Boolean]
+      #
+      def mono?
+        mono
+      end
+
+      ##
+      # Convenience method to check if audio is stereo.
+      #
+      # @return [Boolean]
+      #
+      def stereo?
+        !mono?
+      end
+
+      ##
+      # Whether to use soundread for audio processing.
+      #
+      # @return [Boolean]
+      #
+      def soundread?
+        from_options(:soundread) == true
+      end
+
+      ##
+      # The number of audio channels.
+      #
+      # @return [Integer] 1 for mono, 2 for stereo.
+      #
+      def num_channels
+        mono? ? 1 : 2
+      end
+
+      ##
+      # The amplification factor for audio processing.
+      #
+      # @return [Integer] Defaults to 32768.
+      #
+      def amplification_factor
+        (from_options(:amplification_factor) || 32_768).to_i
+      end
+
+      ##
+      # The preferred audio decoder.
+      #
+      # @return [Symbol, nil] The decoder symbol if set, otherwise +nil+.
+      #
+      def decoder_option
+        from_options(:decoder)&.to_sym
+      end
+
+      private
+
+      ##
+      # Fetches a value from @options using either symbol or string key.
+      #
+      # @param key [Symbol,String] The key to look up.
+      # @return [Object, nil] The value if present, otherwise +nil+.
+      #
+      def from_options(key)
+        @options[key.to_s] || @options[key.to_sym]
+      end
+
+      ##
+      # Validates that all provided options are in the allowed list.
+      #
+      # @raise [ArgumentError] If any provided key is invalid.
+      #
+      def prepare
+        @options.each_key do |key|
+          next if @valid_options.include?(key.to_sym) || @valid_options.include?(key.to_s)
+
+          raise ArgumentError, "Invalid key passed: #{key}. Possible keys: #{@valid_options.join(",")}"
+        end
+      end
+    end
+  end
+end