sound_util 0.1.0

data/lib/sound_util/codec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Codec
+    class UnsupportedFormatError < SoundUtil::Error; end
+
+    @encoders = []
+    @decoders = []
+
+    class << self
+      attr_reader :encoders, :decoders
+
+      def register_encoder(codec_const, *formats)
+        encoders << { codec: codec_const, formats: formats.map { |f| f.to_s.downcase } }
+      end
+
+      def register_decoder(codec_const, *formats)
+        decoders << { codec: codec_const, formats: formats.map { |f| f.to_s.downcase } }
+      end
+
+      def register_codec(codec_const, *formats)
+        register_encoder(codec_const, *formats)
+        register_decoder(codec_const, *formats)
+      end
+
+      def supported?(format)
+        fmt = format.to_s.downcase
+        encoders.any? { |entry| entry[:formats].include?(fmt) && codec_supported?(entry[:codec], fmt) } ||
+          decoders.any? { |entry| entry[:formats].include?(fmt) && codec_supported?(entry[:codec], fmt) }
+      end
+
+      def encode(format, wave, codec: nil, **kwargs)
+        codec = find_codec(encoders, format, codec)
+        codec.encode(format, wave, **kwargs)
+      end
+
+      def decode(format, data, codec: nil, **kwargs)
+        codec = find_codec(decoders, format, codec)
+        codec.decode(format, data, **kwargs)
+      end
+
+      def encode_io(format, wave, io, codec: nil, **kwargs)
+        codec = find_codec(encoders, format, codec)
+        if codec.respond_to?(:encode_io)
+          codec.encode_io(format, wave, io, **kwargs)
+        else
+          io << codec.encode(format, wave, **kwargs)
+        end
+      end
+
+      def decode_io(format, io, codec: nil, **kwargs)
+        codec = find_codec(decoders, format, codec)
+        if codec.respond_to?(:decode_io)
+          codec.decode_io(format, io, **kwargs)
+        else
+          codec.decode(format, io.read, **kwargs)
+        end
+      end
+
+      def detect(data)
+        Magic.detect(data)
+      end
+
+      def detect_io(io)
+        Magic.detect_io(io).first
+      end
+
+      private
+
+      def find_codec(list, format, preferred = nil)
+        fmt = format.to_s.downcase
+        if preferred
+          record = list.find { |entry| entry[:formats].include?(fmt) && entry[:codec].to_s == preferred.to_s }
+          raise UnsupportedFormatError, "unsupported format #{format}" unless record
+
+          codec = const_get(record[:codec])
+          if codec.respond_to?(:supported?) && !codec.supported?(fmt.to_sym)
+            raise UnsupportedFormatError, "unsupported format #{format}"
+          end
+
+          return codec
+        end
+
+        list.each do |entry|
+          next unless entry[:formats].include?(fmt)
+
+          codec = const_get(entry[:codec])
+          next if codec.respond_to?(:supported?) && !codec.supported?(fmt.to_sym)
+
+          return codec
+        end
+
+        raise UnsupportedFormatError, "unsupported format #{format}"
+      end
+
+      def codec_supported?(codec_const, fmt)
+        codec = const_get(codec_const)
+        !codec.respond_to?(:supported?) || codec.supported?(fmt.to_sym)
+      end
+    end
+
+    autoload :Wav, "sound_util/codec/wav"
+
+    register_codec :Wav, :wav
+  end
+end

data/lib/sound_util/filter/_mixin.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    module Mixin
+      def define_immutable_version(*names)
+        names.each do |name|
+          define_method(name) do |*args, **kwargs, &block|
+            dup.tap { |wave| wave.public_send("#{name}!", *args, **kwargs, &block) }
+          end
+        end
+      end
+
+      def define_mutable_version(*names)
+        names.each do |name|
+          define_method("#{name}!") do |*args, **kwargs, &block|
+            initialize_from_buffer(public_send(name, *args, **kwargs, &block).buffer)
+            self
+          end
+        end
+      end
+
+      module_function :define_immutable_version, :define_mutable_version
+    end
+  end
+end

data/lib/sound_util/filter/combine.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    module Combine
+      def append(other_wave)
+        self.class.generate_appended_wave(left: self, right: other_wave)
+      end
+
+      def append!(other_wave)
+        wave = append(other_wave)
+        initialize_from_buffer(wave.buffer)
+        self
+      end
+
+      def mix(other_wave)
+        self.class.generate_mixed_wave(left: self, right: other_wave)
+      end
+
+      def mix!(other_wave)
+        wave = mix(other_wave)
+        initialize_from_buffer(wave.buffer)
+        self
+      end
+
+      def stack_channels(other_wave)
+        self.class.generate_stacked_wave(primary: self, secondary: other_wave)
+      end
+
+      def stack_channels!(other_wave)
+        wave = stack_channels(other_wave)
+        initialize_from_buffer(wave.buffer)
+        self
+      end
+
+      alias + append
+      alias << append!
+      alias | mix
+      alias & stack_channels
+    end
+  end
+end

data/lib/sound_util/filter/fade.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    module Fade
+      extend Filter::Mixin
+
+      define_immutable_version :fade_in, :fade_out
+
+      def fade_in!(seconds: duration)
+        apply_fade!(seconds, :in)
+      end
+
+      def fade_out!(seconds: duration)
+        apply_fade!(seconds, :out)
+      end
+
+      private
+
+      def apply_fade!(seconds, direction)
+        fade_frames = (seconds * sample_rate).to_i
+        fade_frames = [[fade_frames, 1].max, frames].min
+
+        mutate_frames! do |frame_idx, samples|
+          factor = fade_factor(frame_idx, fade_frames, direction)
+          samples.map { |sample| encode_value(sample_to_float(sample) * factor) }
+        end
+      end
+
+      def fade_factor(frame_idx, fade_frames, direction)
+        case direction
+        when :in
+          return 1.0 if frame_idx >= fade_frames
+
+          (frame_idx + 1).to_f / fade_frames
+        when :out
+          remaining = frames - frame_idx
+          return 1.0 if remaining > fade_frames
+
+          [(remaining - 1), 0].max.to_f / fade_frames
+        else
+          1.0
+        end
+      end
+    end
+  end
+end

data/lib/sound_util/filter/gain.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    module Gain
+      extend Filter::Mixin
+
+      define_immutable_version :gain
+
+      def gain!(factor)
+        mutate_frames! do |_frame_idx, samples|
+          samples.map { |sample| encode_value(sample_to_float(sample) * factor) }
+        end
+      end
+
+      alias * gain
+    end
+  end
+end

data/lib/sound_util/filter/resample.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    module Resample
+      extend Filter::Mixin
+
+      define_immutable_version :resample
+
+      def resample!(new_sample_rate, frames: nil, method: :linear)
+        target_rate = Integer(new_sample_rate)
+        raise ArgumentError, "new sample rate must be positive" unless target_rate.positive?
+
+        target_frames = frames ? Integer(frames) : calculate_target_frames(target_rate)
+        raise ArgumentError, "target frames must be positive" unless target_frames.positive?
+
+        return self if target_rate == sample_rate && target_frames == self.frames
+
+        case method
+        when :linear
+          perform_linear_resample!(target_rate, target_frames)
+        else
+          raise ArgumentError, "unsupported resample method: #{method.inspect}"
+        end
+
+        self
+      end
+
+      private
+
+      def calculate_target_frames(new_sample_rate)
+        frames = (duration * new_sample_rate).round
+        frames = 1 if frames.zero?
+        frames
+      end
+
+      def perform_linear_resample!(target_rate, target_frames)
+        if frames.zero?
+          initialize_from_buffer(Util.build_buffer(self, channels: channels, frames: target_frames, sample_rate: target_rate))
+          @sample_rate = target_rate
+          @frames = target_frames
+          return
+        end
+
+        ratio = sample_rate.to_f / target_rate
+        new_buffer = Util.build_buffer(self, channels: channels, frames: target_frames, sample_rate: target_rate)
+
+        target_frames.times do |frame_idx|
+          source_position = frame_idx * ratio
+          left_idx = source_position.floor
+          right_idx = [left_idx + 1, frames - 1].min
+          t = source_position - left_idx
+
+          left_frame = buffer.read_frame(left_idx)
+          right_frame = buffer.read_frame(right_idx)
+
+          samples = Array.new(channels) do |channel_idx|
+            left = sample_to_float(left_frame[channel_idx])
+            right = sample_to_float(right_frame[channel_idx])
+            value = if left_idx == right_idx
+                      left
+                    else
+                      left + (right - left) * t
+                    end
+            encode_value(value)
+          end
+
+          new_buffer.write_frame(frame_idx, samples)
+        end
+
+        initialize_from_buffer(new_buffer)
+        @sample_rate = target_rate
+        @frames = target_frames
+      end
+    end
+  end
+end

data/lib/sound_util/filter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Filter
+    autoload :Mixin, "sound_util/filter/_mixin"
+    autoload :Gain, "sound_util/filter/gain"
+    autoload :Fade, "sound_util/filter/fade"
+    autoload :Combine, "sound_util/filter/combine"
+    autoload :Resample, "sound_util/filter/resample"
+  end
+end

data/lib/sound_util/generator/combine.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Generator
+    module Combine
+      def generate_appended_wave(left:, right:)
+        Util.ensure_same_kind!(left, right)
+        Util.assert_dimensions!(right, channels: left.channels)
+
+        buffer = build_appended_buffer(left, right)
+        Util.build_wave_from_buffer(left, buffer)
+      end
+
+      def generate_mixed_wave(left:, right:)
+        Util.ensure_same_kind!(left, right)
+        Util.assert_dimensions!(right, channels: left.channels)
+
+        frames = [left.frames, right.frames].max
+        buffer = Util.build_buffer(left, channels: left.channels, frames: frames)
+
+        info = left.format_info
+        zero = Util.zero_frame(left.channels)
+
+        frames.times do |frame_idx|
+          left_frame = frame_idx < left.frames ? left.buffer.read_frame(frame_idx) : zero
+          right_frame = frame_idx < right.frames ? right.buffer.read_frame(frame_idx) : zero
+
+          samples = Array.new(buffer.channels) do |channel_idx|
+            mix_sample(left_frame[channel_idx], right_frame[channel_idx], info)
+          end
+
+          buffer.write_frame(frame_idx, samples)
+        end
+
+        Util.build_wave_from_buffer(left, buffer)
+      end
+
+      def generate_stacked_wave(primary:, secondary:)
+        Util.ensure_same_kind!(primary, secondary)
+
+        frames = [primary.frames, secondary.frames].max
+        total_channels = primary.channels + secondary.channels
+
+        buffer = Util.build_buffer(primary, channels: total_channels, frames: frames)
+
+        primary_zero = Util.zero_frame(primary.channels)
+        secondary_zero = Util.zero_frame(secondary.channels)
+
+        frames.times do |frame_idx|
+          primary_frame = frame_idx < primary.frames ? primary.buffer.read_frame(frame_idx) : primary_zero
+          secondary_frame = frame_idx < secondary.frames ? secondary.buffer.read_frame(frame_idx) : secondary_zero
+
+          buffer.write_frame(frame_idx, primary_frame + secondary_frame)
+        end
+
+        Util.build_wave_from_buffer(primary, buffer)
+      end
+
+      private
+
+      def build_appended_buffer(left, right)
+        buffer = Util.build_buffer(left, channels: left.channels, frames: left.frames + right.frames)
+
+        destination = buffer.io_buffer
+        destination.copy(left.buffer.io_buffer, 0)
+        destination.copy(right.buffer.io_buffer, left.buffer.size)
+        buffer
+      end
+
+      def mix_sample(first, second, info)
+        (first + second).clamp(info[:min], info[:max])
+      end
+    end
+  end
+end

data/lib/sound_util/generator/tone.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Generator
+    module Tone
+      DEFAULTS = {
+        sample_rate: 44_100,
+        channels: 1,
+        amplitude: 1.0,
+        phase: 0.0,
+        format: :s16le
+      }.freeze
+
+      def sine(duration_seconds:, frequency:, **options)
+        opts = DEFAULTS.merge(options)
+        sample_rate = opts[:sample_rate]
+        frames = (duration_seconds * sample_rate).to_i
+        new(channels: opts[:channels], sample_rate: sample_rate, frames: frames, format: opts[:format]) do |frame_idx|
+          t = frame_idx.to_f / sample_rate
+          Math.sin((2.0 * Math::PI * frequency * t) + opts[:phase]) * opts[:amplitude]
+        end
+      end
+
+      def silence(duration_seconds:, **options)
+        opts = DEFAULTS.merge(options)
+        sample_rate = opts[:sample_rate]
+        frames = (duration_seconds * sample_rate).to_i
+        new(channels: opts[:channels], sample_rate: sample_rate, frames: frames, format: opts[:format])
+      end
+    end
+  end
+end

data/lib/sound_util/generator.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Generator
+    autoload :Tone, "sound_util/generator/tone"
+    autoload :Combine, "sound_util/generator/combine"
+  end
+end

data/lib/sound_util/magic.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module SoundUtil
+  module Magic
+    MAGIC_HEADERS = {
+      wav: %w[RIFF RF64]
+    }.freeze
+
+    module_function
+
+    def bytes_needed = 12
+
+    def detect(data)
+      return nil unless data && data.bytesize >= bytes_needed
+
+      chunk_id = data.byteslice(0, 4)
+      format = data.byteslice(8, 4)
+
+      return :wav if MAGIC_HEADERS[:wav].include?(chunk_id) && format == "WAVE"
+
+      nil
+    end
+
+    def detect_io(io)
+      pos = io.pos
+      data = io.read(bytes_needed)
+      io.seek(pos)
+      [detect(data), io]
+    rescue Errno::ESPIPE, IOError
+      data = io.read(bytes_needed)
+      fmt = detect(data)
+      prefix = (data || "").b
+      combined = prefix + (io.read || "")
+      new_io = StringIO.new(combined)
+      [fmt, new_io]
+    end
+  end
+end

data/lib/sound_util/sink/playback.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Sink
+    module Playback
+      FORMAT_FLAGS = {
+        u8: "U8",
+        s16le: "S16_LE",
+        s24le: "S24_LE",
+        s32le: "S32_LE",
+        f32le: "FLOAT_LE",
+        f64le: "FLOAT64_LE"
+      }.freeze
+
+      DEFAULT_COMMAND = lambda do |wave|
+        flag = FORMAT_FLAGS[wave.format]
+        raise SoundUtil::Error, "unsupported playback format: #{wave.format}" unless flag
+
+        [
+          "aplay",
+          "-t", "raw",
+          "-f", flag,
+          "-c", wave.channels.to_s,
+          "-r", wave.sample_rate.to_s,
+          "-"
+        ]
+      end
+
+      def play(command: nil, io: nil)
+        if io
+          pipe(io)
+          return self
+        end
+
+        cmd = build_command(command)
+        IO.popen(cmd, "wb") do |handle|
+          pipe(handle)
+          handle.close_write
+          Process.wait(handle.pid) if handle.respond_to?(:pid)
+        end
+        self
+      rescue Errno::ENOENT
+        cmd_display = cmd.is_a?(Array) ? cmd.join(" ") : cmd.to_s
+        raise SoundUtil::Error, "playback command not found: #{cmd_display}"
+      end
+
+      private
+
+      def build_command(command)
+        return command unless command.nil?
+
+        DEFAULT_COMMAND.call(self)
+      end
+    end
+  end
+end

data/lib/sound_util/sink/preview.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "image_util"
+
+module SoundUtil
+  module Sink
+    module Preview
+      DEFAULT_WIDTH = 600
+      DEFAULT_HEIGHT = 28
+
+      def preview(io = $stdout, width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, caption: nil)
+        renderer = PreviewRenderer.new(self, width: width, height: height, caption: caption)
+        rendered = renderer.render
+        io.puts(rendered || "[wave preview unavailable]")
+        self
+      rescue LoadError
+        io.puts "[wave preview unavailable]"
+        self
+      end
+
+      def preview_image(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, caption: nil)
+        PreviewRenderer.new(self, width: width, height: height, caption: caption).image
+      end
+
+      class PreviewRenderer
+        BACKGROUND_COLOR = [12, 12, 18, 255].freeze
+        AXIS_COLOR = [60, 60, 80, 255].freeze
+        CHANNEL_COLORS = [
+          [90, 200, 255, 255],
+          [255, 140, 220, 255],
+          [180, 255, 140, 255]
+        ].freeze
+        TEXT_COLOR = [235, 235, 235, 255].freeze
+
+        def initialize(wave, width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, caption: nil)
+          @wave = wave
+          @width = [[width, 16].max, 1000].min
+          @height = [[height, 16].max, 64].min
+          @caption = caption
+        end
+
+        def render
+          ImageUtil::Terminal.output_image($stdin, $stdout, image)
+        end
+
+        def image
+          @image ||= build_image
+        end
+
+        private
+
+        attr_reader :wave, :width, :height, :caption
+
+        def build_image
+          img = ImageUtil::Image.new(width, height) { BACKGROUND_COLOR }
+          draw_axes(img)
+          draw_waveform(img)
+          draw_caption(img)
+          img
+        end
+
+        def draw_axes(image)
+          mid = (height - 1) / 2
+          width.times { |x| image[x, mid] = AXIS_COLOR }
+          height.times { |y| image[0, y] = AXIS_COLOR }
+        end
+
+        def draw_waveform(image)
+          return if wave.frames.zero?
+
+          mid = (height - 1) / 2.0
+          scale = (height - 1) / 2.0
+          step = [wave.frames.to_f / width, 1.0].max
+
+          width.times do |x|
+            start_idx = (x * step).floor
+            end_idx = [((x + 1) * step).ceil, wave.frames - 1].min
+            next if start_idx.negative? || start_idx >= wave.frames
+
+            wave.channels.times do |channel_idx|
+              min_amp = 1.0
+              max_amp = -1.0
+
+              start_idx.upto(end_idx) do |frame_idx|
+                sample = wave.send(:sample_to_float, wave.buffer.read_frame(frame_idx)[channel_idx])
+                min_amp = sample if sample < min_amp
+                max_amp = sample if sample > max_amp
+              end
+
+              top = amplitude_to_y(max_amp, mid, scale)
+              bottom = amplitude_to_y(min_amp, mid, scale)
+              bottom, top = top, bottom if bottom < top
+              color = CHANNEL_COLORS[channel_idx % CHANNEL_COLORS.length]
+
+              top.upto(bottom) { |y| image[x, y] = color }
+
+              middle_sample = wave.send(:sample_to_float, wave.buffer.read_frame((start_idx + end_idx) / 2)[channel_idx])
+              point_y = amplitude_to_y(middle_sample, mid, scale)
+              image[x, point_y] = highlight_color(color)
+            end
+          end
+        end
+
+        def draw_icon(image)
+          base_x = [2, width - 8].min
+          base_y = 2
+          ICON_COORDS.each do |dx, dy|
+            x = base_x + dx
+            y = base_y + dy
+            next if x >= width || y >= height
+
+            image[x, y] = ICON_COLOR
+          end
+        end
+
+        def draw_caption(image)
+          text = caption || Kernel.format("%dch %dHz %d frames %.2gs", wave.channels, wave.sample_rate, wave.frames, wave.duration)
+          baseline = height - 8
+          baseline = [baseline, 1].max
+          image.bitmap_text!(text, 2, baseline, color: TEXT_COLOR)
+        end
+
+        def amplitude_to_y(amplitude, mid, scale)
+          y = mid - amplitude * scale
+          [[y.round, 0].max, height - 1].min
+        end
+
+        def highlight_color(color)
+          dup_color = color.dup
+          3.times { |idx| dup_color[idx] = [[dup_color[idx] + 40, 255].min, 0].max }
+          dup_color
+        end
+      end
+    end
+  end
+end

data/lib/sound_util/sink.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SoundUtil
+  module Sink
+    autoload :Playback, "sound_util/sink/playback"
+    autoload :Preview, "sound_util/sink/preview"
+  end
+end