wavify 0.1.0

data/lib/wavify/codecs/raw.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Codecs
+    # Raw PCM/float sample codec.
+    #
+    # Since raw audio has no container metadata, callers must provide a
+    # {Wavify::Core::Format} when reading/stream-reading/metadata.
+    class Raw < Base
+      # Recognized filename extensions.
+      EXTENSIONS = %w[.raw .pcm].freeze
+
+      class << self
+        # @param io_or_path [String, IO]
+        # @return [Boolean]
+        def can_read?(io_or_path)
+          return true if io_or_path.respond_to?(:read)
+          return false unless io_or_path.is_a?(String)
+
+          EXTENSIONS.include?(File.extname(io_or_path).downcase)
+        end
+
+        # Reads a raw audio file/IO into a sample buffer.
+        #
+        # @param io_or_path [String, IO]
+        # @param format [Wavify::Core::Format]
+        # @return [Wavify::Core::SampleBuffer]
+        def read(io_or_path, format: nil)
+          target_format = validate_format!(format)
+          io, close_io = open_input(io_or_path)
+          data = io.read || "".b
+          samples = decode_samples(data, target_format)
+          Core::SampleBuffer.new(samples, target_format)
+        ensure
+          io.close if close_io && io
+        end
+
+        # Writes a raw audio buffer to a path/IO.
+        #
+        # @param io_or_path [String, IO]
+        # @param sample_buffer [Wavify::Core::SampleBuffer]
+        # @param format [Wavify::Core::Format]
+        # @return [String, IO]
+        def write(io_or_path, sample_buffer, format:)
+          raise InvalidParameterError, "sample_buffer must be Core::SampleBuffer" unless sample_buffer.is_a?(Core::SampleBuffer)
+
+          target_format = validate_format!(format)
+          buffer = sample_buffer.format == target_format ? sample_buffer : sample_buffer.convert(target_format)
+
+          io, close_io = open_output(io_or_path)
+          io.write(encode_samples(buffer.samples, target_format))
+          io.flush if io.respond_to?(:flush)
+          io.rewind if io.respond_to?(:rewind)
+          io_or_path
+        ensure
+          io.close if close_io && io
+        end
+
+        # Streams raw audio decoding in frame chunks.
+        #
+        # @param io_or_path [String, IO]
+        # @param format [Wavify::Core::Format]
+        # @param chunk_size [Integer]
+        # @return [Enumerator]
+        def stream_read(io_or_path, format:, chunk_size: 4096)
+          return enum_for(__method__, io_or_path, format: format, chunk_size: chunk_size) unless block_given?
+
+          target_format = validate_format!(format)
+          io, close_io = open_input(io_or_path)
+          bytes_per_frame = target_format.block_align
+          raw_chunk_size = chunk_size * bytes_per_frame
+
+          loop do
+            chunk = io.read(raw_chunk_size)
+            break if chunk.nil? || chunk.empty?
+
+            raise InvalidFormatError, "raw data chunk does not align with format frame size" unless (chunk.bytesize % bytes_per_frame).zero?
+
+            samples = decode_samples(chunk, target_format)
+            yield Core::SampleBuffer.new(samples, target_format)
+          end
+        ensure
+          io.close if close_io && io
+        end
+
+        # Streams raw audio encoding via a yielded chunk writer.
+        #
+        # @param io_or_path [String, IO]
+        # @param format [Wavify::Core::Format]
+        # @return [Enumerator, String, IO]
+        def stream_write(io_or_path, format:)
+          return enum_for(__method__, io_or_path, format: format) unless block_given?
+
+          target_format = validate_format!(format)
+          io, close_io = open_output(io_or_path)
+
+          writer = lambda do |sample_buffer|
+            raise InvalidParameterError, "stream chunk must be Core::SampleBuffer" unless sample_buffer.is_a?(Core::SampleBuffer)
+
+            buffer = sample_buffer.format == target_format ? sample_buffer : sample_buffer.convert(target_format)
+            io.write(encode_samples(buffer.samples, target_format))
+          end
+
+          yield writer
+          io.flush if io.respond_to?(:flush)
+          io.rewind if io.respond_to?(:rewind)
+          io_or_path
+        ensure
+          io.close if close_io && io
+        end
+
+        # Reads raw audio metadata using byte size and explicit format.
+        #
+        # @param io_or_path [String, IO]
+        # @param format [Wavify::Core::Format]
+        # @return [Hash]
+        def metadata(io_or_path, format:)
+          target_format = validate_format!(format)
+          io, close_io = open_input(io_or_path)
+          byte_size = io.respond_to?(:size) ? io.size : io.read&.bytesize.to_i
+          sample_frames = byte_size / target_format.block_align
+
+          {
+            format: target_format,
+            sample_frame_count: sample_frames,
+            duration: Core::Duration.from_samples(sample_frames, target_format.sample_rate)
+          }
+        ensure
+          io.close if close_io && io
+        end
+
+        private
+
+        def validate_format!(format)
+          raise InvalidFormatError, "format is required for raw pcm codec" unless format.is_a?(Core::Format)
+
+          format
+        end
+
+        def decode_samples(data, format)
+          if format.sample_format == :float
+            return data.unpack("e*") if format.bit_depth == 32
+            return data.unpack("E*") if format.bit_depth == 64
+          elsif format.sample_format == :pcm
+            return data.unpack("C*").map { |byte| byte - 128 } if format.bit_depth == 8
+            return data.unpack("s<*") if format.bit_depth == 16
+            return decode_pcm24(data) if format.bit_depth == 24
+            return data.unpack("l<*") if format.bit_depth == 32
+          end
+
+          raise UnsupportedFormatError, "unsupported raw format: #{format.sample_format}/#{format.bit_depth}"
+        end
+
+        def encode_samples(samples, format)
+          if format.sample_format == :float
+            normalized = samples.map { |sample| sample.to_f.clamp(-1.0, 1.0) }
+            return normalized.pack("e*") if format.bit_depth == 32
+            return normalized.pack("E*") if format.bit_depth == 64
+          elsif format.sample_format == :pcm
+            min = -(2**(format.bit_depth - 1))
+            max = (2**(format.bit_depth - 1)) - 1
+            ints = samples.map { |sample| sample.to_i.clamp(min, max) }
+            return ints.map { |sample| sample + 128 }.pack("C*") if format.bit_depth == 8
+            return ints.pack("s<*") if format.bit_depth == 16
+            return encode_pcm24(ints) if format.bit_depth == 24
+            return ints.pack("l<*") if format.bit_depth == 32
+          end
+
+          raise UnsupportedFormatError, "unsupported raw format: #{format.sample_format}/#{format.bit_depth}"
+        end
+
+        def decode_pcm24(data)
+          bytes = data.unpack("C*")
+          bytes.each_slice(3).map do |b0, b1, b2|
+            value = b0 | (b1 << 8) | (b2 << 16)
+            value -= 0x1000000 if value.anybits?(0x800000)
+            value
+          end
+        end
+
+        def encode_pcm24(samples)
+          bytes = samples.flat_map do |sample|
+            value = sample
+            value += 0x1000000 if value.negative?
+            [value & 0xFF, (value >> 8) & 0xFF, (value >> 16) & 0xFF]
+          end
+          bytes.pack("C*")
+        end
+
+      end
+    end
+  end
+end

data/lib/wavify/codecs/registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Codecs
+    # Selects a codec implementation by extension and/or magic bytes.
+    class Registry
+      # Probe lambdas used to match container signatures from leading bytes.
+      MAGIC_PROBES = {
+        "RIFF" => lambda do |bytes|
+          bytes.bytesize >= 12 && bytes.start_with?("RIFF") && bytes[8, 4] == "WAVE"
+        end,
+        "fLaC" => ->(bytes) { bytes.start_with?("fLaC") },
+        "OggS" => ->(bytes) { bytes.start_with?("OggS") },
+        "FORM" => lambda do |bytes|
+          bytes.bytesize >= 12 && bytes.start_with?("FORM") && bytes[8, 4] == "AIFF"
+        end
+      }.freeze
+
+      # Extension-to-codec mapping for path-based detection.
+      EXTENSIONS = {
+        ".wav" => Wav,
+        ".wave" => Wav,
+        ".flac" => Flac,
+        ".ogg" => OggVorbis,
+        ".oga" => OggVorbis,
+        ".aiff" => Aiff,
+        ".aif" => Aiff,
+        ".raw" => Raw,
+        ".pcm" => Raw
+      }.freeze
+
+      # Probe order for magic-byte detection.
+      MAGIC_CODEC_ORDER = [
+        ["RIFF", Wav],
+        ["fLaC", Flac],
+        ["OggS", OggVorbis],
+        ["FORM", Aiff]
+      ].freeze
+
+      class << self
+        # Detects the codec for a path or IO object.
+        #
+        # @param io_or_path [String, IO]
+        # @return [Class] codec class
+        def detect(io_or_path)
+          detect_by_extension(io_or_path) || detect_by_magic(io_or_path) || raise_not_found(io_or_path)
+        end
+
+        private
+
+        def detect_by_extension(io_or_path)
+          return unless io_or_path.is_a?(String)
+
+          EXTENSIONS[File.extname(io_or_path).downcase]
+        end
+
+        def detect_by_magic(io_or_path)
+          io, close_io = ensure_io(io_or_path)
+          return unless io
+
+          probe = io.read(12)
+          io.rewind if io.respond_to?(:rewind)
+          MAGIC_CODEC_ORDER.each do |magic_key, codec|
+            return codec if MAGIC_PROBES.fetch(magic_key).call(probe)
+          end
+
+          nil
+        ensure
+          io.close if close_io && io
+        end
+
+        def ensure_io(io_or_path)
+          return [io_or_path, false] if io_or_path.respond_to?(:read)
+          return [nil, false] unless io_or_path.is_a?(String) && File.file?(io_or_path)
+
+          [File.open(io_or_path, "rb"), true]
+        rescue Errno::ENOENT
+          [nil, false]
+        end
+
+        def raise_not_found(io_or_path)
+          raise CodecNotFoundError, "codec not found for input: #{io_or_path.inspect}"
+        end
+      end
+    end
+  end
+end