sound_util 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbecd6bac9e54aff63e2d7bd8376bbbbcfa99912e50da7904476a1cd95af3470
+  data.tar.gz: bb24ac976ad9e2aef0258c3d490b4b9da7d11cb402cad15f415bf1e59e2d59cd
+SHA512:
+  metadata.gz: 305b93d7e7548ec86946914a4859ac83bf92f5ca17c85eb541161366946d491bf5e177a954f370195af5c9cc67592ff4449c416b8522c5fb45ae05a40edd072a
+  data.tar.gz: 6251e1a64e7d4f7f44b4bb91e3d45a370399fa5d684519856e1c230a560c7b5a160ceb70791149858fcd46b087ffe59213def3041945dfcdc87aa8ba568ad83d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,95 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: disable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+  Exclude:
+    - 'spec/**/*'
+    - 'sound_util.gemspec'
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 170
+
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/PerlBackrefs:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+Style/FormatString:
+  Enabled: false
+
+Layout/SpaceAfterComma:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
+Layout/TrailingWhitespace:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+Style/NilComparison:
+  Enabled: false
+Style/NumericPredicate:
+  Enabled: false
+
+Lint/DuplicateMethods:
+  Enabled: false
+
+Lint/Void:
+  Enabled: false
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+Style/IfInsideElse:
+  Enabled: false
+
+Style/RedundantBegin:
+  Enabled: false
+
+Style/SymbolProc:
+  Enabled: false

data/AGENTS.md

@@ -0,0 +1,12 @@
+# Contributor Guidelines
+
+- Specs mirror file structure under `lib`. For example, `lib/sound_util/buffer.rb` has a spec at `spec/buffer_spec.rb`.
+- Use `autoload` for loading internal files. Avoid `require` and `require_relative` for internal files.
+- Start every Ruby file with `# frozen_string_literal: true`.
+- Prefer double-quoted strings except in specs and the gemspec.
+- Use RSpec's `should` syntax instead of `expect`.
+- For one-line methods, use the `def name = expression` style.
+- After adding new features or modifying existing ones, update documentation accordingly (README and CHANGELOG).
+- Specs target at least 80% coverage as enforced by SimpleCov.
+- The library aims to remain lightweight and portable.
+- Ensure `rake` tests pass and Rubocop doesn't complain.

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## [Unreleased]
+
+- Add `SoundUtil::Wave` and `Wave::Buffer` with `IO::Buffer`-backed PCM storage.
+- Introduce generator/filter/sink subsystems mirroring `image_util`: tone generators (`.sine`, `.silence`), gain/fade filters, playback helper (`Wave#play`), and immutable/bang variants.
+- Wave constructor now defaults to mono 44.1 kHz one-second buffers; blocks accept scalar or per-channel samples.
+- Add `Wave#[]`/`Wave#[]=` with float conversions and range-aware slicing/assignment.
+- Add wave-combination helpers (`#+`/`#<<`, `#|`, `#&`) backed by generator-driven filters plus `Wave#channel` extraction.
+- Introduce WAV codec with magic detection, multi-format PCM/float support, and `Wave.from_data`/`from_file`/`#to_string(:wav)` helpers.
+- Adopt ImageUtil v0.5.0 inspectable interface for `SoundUtil::Wave` pretty-printing.
+- Add linear `Wave#resample` filter for sample rate/frame conversion.
+- Add `Wave#preview` sink for ImageUtil-based waveform charts.
+- CLI `generate` command for sine and silence waveforms; emit raw PCM suitable for piping to sound cards.
+- Set up GitHub Actions CI workflow
+
+## [0.1.0] - 2025-09-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 sound_util contributors
+
+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,158 @@
+# SoundUtil
+
+[![CI](https://github.com/rbutils/sound_util/actions/workflows/ci.yml/badge.svg)](https://github.com/rbutils/sound_util/actions/workflows/ci.yml)
+
+SoundUtil is a lightweight Ruby library focused on manipulating sound data directly in memory. Its primary goal is to help scripts process and analyze audio buffers using `IO::Buffer`. The API is still evolving and should be considered unstable until version 1.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "sound_util"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+## Usage
+
+Generate a 440 Hz stereo sine wave and stream it to stdout (pipeable into
+`aplay`, `ffplay`, etc.):
+
+```ruby
+require "sound_util"
+
+duration    = 2.0
+sample_rate = 44_100
+channels    = 2
+
+wave = SoundUtil::Wave.sine(
+  duration_seconds: duration,
+  sample_rate: sample_rate,
+  channels: channels,
+  frequency: 440.0,
+  amplitude: 0.6
+)
+
+wave.pipe($stdout)
+```
+
+Blocks passed to `SoundUtil::Wave.new` yield the frame index and may return a
+scalar (applied to all channels) or an array of per-channel sample values.
+Floats are treated as `-1.0..1.0` amplitudes and integers are clamped to the
+target PCM range.
+
+### Filters
+
+Waves provide mutable/immutable filters similar to `image_util`:
+
+```ruby
+wave = SoundUtil::Wave.sine(duration_seconds: 1, frequency: 220)
+
+wave = wave.gain(0.25)          # return a quieter copy
+wave.fade_in!(seconds: 0.1)     # in-place fade-in over the first 0.1s
+wave.fade_out!(seconds: 0.1)    # in-place fade-out over the last 0.1s
+wave = wave.resample(48_000)         # adjust sample rate with linear interpolation
+```
+
+`Wave#resample(rate, frames: nil)` performs linear interpolation and updates both sample rate and frame count (pass `frames:` to override duration).
+
+### WAV input/output
+
+```ruby
+wave  = SoundUtil::Wave.from_file("input.wav")
+bytes = wave.to_string(:wav)               # defaults to source format
+
+wave = SoundUtil::Wave.new(frames: 2) { 0.2 }
+wave.to_file("output.wav")                # writes RIFF/WAVE by default
+
+io = StringIO.new
+wave.to_file(io, :wav, sample_format: :f32le) # encode with custom format
+```
+
+`SoundUtil::Wave.from_data(data, format: :wav)` decodes in-memory WAV blobs,
+while `from_file` accepts paths or IO objects (auto-detecting formats via the
+Magic helper). Encoding supports the common PCM/float variants (`:u8`,
+`:s16le`, `:s24le`, `:s32le`, `:f32le`, `:f64le`). Pass `sample_format:` when
+you need to transcode to a different width before writing.
+
+### Combining waves
+
+```ruby
+intro = SoundUtil::Wave.sine(duration_seconds: 0.5, frequency: 440)
+outro = SoundUtil::Wave.silence(duration_seconds: 0.25)
+
+full  = intro + outro           # append, returns a new wave
+intro << outro                  # append in place
+
+vocals = SoundUtil::Wave.sine(duration_seconds: 0.5, frequency: 220)
+mix    = vocals | intro         # mix with sample clamping
+
+stereo = vocals & intro         # stack channels together
+mono   = stereo.channel(0)      # extract an individual channel
+```
+
+`#+` and `#<<` append clips end-to-end (requiring matching sample rates, formats,
+and channel counts). `#|` mixes two clips frame-by-frame with automatic
+clamping, and `#&` stacks their channels using the longest duration from either
+wave. Use `Wave#channel(index)` to materialize a single channel as its own
+wave.
+
+```ruby
+wave.play                         # pipes to the default `aplay` command
+wave.play(command: ["ffplay", "-autoexit", "-nodisp", "-f", "s16le", "-ar", wave.sample_rate.to_s, "-ac", wave.channels.to_s, "-"])
+```
+
+`Wave#play` shells out to `aplay` by default. Provide `command:` with a string/array when targeting other tools (e.g. `ffplay`, `afplay`).
+
+### Indexing
+
+```ruby
+wave[0]          # => [Float, Float] for all channels in the first frame
+wave[0, 1]       # => Float for a specific channel
+wave[100..200]   # => new Wave containing that frame range
+wave[0..-1, 0]   # => mono Wave extracted from channel 0
+
+wave[0] = [0.5, -0.5]
+wave[10..20] = SoundUtil::Wave.sine(duration_seconds: 0.25, frequency: 880)
+```
+
+Values are normalised to the `-1.0..1.0` range when read and clamped when written.
+
+### Preview
+
+```ruby
+SoundUtil::Wave.sine(duration_seconds: 1, frequency: 440).preview
+```
+
+Renders a compact Sixel chart (requires ImageUtil and terminal support). Pass `width:`/`height:` options to adjust the preview
+
+Wave instances now implement `inspect_image`, so pretty-printing in IRB (`pp wave`) renders the same preview via ImageUtil's inspectable interface.
+
+### CLI
+
+The Thor CLI emits raw PCM suitable for piping into a sound device:
+
+```sh
+bundle exec exe/sound_util generate sine \
+  --seconds 2 --rate 44100 --channels 2 --frequency 440 --amplitude 0.6 \
+  | aplay -f S16_LE -c 2 -r 44100
+```
+
+Use `--output path.pcm` to write to a file instead of stdout.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake` to run the tests and linter.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rbutils/sound_util.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/sound_util

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sound_util"
+
+SoundUtil::CLI.start(ARGV)

data/lib/sound_util/cli.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module SoundUtil
+  class CLI < Thor
+    desc "version", "Display SoundUtil version"
+    def version
+      puts SoundUtil::VERSION
+    end
+
+    desc "generate TYPE", "Generate PCM audio and write to stdout or file"
+    option :seconds, type: :numeric, default: 1.0, aliases: "-s", banner: "SECONDS"
+    option :rate, type: :numeric, default: 44_100, aliases: "-r", banner: "HZ"
+    option :channels, type: :numeric, default: 2, aliases: "-c", banner: "N"
+    option :frequency, type: :numeric, default: 440.0, aliases: "-f", banner: "HZ"
+    option :amplitude, type: :numeric, default: 1.0, aliases: "-a"
+    option :format, type: :string, default: "s16le"
+    option :output, type: :string, aliases: "-o"
+    def generate(type)
+      wave = case type
+             when "sine"
+               SoundUtil::Wave.sine(
+                 duration_seconds: options[:seconds],
+                 sample_rate: options[:rate],
+                 channels: options[:channels],
+                 frequency: options[:frequency],
+                 amplitude: options[:amplitude],
+                 format: options[:format]
+               )
+             when "silence"
+               SoundUtil::Wave.silence(
+                 duration_seconds: options[:seconds],
+                 sample_rate: options[:rate],
+                 channels: options[:channels],
+                 format: options[:format]
+               )
+             else
+               raise ArgumentError, "unsupported generator: #{type}"
+             end
+
+      write_wave(wave)
+    end
+
+    no_commands do
+      def write_wave(wave)
+        if options[:output]
+          File.open(options[:output], "wb") { |io| wave.pipe(io) }
+        else
+          wave.pipe($stdout)
+        end
+      end
+    end
+  end
+end

data/lib/sound_util/codec/wav.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module SoundUtil
+  module Codec
+    # rubocop:disable Metrics/ModuleLength
+    module Wav
+      PCM = 0x0001
+      IEEE_FLOAT = 0x0003
+      EXTENSIBLE = 0xFFFE
+
+      SUBFORMAT_PCM = [1, 0, 0, 0, 0, 0, 16, 0, 128, 0, 0, 170, 0, 56, 155, 113].pack("C*").freeze
+      SUBFORMAT_IEEE_FLOAT = [3, 0, 0, 0, 0, 0, 16, 0, 128, 0, 0, 170, 0, 56, 155, 113].pack("C*").freeze
+
+      CHUNK_ALIGN = 2
+
+      SUPPORTED_FORMATS = {
+        u8: { bits_per_sample: 8, audio_format: PCM },
+        s16le: { bits_per_sample: 16, audio_format: PCM },
+        s24le: { bits_per_sample: 24, audio_format: PCM },
+        s32le: { bits_per_sample: 32, audio_format: PCM },
+        f32le: { bits_per_sample: 32, audio_format: IEEE_FLOAT },
+        f64le: { bits_per_sample: 64, audio_format: IEEE_FLOAT }
+      }.freeze
+
+      module_function
+
+      def supported?(format)
+        format == :wav
+      end
+
+      def decode(_format, data, **_kwargs)
+        io = StringIO.new(data)
+        decode_io(:wav, io)
+      end
+
+      def decode_io(_format, io, **_kwargs)
+        io.binmode if io.respond_to?(:binmode)
+
+        riff, _total_size, wave_id = read_riff_header(io)
+        raise UnsupportedFormatError, "unsupported RIFF type: #{riff}" unless riff == "RIFF"
+        raise UnsupportedFormatError, "not a WAVE file" unless wave_id == "WAVE"
+
+        fmt_chunk = nil
+        data_chunk = nil
+
+        until io.eof?
+          id = io.read(4)
+          break unless id
+
+          size = read_uint32(io)
+          payload = io.read(size)
+          raise UnsupportedFormatError, "unexpected EOF" if payload.nil? || payload.bytesize < size
+
+          io.read(1) if (size % CHUNK_ALIGN).positive?
+
+          case id
+          when "fmt "
+            fmt_chunk = payload
+          when "data"
+            data_chunk = payload
+            break if fmt_chunk
+          else
+            next
+          end
+        end
+
+        raise UnsupportedFormatError, "missing fmt chunk" unless fmt_chunk
+        raise UnsupportedFormatError, "missing data chunk" unless data_chunk
+
+        fmt = parse_fmt_chunk(fmt_chunk)
+        ensure_supported_format!(fmt)
+
+        validate_data_size!(data_chunk.bytesize, fmt)
+
+        SoundUtil::Wave.from_string(
+          data_chunk,
+          channels: fmt[:channels],
+          sample_rate: fmt[:sample_rate],
+          format: fmt[:internal_format]
+        )
+      end
+
+      def encode(_format, wave, sample_format: nil, bits_per_sample: nil)
+        io = StringIO.new
+        encode_io(:wav, wave, io, sample_format: sample_format, bits_per_sample: bits_per_sample)
+        io.string
+      end
+
+      def encode_io(_format, wave, io, sample_format: nil, bits_per_sample: nil)
+        io.binmode if io.respond_to?(:binmode)
+
+        format_symbol = determine_target_format(wave, sample_format, bits_per_sample)
+        spec = SUPPORTED_FORMATS.fetch(format_symbol)
+        bytes_per_sample = SoundUtil::Wave::SUPPORTED_FORMATS.fetch(format_symbol)[:bytes_per_sample]
+        block_align = bytes_per_sample * wave.channels
+        byte_rate = wave.sample_rate * block_align
+        bits = spec[:bits_per_sample]
+
+        data = export_wave_data(wave, format_symbol)
+        data_size = data.bytesize
+        data_padding = (data_size % CHUNK_ALIGN).positive? ? "\x00" : ""
+        data_chunk = String.new("data", encoding: Encoding::ASCII_8BIT)
+        data_chunk << [data_size].pack("V")
+        data_chunk << data
+        data_chunk << data_padding
+
+        fmt_body = [
+          spec[:audio_format],
+          wave.channels,
+          wave.sample_rate,
+          byte_rate,
+          block_align,
+          bits
+        ].pack("v2V2v2")
+
+        fmt_chunk = build_chunk("fmt ", fmt_body)
+        fact_chunk = spec[:audio_format] == PCM ? nil : build_chunk("fact", [wave.frames].pack("V"))
+
+        total_size = 4 + fmt_chunk.bytesize + (fact_chunk ? fact_chunk.bytesize : 0) + data_chunk.bytesize
+
+        io << "RIFF"
+        io << [total_size].pack("V")
+        io << "WAVE"
+        io << fmt_chunk
+        io << fact_chunk if fact_chunk
+        io << data_chunk
+        io
+      end
+
+      def build_chunk(id, payload)
+        size = payload.bytesize
+        id + [size].pack("V") + payload
+      end
+      private_class_method :build_chunk
+
+      def read_riff_header(io)
+        chunk_id = io.read(4)
+        size = read_uint32(io)
+        format = io.read(4)
+        [chunk_id, size, format]
+      end
+
+      def read_uint16(io)
+        data = io.read(2)
+        raise UnsupportedFormatError, "unexpected EOF" unless data && data.bytesize == 2
+
+        data.unpack1("v")
+      end
+
+      def read_uint32(io)
+        data = io.read(4)
+        raise UnsupportedFormatError, "unexpected EOF" unless data && data.bytesize == 4
+
+        data.unpack1("V")
+      end
+
+      def parse_fmt_chunk(data)
+        io = StringIO.new(data)
+
+        audio_format = read_uint16(io)
+        channels = read_uint16(io)
+        sample_rate = read_uint32(io)
+        byte_rate = read_uint32(io)
+        block_align = read_uint16(io)
+        bits_per_sample = read_uint16(io)
+
+        resolved_format = audio_format
+        valid_bits = bits_per_sample
+
+        if audio_format == EXTENSIBLE
+          cb_size = read_uint16(io)
+          raise UnsupportedFormatError, "invalid extensible header" if cb_size.nil? || cb_size < 22
+
+          valid_bits = read_uint16(io)
+          valid_bits = bits_per_sample if valid_bits.zero?
+          _channel_mask = read_uint32(io)
+          subformat = read_guid(io)
+          resolved_format = resolve_subformat(subformat)
+          skip = cb_size - 22
+          io.read(skip) if skip.positive?
+        end
+
+        {
+          audio_format: resolved_format,
+          channels: channels,
+          sample_rate: sample_rate,
+          byte_rate: byte_rate,
+          block_align: block_align,
+          bits_per_sample: valid_bits
+        }
+      end
+
+      def read_guid(io)
+        data = io.read(16)
+        raise UnsupportedFormatError, "unexpected EOF" unless data && data.bytesize == 16
+
+        data
+      end
+
+      def resolve_subformat(subformat)
+        case subformat
+        when SUBFORMAT_PCM
+          PCM
+        when SUBFORMAT_IEEE_FLOAT
+          IEEE_FLOAT
+        else
+          raise UnsupportedFormatError, "unsupported extensible subformat"
+        end
+      end
+
+      def ensure_supported_format!(fmt)
+        fmt[:internal_format] = case fmt[:audio_format]
+                                when PCM
+                                  map_pcm_bits(fmt[:bits_per_sample])
+                                when IEEE_FLOAT
+                                  map_float_bits(fmt[:bits_per_sample])
+                                else
+                                  raise UnsupportedFormatError, "unsupported audio format #{fmt[:audio_format]}"
+                                end
+      end
+
+      def map_pcm_bits(bits)
+        case bits
+        when 8 then :u8
+        when 16 then :s16le
+        when 24 then :s24le
+        when 32 then :s32le
+        else
+          raise UnsupportedFormatError, "unsupported PCM bit depth #{bits}"
+        end
+      end
+
+      def map_float_bits(bits)
+        case bits
+        when 32 then :f32le
+        when 64 then :f64le
+        else
+          raise UnsupportedFormatError, "unsupported float bit depth #{bits}"
+        end
+      end
+
+      def validate_data_size!(bytesize, fmt)
+        expected_stride = fmt[:block_align]
+        raise UnsupportedFormatError, "corrupt data chunk" unless (bytesize % expected_stride).zero?
+      end
+
+      def determine_target_format(wave, sample_format, bits)
+        return sample_format.to_sym if sample_format
+
+        if bits
+          return map_pcm_bits(bits) if [8, 16, 24, 32].include?(bits) && !%i[f32le f64le].include?(wave.format)
+          return map_float_bits(bits) if [32, 64].include?(bits) && %i[f32le f64le].include?(wave.format)
+        end
+
+        wave.format.tap do |fmt|
+          raise UnsupportedFormatError, "unsupported wave format #{fmt}" unless SUPPORTED_FORMATS.key?(fmt)
+        end
+      end
+
+      def export_wave_data(wave, target_format)
+        return wave.buffer.to_s if wave.format == target_format
+
+        converted = SoundUtil::Wave.new(
+          channels: wave.channels,
+          sample_rate: wave.sample_rate,
+          frames: wave.frames,
+          format: target_format
+        ) do |frame_idx|
+          wave[frame_idx]
+        end
+
+        converted.to_string
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end