awaaz 0.1.0

data/lib/awaaz/utils/soundread.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Utils
+    ##
+    # A utility class for reading and optionally resampling audio files.
+    #
+    # This class supports reading `.wav` files using {Extensions::Soundfile}
+    # and can automatically resample them using {Utils::Resample}.
+    #
+    # @example Read and resample a WAV file
+    #   reader = Awaaz::Utils::Soundread.new("audio.wav", resample_options: { output_rate: 44100 })
+    #   samples, channels, rate = reader.read
+    #
+    # @note Currently, only `.wav` files are supported.
+    #
+    class Soundread
+      ##
+      # Supported audio file extensions.
+      #
+      # @return [Array<String>] List of supported file extensions.
+      #
+      SUPPORTED_EXTENSIONS = %w[.wav].freeze
+
+      ##
+      # Creates a new Soundread instance.
+      #
+      # @param filename [String] Path to the audio file to read.
+      # @param resample_options [Hash] Options for resampling the audio.
+      #   - `:output_rate` [Integer] Output sample rate (default: `22050`)
+      #   - `:sampling_option` [Symbol] Resampling algorithm (default: `:sinc_fastest`)
+      #
+      def initialize(filename, resample_options: default_resample_options)
+        @filename = filename
+        @resample_options = resample_options || {}
+      end
+
+      ##
+      # Reads the audio file, returning its samples and metadata.
+      #
+      # @return [Array<(Numo::SFloat, Integer, Integer)>]
+      #   A tuple containing:
+      #   - samples [Numo::SFloat] — Audio samples as a Numo array.
+      #   - channels [Integer] — Number of channels in the audio.
+      #   - output_rate [Integer] — Sample rate of the returned audio.
+      #
+      # @raise [ArgumentError] If the file extension is unsupported.
+      # @raise [Awaaz::AudioreadError] If the file cannot be opened.
+      #
+      def read
+        validate_support
+        soundfile, sample_rate, frames, channels = open_file
+        samples = parse_soundfile(soundfile, frames, channels)
+        close_soundfile(soundfile)
+
+        resample(samples, sample_rate, channels)
+      end
+
+      private
+
+      ##
+      # Default resampling options.
+      #
+      # @return [Hash] Default options with `:output_rate => 22050`.
+      #
+      def default_resample_options
+        { output_rate: 22_050 }
+      end
+
+      ##
+      # Ensures the file format is supported.
+      #
+      # @raise [ArgumentError] If the file extension is not in {SUPPORTED_EXTENSIONS}.
+      #
+      def validate_support
+        return if supported?
+
+        raise ArgumentError, "File extension not supported. Supported files: #{SUPPORTED_EXTENSIONS.join(",")}"
+      end
+
+      ##
+      # Checks if the file extension is supported.
+      #
+      # @return [Boolean] `true` if supported, `false` otherwise.
+      #
+      def supported?
+        SUPPORTED_EXTENSIONS.include?(File.extname(@filename))
+      end
+
+      ##
+      # Opens the audio file for reading.
+      #
+      # @return [Array<(FFI::Pointer, Integer, Integer, Integer)>]
+      #   A tuple containing:
+      #   - soundfile [FFI::Pointer] — Pointer to the opened sound file.
+      #   - sample_rate [Integer] — Sample rate of the audio file.
+      #   - frames [Integer] — Number of frames in the file.
+      #   - channels [Integer] — Number of channels in the file.
+      #
+      # @raise [Awaaz::AudioreadError] If the file cannot be opened.
+      #
+      def open_file
+        info = Extensions::Soundfile::SF_INFO.new
+        sndfile = Extensions::Soundfile.sf_open(@filename, Extensions::Soundfile::SFM_READ, info.to_ptr)
+
+        raise Awaaz::AudioreadError, "Could not read the audio file" if sndfile.null?
+
+        sample_rate = info[:samplerate]
+        frames = info[:frames]
+        channels = info[:channels]
+        [sndfile, sample_rate, frames, channels]
+      end
+
+      ##
+      # Reads the raw samples from the file and converts them into a Numo array.
+      #
+      # @param soundfile [FFI::Pointer] Open sound file pointer.
+      # @param frames [Integer] Number of frames to read.
+      # @param channels [Integer] Number of channels in the file.
+      # @return [Numo::SFloat] The audio samples.
+      #
+      def parse_soundfile(soundfile, frames, channels)
+        buffer = FFI::MemoryPointer.new(:float, frames * channels)
+        read_frames = Extensions::Soundfile.sf_readf_float(soundfile, buffer, frames)
+        Numo::SFloat.cast(buffer.read_array_of_float(read_frames * channels))
+      end
+
+      ##
+      # Closes the open sound file.
+      #
+      # @param soundfile [FFI::Pointer] Open sound file pointer.
+      # @return [void]
+      #
+      def close_soundfile(soundfile)
+        Extensions::Soundfile.sf_close(soundfile)
+      end
+
+      ##
+      # Resamples the audio if necessary.
+      #
+      # @param samples [Numo::SFloat] The input samples.
+      # @param sample_rate [Integer] Original sample rate.
+      # @param channels [Integer] Number of channels.
+      # @return [Array<(Numo::SFloat, Integer, Integer)>]
+      #
+      # @raise [ArgumentError] If an invalid resample option key is passed.
+      #
+      def resample(samples, sample_rate, channels)
+        valid_options = %i[output_rate sampling_option]
+
+        @resample_options.transform_keys!(&:to_sym)
+        @resample_options.each_key do |key|
+          next if valid_options.include?(key)
+
+          raise ArgumentError, "Invalid option: #{key}. Available options: #{valid_options.join}"
+        end
+
+        output_rate, sampling_option = @resample_options.values_at(:output_rate, :sampling_rate)
+        sampling_option ||= :sinc_fastest
+
+        [
+          Utils::Resample.read_and_resample_numo(samples, sample_rate, output_rate, sampling_option:),
+          channels,
+          output_rate
+        ]
+      end
+    end
+  end
+end

data/lib/awaaz/utils/utils.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# This namespace contains utility classes and modules
+# used internally by the Awaaz gem for audio processing.
+#
+# It requires and consolidates helper modules for resampling,
+# sample manipulation, configuration, file reading, shell command
+# building, and shell-based audio operations.
+#
+# @see Awaaz
+# @since 0.1.0
+#
+# @example Accessing a utility class
+#   Awaaz::Utils::Soundread.new("file.wav").read
+#
+require_relative "resample"
+require_relative "sound_config"
+require_relative "soundread"
+require_relative "shell_command_builder"
+require_relative "via_shell"
+
+module Awaaz
+  # The Utils module provides low-level helper components
+  # for performing core audio-related operations in the Awaaz gem.
+  #
+  # These utilities are generally not intended for direct use by
+  # consumers of the gem, but may be useful for advanced integrations.
+  module Utils
+  end
+end

data/lib/awaaz/utils/via_shell.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Utils
+    ##
+    # Utility module providing shell-based audio decoding support for decoder classes.
+    #
+    # This module is intended to be mixed into decoder classes that rely on external
+    # tools such as `ffmpeg`, `mpg123`, or `sox` to decode audio files. It builds the
+    # appropriate shell commands, executes them, and converts the raw audio data into
+    # [Numo::NArray] samples.
+    #
+    # @note This module is `private` and its methods are meant to be used internally by decoders.
+    #
+    # @example Using within a decoder
+    #   class Mp3Decoder < B
+    #     include Awaaz::Utils::ViaShell
+    #
+    #     def load
+    #       process(*shell_load(sox_options: { raw: true }))
+    #     end
+    #   end
+    #
+    module ViaShell
+      private
+
+      ##
+      # Loads audio samples by building and executing a shell command.
+      #
+      # @return [Array<(Numo::DFloat, Integer, Integer)>] An array containing:
+      #   - samples (`Numo::DFloat`)
+      #   - number of channels (`Integer`)
+      #   - sample rate (`Integer`)
+      def shell_load(...)
+        shell_command = build_shell_command(...)
+        load_samples(shell_command)
+      end
+
+      ##
+      # Builds the appropriate shell command for the detected decoder.
+      #
+      # @param ffmpeg_options [Hash] Additional options for `ffmpeg` commands.
+      # @param mpg123_options [Hash] Additional options for `mpg123` commands.
+      # @param sox_options [Hash] Additional options for `sox` commands.
+      # @return [Utils::ShellCommandBuilder] The command builder object.
+      def build_shell_command(ffmpeg_options: {}, mpg123_options: {}, sox_options: {})
+        set_decoder
+
+        case @decoder
+        when :ffmpeg then build_ffmpeg_command(@filename, **ffmpeg_options)
+        when :mpg123 then build_mpg123_command(@filename, **mpg123_options)
+        when :sox    then build_sox_command(@filename, **sox_options)
+        end
+      end
+
+      ##
+      # Builds an `ffmpeg` command to decode audio.
+      #
+      # @param filename [String] Path to the audio file.
+      # @return [Utils::ShellCommandBuilder] The configured command.
+      def build_ffmpeg_command(filename, **_opts)
+        ffmpeg_command = Utils::ShellCommandBuilder.new(:ffmpeg)
+
+        ffmpeg_command
+          .add_flag("-nostdin")
+          .add_option("-v", "quiet")
+          .add_option("-i", filename)
+          .add_option("-f", "s16le")
+          .add_option("-acodec", "pcm_s16le")
+          .add_option("-ac", channels_flag)
+          .add_option("-ar", sample_rate)
+          .add_arg("-")
+      end
+
+      ##
+      # Builds a `mpg123` command to decode audio.
+      #
+      # @param filename [String] Path to the audio file.
+      # @return [Utils::ShellCommandBuilder] The configured command.
+      def build_mpg123_command(filename, **_opts)
+        mpg123_command = Utils::ShellCommandBuilder.new(:mpg123)
+
+        mpg123_command
+          .add_flag("-q")
+          .add_option("-f", amplification_factor)
+          .add_option("-r", sample_rate)
+          .add_flag("-s")
+          .add_arg(filename)
+        mpg123_command.add_flag(channels_flag) if mono?
+        mpg123_command
+      end
+
+      ##
+      # Builds a `sox` command to decode audio.
+      #
+      # @param filename [String] Path to the audio file.
+      # @param opts [Hash] Additional options (e.g., `raw: true`).
+      # @return [Utils::ShellCommandBuilder] The configured command.
+      def build_sox_command(filename, **opts)
+        sox_command = Utils::ShellCommandBuilder.new(:sox)
+
+        sox_command
+          .add_arg(filename)
+          .add_option("-r", sample_rate)
+          .add_option("-e", "signed")
+          .add_option("-b", 16)
+          .add_option("-c", channels_flag)
+        sox_command.add_option("-t", "raw") if opts[:raw]
+        sox_command.add_arg("-")
+      end
+
+      ##
+      # Executes the shell command and loads raw audio samples.
+      #
+      # @param shell_command [String, Utils::ShellCommandBuilder] The shell command to execute.
+      # @return [Array<(Numo::DFloat, Integer, Integer)>] An array containing:
+      #   - samples (`Numo::DFloat`)
+      #   - number of channels (`Integer`)
+      #   - sample rate (`Integer`)
+      def load_samples(shell_command)
+        shell_command = shell_command.command unless shell_command.is_a?(String)
+        raw_audio = IO.popen(shell_command, "rb", &:read)
+        samples = Numo::Int16.from_string(raw_audio).cast_to(Numo::DFloat) / amplification_factor.to_f
+
+        [samples, num_channels, sample_rate.to_i]
+      end
+
+      # This method first returns the already-set `@decoder` if present.
+      # If no decoder is set, it attempts to determine an appropriate decoder
+      # by calling {#choose_decoder}. If no decoder can be determined, it raises
+      # a {Awaaz::DecoderNotFound} error with a list of potential decoders.
+      #
+      # @raise [Awaaz::DecoderNotFound] if no decoder could be determined.
+      # @return [Symbol] The chosen decoder symbol (`:ffmpeg`, `:mpg123`, `:sox`, or a user-provided option).
+      def set_decoder
+        return @decoder if @decoder
+
+        @decoder = choose_decoder
+        return if @decoder
+
+        raise Awaaz::DecoderNotFound,
+              "No available decoder detected to decode mp3 files. " \
+              "Potential decoders: #{config.potential_decoders.join(", ")}"
+      end
+
+      # Chooses an appropriate decoder based on user preference and system capabilities.
+      #
+      # Priority order:
+      # 1. User-specified decoder option (if valid).
+      # 2. `ffmpeg` if available.
+      # 3. `mpg123` if available.
+      # 4. `sox` if available.
+      #
+      # @return [Symbol, nil] The chosen decoder symbol (`:ffmpeg`, `:mpg123`, `:sox`,
+      # or a user-provided option), or `nil` if none is available.
+      def choose_decoder
+        return decoder_option if decoder_option && potential_decoders.include?(decoder_option)
+        return :ffmpeg if config.ffmpeg?
+        return :mpg123 if config.mpg123?
+
+        :sox if config.sox?
+      end
+
+      ##
+      # Returns the appropriate channel flag for the decoder.
+      #
+      # @return [String, Integer] A flag for `mpg123` (`"-m"`) if mono, otherwise the channel count.
+      def channels_flag
+        return "-m" if mpg123? && mono?
+
+        num_channels
+      end
+
+      ##
+      # Checks if the current decoder is `mpg123`.
+      #
+      # @return [Boolean] `true` if the decoder is `mpg123`.
+      def mpg123?
+        set_decoder == :mpg123
+      end
+    end
+  end
+end

data/lib/awaaz/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Awaaz
+  # Version the Awaaz gem.
+  VERSION = "0.1.0"
+end

data/lib/awaaz.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+##
+# Main namespace for the Awaaz gem.
+#
+# The Awaaz gem provides audio decoding utilities and related tools for working
+# with various audio formats. It uses FFI bindings and Numo::NArray for numerical
+# processing and includes multiple decoders, utilities, and configuration options.
+#
+# @see Awaaz::Decoders
+# @see Awaaz::Utils
+# @see Awaaz::Config
+module Awaaz
+end
+
+require "ffi"
+require "numo/narray"
+
+require_relative "awaaz/errors"
+require_relative "awaaz/extensions/extensions"
+require_relative "awaaz/utils/utils"
+require_relative "awaaz/version"
+
+require_relative "awaaz/config"
+require_relative "awaaz/decoders/decoders"

data/sig/awaaz.rbs

@@ -0,0 +1,4 @@
+module Awaaz
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: awaaz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Saad Azam
+bindir: exe
+cert_chain: []
+date: 2025-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+- !ruby/object:Gem::Dependency
+  name: numo-narray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: ruby-filemagic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.3
+description: A gem for loading, decoding, processing and analyse audio.
+email:
+- zeroinside4u@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- GLOSSARY.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODOS.md
+- lib/awaaz.rb
+- lib/awaaz/config.rb
+- lib/awaaz/decoders/base_decoder.rb
+- lib/awaaz/decoders/decode.rb
+- lib/awaaz/decoders/decoders.rb
+- lib/awaaz/decoders/mp3_decoder.rb
+- lib/awaaz/decoders/wavefile_decoder.rb
+- lib/awaaz/errors.rb
+- lib/awaaz/extensions/extensions.rb
+- lib/awaaz/extensions/samplerate.rb
+- lib/awaaz/extensions/soundfile.rb
+- lib/awaaz/utils/resample.rb
+- lib/awaaz/utils/shell_command_builder.rb
+- lib/awaaz/utils/sound_config.rb
+- lib/awaaz/utils/soundread.rb
+- lib/awaaz/utils/utils.rb
+- lib/awaaz/utils/via_shell.rb
+- lib/awaaz/version.rb
+- sig/awaaz.rbs
+homepage: https://github.com/SadMadLad/awaaz
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/SadMadLad/awaaz
+  source_code_uri: https://github.com/SadMadLad/awaaz
+  changelog_uri: https://github.com/SadMadLad/awaaz/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Audio Analysis with Ruby
+test_files: []