awaaz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2aa5ae798de6f2b722134913cc7b055f53b4b035989e94521be55d1fe76acc7
+  data.tar.gz: b54beb3ae4fc90ab2a4c1485ffa91eccb1b53cafca27c04e7ece14263b65abb4
+SHA512:
+  metadata.gz: b0c79b3dbf5396de690ee17868cb8a0d2d29dfe396b8c5dd9c9a098393a40d15715d4def9990990024ad356f9463cb28feab981e96f59e4961d978e373a104ce
+  data.tar.gz: d28e0001af9a5b8052298f33a5dbf72ca16325d15e3762187fd7a022b6140874729f52d71d32a0e39a589b712471e248fd28dd6e73dea35dd3fa26742a22ef2b

data/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/MethodLength:
+  Max: 20
+
+
+

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-07-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/GLOSSARY.md

@@ -0,0 +1,3 @@
+# Terms and Definitions for Audio Processing
+
+- **PCM (Pulse Code Modulation):** A method to convert analog audio signals into digital form by sampling the signal's ampllitude at regular intervals.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Saad Azam
+
+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,72 @@
+# Awaaz
+
+Awaaz is a Ruby gem for working with audio, from decoding to analysis, making it easier to process and understand sound in your projects.
+
+## Requirements
+
+Awaaz can decode audio in two ways:
+
+#### 1. Shell-based decoding  
+You can install **any one** of the following:
+
+- [`ffmpeg`](https://github.com/FFmpeg/FFmpeg) – supports most formats, including MP3.  
+- [`sox`](https://github.com/chirlu/sox) – also supports most formats, including MP3.  
+- [`mpg123`](https://github.com/madebr/mpg123) – **MP3 only**.
+
+#### 2. Library-based decoding and resampling  
+- [`libsndfile`](https://github.com/libsndfile/libsndfile) – reads audio files (but **cannot** read MP3 files).  
+- [`libsamplerate`](https://github.com/libsndfile/libsamplerate) – resamples audio samples when using `libsndfile`.  
+
+⚠ **Important**:  
+- If you need MP3 support with the library-based method, you **must also** install one of:  
+  - `ffmpeg`  
+  - `sox`  
+  - `mpg123`
+
+#### Additional Requirement
+- The Ruby gem [`numo-narray`](https://github.com/ruby-numo/numo-narray) is required for numerical array operations.
+
+### Installation Examples
+
+- **Just ffmpeg** → works for all formats (no `libsndfile` or `libsamplerate` needed).  
+- **Just sox** → works for all formats (no `libsndfile` or `libsamplerate` needed).  
+- **libsndfile + libsamplerate** → works for non-MP3 formats. For MP3, add `ffmpeg`, `sox`, or `mpg123`.  
+- **Everything installed** → maximum flexibility.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add awaaz
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install awaaz
+```
+
+## Usage
+
+```ruby
+# To decode the audio file
+samples, sample_rate = Awaaz.load("path/to/audio_file")
+
+# To decode the audio file using specified decoder
+samples, sample_rate = Awaaz.load("path/to/audio_file", decoder: :sox)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [Awaaz](https://github.com/SadMadLad/awaaz). This project is intended to be a safe, welcoming space for collaboration, and contributors.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/TODOS.md

@@ -0,0 +1,3 @@
+- Lazy decoding of an audio
+- `libsndfile` support
+- Streaming output of larger files

data/lib/awaaz/config.rb

@@ -0,0 +1,123 @@
+# 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.
+#
+module Awaaz
+  ##
+  # The Config class handles detection and configuration of available audio decoders
+  # for the Awaaz gem. It checks the system for supported decoder binaries
+  # (mpg123, ffmpeg, sox) and provides query helpers to check their availability.
+  #
+  # @example Check if `ffmpeg` is available
+  #   Awaaz.config.ffmpeg? # => true or false
+  #
+  class Config
+    ##
+    # Creates a new configuration instance and detects available decoders.
+    #
+    def initialize
+      @available_decoders = detect_decoders
+    end
+
+    ##
+    # Checks if a given decoder is available on the system.
+    #
+    # @param name [Symbol, String] The name of the decoder (e.g., `:mpg123`, `"ffmpeg"`).
+    # @return [Boolean] `true` if the decoder is available, otherwise `false`.
+    #
+    def decoder?(name)
+      @available_decoders.include?(name.to_sym)
+    end
+
+    ##
+    # Checks if mpg123 is available.
+    #
+    # @return [Boolean] `true` if mpg123 is installed, otherwise `false`.
+    #
+    def mpg123?
+      decoder?(:mpg123)
+    end
+
+    ##
+    # Checks if ffmpeg is available.
+    #
+    # @return [Boolean] `true` if ffmpeg is installed, otherwise `false`.
+    #
+    def ffmpeg?
+      decoder?(:ffmpeg)
+    end
+
+    ##
+    # Checks if sox is available.
+    #
+    # @return [Boolean] `true` if sox is installed, otherwise `false`.
+    #
+    def sox?
+      decoder?(:sox)
+    end
+
+    ##
+    # Lists all potential decoders that Awaaz can work with.
+    #
+    # @return [Array<Symbol>] An array of decoder names (`:mpg123`, `:ffmpeg`, `:sox`).
+    #
+    def potential_decoders
+      %i[mpg123 ffmpeg sox]
+    end
+
+    ##
+    # Checks if no decoders are available on the system.
+    #
+    # @return [Boolean] `true` if no decoders were detected, otherwise `false`.
+    #
+    def no_decoders?
+      @available_decoders.nil? || @available_decoders.empty?
+    end
+
+    private
+
+    ##
+    # Detects which decoders are available by checking system binaries.
+    #
+    # @return [Array<Symbol>] An array of detected decoder names.
+    #
+    def detect_decoders
+      decoders = []
+      decoders << :mpg123 if system("which mpg123 > /dev/null 2>&1")
+      decoders << :ffmpeg if system("which ffmpeg > /dev/null 2>&1")
+      decoders << :sox    if system("which sox > /dev/null 2>&1")
+      decoders
+    end
+  end
+
+  class << self
+    ##
+    # Returns the current configuration object.
+    #
+    # @return [Awaaz::Config] The configuration instance.
+    #
+    def config
+      @config ||= Config.new
+    end
+
+    ##
+    # Yields the current configuration object for modifications.
+    #
+    # @yieldparam config [Awaaz::Config] The configuration instance.
+    #
+    def configure
+      yield(config)
+    end
+
+    ##
+    # Lists all potential decoders that Awaaz can work with.
+    #
+    # @return [Array<Symbol>] An array of decoder names.
+    #
+    def potential_decoders
+      config.potential_decoders
+    end
+  end
+end

data/lib/awaaz/decoders/base_decoder.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Decoders
+    # Abstract base class for audio decoders in the Awaaz gem.
+    #
+    # Provides common configuration handling, option management, and helper
+    # methods for working with audio data. Subclasses are expected to implement
+    # the {#load} method to perform the actual decoding process.
+    #
+    # @abstract
+    class BaseDecoder
+      class << self
+        # @return [Array<Symbol>] The default set of options available to all decoders.
+        def default_available_options
+          %i[amplification_factor decoder sample_rate mono]
+        end
+
+        # Sets the list of available options for this decoder class.
+        #
+        # @param provided_available_options [Array<Symbol>] the list of available option keys.
+        # @return [void]
+        def set_available_options(provided_available_options = default_available_options)
+          @available_options = provided_available_options
+        end
+
+        # @return [Array<Symbol>] The currently available option keys for this decoder class.
+        attr_reader :available_options
+
+        # Loads audio from a given file using this decoder.
+        #
+        # @param filename [String] The path to the audio file to load.
+        # @return [Object] The decoded audio data.
+        #
+        # @see #initialize
+        def load(filename, ...)
+          new(filename, ...).load
+        end
+      end
+
+      set_available_options
+
+      # @param filename [String] Path to the audio file to decode.
+      def initialize(filename, **)
+        @filename = filename
+        @options = Utils::SoundConfig.new(available_options, **)
+      end
+
+      # Loads audio data.
+      #
+      # This method must be implemented by subclasses to perform
+      # the actual decoding of the file.
+      #
+      # @abstract
+      # @raise [NotImplementedError] if called on the base class.
+      def load
+        raise NotImplementedError
+      end
+
+      # @return [Array<Symbol>] The available options for this instance.
+      def available_options
+        self.class.available_options
+      end
+
+      protected
+
+      # Reads audio data from the file using {Utils::Soundread}.
+      #
+      # @return [Array<(Numo::SFloat, Integer, Integer)>]
+      #   A tuple containing:
+      #   - audio samples as a Numo::SFloat array
+      #   - number of channels
+      #   - sample rate
+      def soundread
+        Utils::Soundread.new(@filename).read
+      end
+
+      # Processes the decoded audio samples by reshaping and optionally converting to mono.
+      #
+      # @param input_samples [Numo::DFloat] The raw decoded samples.
+      # @param channels [Integer] Number of channels in the input.
+      # @param sample_rate [Integer] The sample rate of the input.
+      # @return [Array<(Numo::DFloat, Integer)>] Processed samples and the sample rate.
+      def process(input_samples, channels, sample_rate)
+        input_samples = input_samples.reshape(channels, input_samples.size / channels)
+        input_samples = input_samples.mean(0) if mono?
+
+        [input_samples, sample_rate]
+      end
+
+      # Validates that the file extension matches the expected extension.
+      #
+      # @param file_extension [String] Expected file extension (e.g., ".mp3").
+      # @raise [ArgumentError] if the file extension does not match.
+      def validate_file_extension(file_extension)
+        raise ArgumentError, "Not a #{file_extension} file" unless File.extname(@filename) == file_extension
+      end
+
+      # @return [Awaaz::Config] The global Awaaz configuration.
+      def config = Awaaz.config
+
+      # Delegates config methods to the {Awaaz::Config} instance.
+      %i[no_decoders? potential_decoders].each do |config_method|
+        define_method(config_method) { config.public_send(config_method) }
+      end
+
+      # Delegates option accessors to the {Utils::SoundConfig} instance.
+      %i[
+        sample_rate num_channels decoder_option mono mono?
+        stereo? amplification_factor soundread?
+      ].each do |option_key|
+        define_method(option_key) { @options.public_send(option_key) }
+      end
+    end
+  end
+end

data/lib/awaaz/decoders/decode.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "filemagic"
+
+# 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.
+module Awaaz
+  # Mapping of MIME types to their respective decoder classes.
+  DECODER_MAP = {
+    "audio/wav" => Decoders::WavefileDecoder,
+    "audio/x-wav" => Decoders::WavefileDecoder,
+    "audio/wave" => Decoders::WavefileDecoder,
+    "audio/vnd.wave" => Decoders::WavefileDecoder,
+    "audio/mpeg" => Decoders::Mp3Decoder,
+    "audio/mp3" => Decoders::Mp3Decoder,
+    "audio/x-mpeg" => Decoders::Mp3Decoder,
+    "audio/x-mp3" => Decoders::Mp3Decoder
+  }.freeze
+
+  class << self
+    # Loads an audio file and processes it using the appropriate decoder
+    # based on the file's MIME type.
+    #
+    # @param filename [String] the path to the audio file
+    # @raise [ArgumentError] if the MIME type is not supported
+    # @return [Object] the result of decoding, as returned by the decoder class
+    def load(filename)
+      fm = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
+      mime_type = fm.file(filename)
+
+      unless DECODER_MAP.key?(mime_type)
+        raise ArgumentError,
+              "Cannot load the file. Available mime types: #{DECODER_MAP.keys.join(", ")}"
+      end
+
+      decoding_class = DECODER_MAP[mime_type]
+      decoding_class.load(filename)
+    end
+  end
+end

data/lib/awaaz/decoders/decoders.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# This file loads all available decoders for the Awaaz gem.
+# It ensures that the base decoder and all specific decoder
+# implementations (e.g., MP3, WAV) are required and ready
+# for use under the {Awaaz::Decoders} namespace.
+#
+# @example Accessing a decoder
+#   Awaaz::Decoders::Mp3Decoder.new.load
+#
+# @see Awaaz::Decoders::BaseDecoder
+# @see Awaaz::Decoders::Mp3Decoder
+# @see Awaaz::Decoders::WavefileDecoder
+#
+
+require_relative "base_decoder"
+require_relative "mp3_decoder"
+require_relative "wavefile_decoder"
+require_relative "decode"
+
+module Awaaz
+  # Namespace for all audio decoder implementations.
+  #
+  # Each decoder is responsible for loading and processing
+  # a specific audio format into a format usable by the Awaaz system.
+  #
+  # @since 0.1.0
+  module Decoders
+  end
+end

data/lib/awaaz/decoders/mp3_decoder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Awaaz
+  module Decoders
+    ##
+    # The Mp3Decoder class provides decoding functionality for `.mp3` files
+    # within the Awaaz gem.
+    #
+    # It inherits from {BaseDecoder} and uses the {Utils::ViaShell} mixin
+    # to perform decoding via shell commands (e.g., Sox).
+    #
+    # @example Basic usage
+    #   decoder = Awaaz::Decoders::Mp3Decoder.new(file_path: "song.mp3")
+    #   samples = decoder.load
+    #
+    # @see BaseDecoder
+    # @see Utils::ViaShell
+    #
+    class Mp3Decoder < BaseDecoder
+      include Utils::ViaShell
+
+      # Sets available options for this decoder (defined in BaseDecoder).
+      set_available_options
+
+      ##
+      # Loads and processes an MP3 file.
+      #
+      # This method:
+      # 1. Validates that the file has a `.mp3` extension.
+      # 2. Uses {Utils::ViaShell#shell_load} to load raw audio data.
+      # 3. Passes the loaded data to {BaseDecoder#process} for further handling.
+      #
+      # @raise [ArgumentError]
+      #   If the file does not have a `.mp3` extension.
+      #
+      # @return [Object]
+      #   The processed audio data (return type depends on BaseDecoder#process).
+      #
+      def load
+        process(*shell_load(sox_options: { raw: true }))
+      end
+    end
+  end
+end