ffi-sndfile 0.1.0

data/lib/sndfile/native/structs.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module SndFile
+  # FFI::Struct definitions for the structs in sndfile.h, in the order of
+  # that header. Field names follow the C names.
+  module Native
+    # Helpers for structs with fixed-size char arrays: read them as Ruby
+    # strings (up to the first NUL) and write Ruby strings into them.
+    module CharArrayFields
+      # The char array +field+ as a String, up to the first NUL byte.
+      def string(field)
+        self[field].to_ptr.get_bytes(0, self[field].size).unpack1("Z*")
+      end
+
+      # Writes +value+ into the char array +field+, NUL-padded. A value may
+      # fill the array exactly; a longer one raises ArgumentError.
+      def set_string(field, value)
+        bytes = value.to_s.b
+        size = self[field].size
+        raise ArgumentError, "#{field} is at most #{size} bytes, got #{bytes.bytesize}" if bytes.bytesize > size
+
+        self[field].to_ptr.put_bytes(0, bytes.ljust(size, "\0"))
+        value
+      end
+    end
+
+    # SF_INFO: passed to sf_open, which fills it in when reading and reads
+    # it when writing.
+    class Info < FFI::Struct
+      layout :frames,     :int64,
+             :samplerate, :int,
+             :channels,   :int,
+             :format,     :int,
+             :sections,   :int,
+             :seekable,   :int
+    end
+
+    # SF_FORMAT_INFO: describes a format (SFC_GET_FORMAT_INFO and friends).
+    class FormatInfo < FFI::Struct
+      layout :format,    :int,
+             :name,      :string,
+             :extension, :string
+    end
+
+    # SF_DITHER_INFO (reserved for future use by libsndfile).
+    class DitherInfo < FFI::Struct
+      layout :type,  :int,
+             :level, :double,
+             :name,  :string
+    end
+
+    # SF_EMBED_FILE_INFO: where a sound file sits inside a larger file.
+    class EmbedFileInfo < FFI::Struct
+      layout :offset, :int64,
+             :length, :int64
+    end
+
+    # SF_CUE_POINT: one cue marker.
+    class CuePoint < FFI::Struct
+      include CharArrayFields
+
+      layout :indx,          :int32,
+             :position,      :uint32,
+             :fcc_chunk,     :int32,
+             :chunk_start,   :int32,
+             :block_start,   :int32,
+             :sample_offset, :uint32,
+             :name,          [:char, 256]
+    end
+
+    # SF_CUES: up to 100 cue markers (SFC_GET_CUE / SFC_SET_CUE).
+    class Cues < FFI::Struct
+      MAX_CUE_POINTS = 100
+
+      layout :cue_count,  :uint32,
+             :cue_points, [CuePoint, MAX_CUE_POINTS]
+    end
+
+    # SF_INSTRUMENT: sampler instrument data (SFC_GET/SET_INSTRUMENT).
+    class Instrument < FFI::Struct
+      # One entry of SF_INSTRUMENT's loops array.
+      class Loop < FFI::Struct
+        layout :mode,  :int,
+               :start, :uint32,
+               :end,   :uint32,
+               :count, :uint32
+      end
+
+      MAX_LOOPS = 16
+
+      layout :gain,        :int,
+             :basenote,    :char,
+             :detune,      :char,
+             :velocity_lo, :char,
+             :velocity_hi, :char,
+             :key_lo,      :char,
+             :key_hi,      :char,
+             :loop_count,  :int,
+             :loops,       [Loop, MAX_LOOPS]
+    end
+
+    # SF_LOOP_INFO: loop/tempo information (SFC_GET_LOOP_INFO).
+    class LoopInfo < FFI::Struct
+      layout :time_sig_num, :short,
+             :time_sig_den, :short,
+             :loop_mode,    :int,
+             :num_beats,    :int,
+             :bpm,          :float,
+             :root_key,     :int,
+             :future,       [:int, 6]
+    end
+
+    # SF_BROADCAST_INFO: the Broadcast WAV "bext" chunk, with 256 bytes of
+    # coding history (SFC_GET/SET_BROADCAST_INFO).
+    class BroadcastInfo < FFI::Struct
+      include CharArrayFields
+
+      layout :description,            [:char, 256],
+             :originator,             [:char, 32],
+             :originator_reference,   [:char, 32],
+             :origination_date,       [:char, 10],
+             :origination_time,       [:char, 8],
+             :time_reference_low,     :uint32,
+             :time_reference_high,    :uint32,
+             :version,                :short,
+             :umid,                   [:char, 64],
+             :loudness_value,         :int16,
+             :loudness_range,         :int16,
+             :max_true_peak_level,    :int16,
+             :max_momentary_loudness, :int16,
+             :max_shortterm_loudness, :int16,
+             :reserved,               [:char, 180],
+             :coding_history_size,    :uint32,
+             :coding_history,         [:char, 256]
+    end
+
+    # SF_CART_TIMER: one post timer of SF_CART_INFO.
+    class CartTimer < FFI::Struct
+      include CharArrayFields
+
+      layout :usage, [:char, 4],
+             :value, :int32
+    end
+
+    # SF_CART_INFO: the AES46 "cart" chunk, with 256 bytes of tag text
+    # (SFC_GET/SET_CART_INFO).
+    class CartInfo < FFI::Struct
+      include CharArrayFields
+
+      layout :version,              [:char, 4],
+             :title,                [:char, 64],
+             :artist,               [:char, 64],
+             :cut_id,               [:char, 64],
+             :client_id,            [:char, 64],
+             :category,             [:char, 64],
+             :classification,       [:char, 64],
+             :out_cue,              [:char, 64],
+             :start_date,           [:char, 10],
+             :start_time,           [:char, 8],
+             :end_date,             [:char, 10],
+             :end_time,             [:char, 8],
+             :producer_app_id,      [:char, 64],
+             :producer_app_version, [:char, 64],
+             :user_def,             [:char, 64],
+             :level_reference,      :int32,
+             :post_timers,          [CartTimer, 8],
+             :reserved,             [:char, 276],
+             :url,                  [:char, 1024],
+             :tag_text_size,        :uint32,
+             :tag_text,             [:char, 256]
+    end
+
+    # SF_VIRTUAL_IO: the callbacks sf_open_virtual uses instead of a file.
+    # Every callback gets the user_data pointer passed to sf_open_virtual.
+    class VirtualIO < FFI::Struct
+      layout :get_filelen, callback([:pointer], :int64),
+             :seek,        callback(%i[int64 int pointer], :int64),
+             :read,        callback(%i[pointer int64 pointer], :int64),
+             :write,       callback(%i[pointer int64 pointer], :int64),
+             :tell,        callback([:pointer], :int64)
+    end
+
+    # SF_CHUNK_INFO: a chunk of a sound file (sf_set_chunk and the chunk
+    # iterator functions).
+    class ChunkInfo < FFI::Struct
+      include CharArrayFields
+
+      layout :id,      [:char, 64],
+             :id_size, :uint,
+             :datalen, :uint,
+             :data,    :pointer
+    end
+  end
+end

data/lib/sndfile/native.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "sndfile/constants"
+require "sndfile/library_version"
+
+module SndFile
+  # The libsndfile bindings: an FFI::Library with every function in
+  # sndfile.h, plus the structs and enums those functions use.
+  module Native
+    extend FFI::Library
+
+    ffi_lib ["sndfile", "libsndfile.so.1", "libsndfile.1.dylib", "libsndfile-1"]
+
+    typedef :pointer, :sndfile
+    typedef :int64, :sf_count_t
+
+    # Attached first, so the version check below can run before the other
+    # functions: attaching a function that an older libsndfile lacks would
+    # fail with an unclear FFI::NotFoundError.
+    attach_function :sf_version_string, [], :string
+    LibraryVersion.ensure_supported!
+  end
+end
+
+require "sndfile/native/enums"
+require "sndfile/native/structs"
+require "sndfile/native/handle"
+require "sndfile/native/functions"

data/lib/sndfile/sound_file.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module SndFile
+  # A sound file opened for reading, writing or both.
+  #
+  # Samples are flat Arrays with the channels interleaved: left, right, left,
+  # right, ... for stereo. They are :float (the default, -1.0..1.0), :double,
+  # :short or :int; libsndfile converts them from and to the file's encoding.
+  class SoundFile
+    include Commands
+
+    SAMPLE_TYPES = { short: :short, int: :int, float: :float, double: :double }.freeze
+
+    # Frames per read in #each_buffer and #read without a frame count.
+    DEFAULT_BUFFER_FRAMES = 4096
+
+    # The path, or the IO object for files opened through VirtualIO.
+    attr_reader :target
+
+    # :read, :write or :rdwr.
+    attr_reader :mode
+
+    # Opens a sound file. Without a block, returns the SoundFile. With a
+    # block, yields it, closes it afterwards (also when the block raises)
+    # and returns the block's value.
+    def self.open(target, mode = :read, **, &)
+      file = new(target, mode, **)
+      return file unless block_given?
+
+      begin
+        yield file
+      ensure
+        file.close
+      end
+    end
+
+    # Opens +target+, a path or an IO-like object (see VirtualIO), in +mode+
+    # :read, :write or :rdwr.
+    #
+    # Writing needs +samplerate+, +channels+ and a +format+: anything
+    # Format.coerce accepts, with an optional +subtype+ and +endian+. Without
+    # a format, it follows the path's extension. Reading RAW files needs the
+    # same options. +strings+ are set before any audio is written.
+    def initialize(target, mode = :read, format: nil, subtype: nil, endian: nil, samplerate: nil, channels: nil,
+                   strings: nil)
+      @target = target
+      @mode = Native.enum_type(:sf_mode).find(Native.enum_type(:sf_mode).to_native(mode, nil))
+      info = native_info(format_for(format, subtype, endian), samplerate, channels)
+      @handle = open_handle(target, info)
+      self.strings.update(strings) if strings
+    end
+
+    # The file's current Info (SFC_GET_CURRENT_SF_INFO), which includes the
+    # frames written so far.
+    def info
+      struct = Native::Info.new
+      command(SFC_GET_CURRENT_SF_INFO, struct)
+      Info.from_native(struct)
+    end
+
+    def frames = info.frames
+    def samplerate = info.samplerate
+    def channels = info.channels
+    def format = info.format
+    def sections = info.sections
+    def seekable? = info.seekable?
+    def duration = info.duration
+
+    # The string metadata (title, artist, ...); see Strings.
+    def strings
+      @strings ||= Strings.new(self)
+    end
+
+    # The current byte rate (bytes of audio per second), or nil if unknown.
+    def byterate
+      rate = Native.sf_current_byterate(handle)
+      rate unless rate.negative?
+    end
+
+    # Reads up to +frames+ frames and returns their samples as a flat,
+    # interleaved Array (empty at the end of the file). Without +frames+,
+    # reads everything up to the end of the file.
+    def read(frames = nil, type: :float)
+      return read_all(type) if frames.nil?
+
+      ffi_type = ffi_type_for(type)
+      channel_count = channels
+      buffer = FFI::MemoryPointer.new(ffi_type, frames * channel_count)
+      read_frames = Native.public_send(:"sf_readf_#{type}", handle, buffer, frames)
+      check_io!
+      buffer.public_send(:"get_array_of_#{ffi_type}", 0, read_frames * channel_count)
+    end
+
+    # Yields the samples of each buffer of up to +frames+ frames until the
+    # end of the file. Returns an Enumerator without a block.
+    def each_buffer(frames = DEFAULT_BUFFER_FRAMES, type: :float)
+      return enum_for(:each_buffer, frames, type: type) unless block_given?
+
+      loop do
+        samples = read(frames, type: type)
+        break if samples.empty?
+
+        yield samples
+      end
+      self
+    end
+
+    # Reads up to +bytes+ bytes of the encoded audio data (sf_read_raw).
+    def read_raw(bytes)
+      buffer = FFI::MemoryPointer.new(:char, bytes)
+      count = Native.sf_read_raw(handle, buffer, bytes)
+      check_io!
+      buffer.get_bytes(0, count)
+    end
+
+    # Writes +samples+, a flat interleaved Array whose size is a multiple of
+    # the channel count. Returns the number of frames written.
+    def write(samples, type: :float)
+      ffi_type = ffi_type_for(type)
+      frames = frame_count(samples)
+      return 0 if frames.zero?
+
+      buffer = FFI::MemoryPointer.new(ffi_type, samples.size)
+      buffer.public_send(:"put_array_of_#{ffi_type}", 0, samples)
+      written = Native.public_send(:"sf_writef_#{type}", handle, buffer, frames)
+      check_io!(failed: written < frames)
+      written
+    end
+
+    # Writes +samples+ as floats and returns the file, for chaining.
+    def <<(samples)
+      write(samples)
+      self
+    end
+
+    # Writes +data+, already encoded in the file's format (sf_write_raw).
+    # Returns the number of bytes written.
+    def write_raw(data)
+      bytes = data.to_s.b
+      buffer = FFI::MemoryPointer.new(:char, bytes.bytesize)
+      buffer.put_bytes(0, bytes)
+      written = Native.sf_write_raw(handle, buffer, bytes.bytesize)
+      check_io!(failed: written < bytes.bytesize)
+      written
+    end
+
+    # Forces written data to disk (sf_write_sync).
+    def sync
+      Native.sf_write_sync(handle)
+      self
+    end
+
+    # Moves to frame +frames+, relative to +whence+ (:set, :cur or :end).
+    # Returns the new position in frames.
+    def seek(frames, whence = :set)
+      position = Native.sf_seek(handle, frames, whence)
+      check_io!(failed: position.negative?)
+      position
+    end
+
+    # The current position in frames.
+    def tell
+      seek(0, :cur)
+    end
+    alias pos tell
+
+    def rewind
+      seek(0, :set)
+      self
+    end
+
+    # Closes the file, writing any buffered data and the final header. Does
+    # nothing when it is already closed.
+    def close
+      return if closed?
+
+      result = Native.sf_close(handle)
+      @closed = true
+      @virtual_io&.raise_error!
+      Error.check_error(result)
+      nil
+    end
+
+    def closed?
+      @closed == true
+    end
+
+    # libsndfile's description of the last error on this file.
+    def error_message
+      Native.sf_strerror(handle)
+    end
+
+    # The Native::Handle. Raises ClosedFileError once the file is closed.
+    def handle
+      raise ClosedFileError, "#{inspect} is closed" if closed?
+
+      @handle
+    end
+
+    def inspect
+      state = closed? ? "closed" : "#{format} #{channels}ch #{samplerate}Hz"
+      "#<#{self.class.name} #{target_name} (#{mode}, #{state})>"
+    end
+
+    private
+
+    def format_for(format, subtype, endian)
+      return Format.coerce(format, subtype, endian) if format
+      return unless mode == :write
+
+      return Format.for_path(target) if path?(target)
+
+      raise ArgumentError, "A format is needed to write to #{target.class}"
+    end
+
+    def native_info(format, samplerate, channels)
+      check_write_options(format, samplerate, channels) if mode == :write
+      Native::Info.new.tap do |info|
+        info[:format] = format.to_i if format
+        info[:samplerate] = samplerate.to_i if samplerate
+        info[:channels] = channels.to_i if channels
+      end
+    end
+
+    def check_write_options(format, samplerate, channels)
+      raise ArgumentError, "Cannot tell the format of #{target_name}; pass format:" unless format
+
+      missing = { samplerate: samplerate, channels: channels }.select { |_, value| value.nil? }.keys
+      raise ArgumentError, "Writing needs #{missing.join(" and ")}" if missing.any?
+      return if format.valid?(samplerate: samplerate, channels: channels)
+
+      raise ArgumentError, "libsndfile cannot write #{format} with #{samplerate} Hz and #{channels} channel(s)"
+    end
+
+    def open_handle(target, info)
+      if path?(target)
+        Native.sf_open(target.to_s, mode, info)
+      elsif target.respond_to?(:read) || target.respond_to?(:write)
+        @virtual_io = VirtualIO.new(target)
+        open_virtual(info)
+      else
+        raise ArgumentError, "Expected a path or an IO, got #{target.class}"
+      end
+    end
+
+    def open_virtual(info)
+      Native.sf_open_virtual(@virtual_io.struct, mode, info, nil)
+    rescue SndFileError
+      @virtual_io.raise_error!
+      raise
+    end
+
+    def read_all(type)
+      each_buffer(DEFAULT_BUFFER_FRAMES, type: type).reduce([], :concat)
+    end
+
+    def ffi_type_for(type)
+      SAMPLE_TYPES.fetch(type) do
+        raise ArgumentError, "Unknown sample type #{type.inspect}; expected one of #{SAMPLE_TYPES.keys.join(", ")}"
+      end
+    end
+
+    def frame_count(samples)
+      channel_count = channels
+      unless (samples.size % channel_count).zero?
+        raise ArgumentError, "#{samples.size} samples is not a whole number of #{channel_count}-channel frames"
+      end
+
+      samples.size / channel_count
+    end
+
+    # Raises an IO callback's exception, or libsndfile's error when +failed+
+    # (a short write or failed seek) or when libsndfile recorded one.
+    def check_io!(failed: false)
+      @virtual_io&.raise_error!
+      Error.check_sndfile(handle)
+      raise SndFileError, error_message if failed
+    end
+
+    # Strings and Pathnames are paths; anything else is opened as an IO.
+    def path?(target)
+      target.is_a?(String) || (defined?(::Pathname) && target.is_a?(::Pathname))
+    end
+
+    def target_name
+      path?(target) ? target.to_s.inspect : target.class.name
+    end
+  end
+end

data/lib/sndfile/strings.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SndFile
+  # The string metadata of a sound file, such as its title and artist
+  # (sf_get_string / sf_set_string). libsndfile stores them as the format's
+  # own tags: Vorbis comments in Ogg and FLAC, the INFO chunk in WAV. Most
+  # formats need them set before any audio is written.
+  class Strings
+    include Enumerable
+
+    # The string types, in libsndfile's order (SF_STR_*).
+    NAMES = Native.enum_type(:sf_str).symbols.freeze
+
+    def initialize(sound_file)
+      @sound_file = sound_file
+    end
+
+    # The string +name+ (one of NAMES), or nil when the file has none. It is
+    # returned as UTF-8, or as binary when it isn't valid UTF-8.
+    def [](name)
+      value = Native.sf_get_string(@sound_file.handle, name_for(name))
+      return if value.nil?
+
+      utf8 = value.dup.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? ? utf8 : value
+    end
+
+    # Sets the string +name+ (one of NAMES). Raises a SndFileError when the
+    # file format doesn't support it or audio data was already written.
+    def []=(name, value)
+      handle = @sound_file.handle
+      Error.check_error(Native.sf_set_string(handle, name_for(name), value.to_s.encode(Encoding::UTF_8)), handle)
+    end
+
+    NAMES.each do |name|
+      define_method(name) { self[name] }
+      define_method(:"#{name}=") { |value| self[name] = value }
+    end
+    alias track_number tracknumber
+    alias track_number= tracknumber=
+
+    # Sets every string in +hash+, e.g. update(title: "Song", artist: "Me").
+    def update(hash)
+      hash.each { |name, value| self[name] = value }
+      self
+    end
+
+    # Yields each string that is set, as name and value.
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      to_h.each(&)
+      self
+    end
+
+    def to_h
+      NAMES.filter_map { |name| (value = self[name]) && [name, value] }.to_h
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h.inspect}>"
+    end
+
+    private
+
+    def name_for(name)
+      symbol = name.to_s.downcase.to_sym
+      symbol = :tracknumber if symbol == :track_number
+      return symbol if NAMES.include?(symbol)
+
+      raise ArgumentError, "Unknown string #{name.inspect}; expected one of #{NAMES.join(", ")}"
+    end
+  end
+end

data/lib/sndfile/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SndFile
+  VERSION = "0.1.0"
+end

data/lib/sndfile/virtual_io.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SndFile
+  # Lets libsndfile read and write an IO-like object, such as a StringIO,
+  # through sf_open_virtual. The object needs #read or #write, and #seek and
+  # #pos for formats that seek, which most do when writing.
+  #
+  # Exceptions from the IO must not unwind through libsndfile, so they are
+  # kept in #error, and SoundFile raises them again.
+  class VirtualIO
+    # For each SF_VIRTUAL_IO callback: the method that implements it and the
+    # value it returns to libsndfile when the IO raises.
+    CALLBACKS = {
+      get_filelen: [:io_length, -1],
+      seek: [:io_seek, -1],
+      read: [:io_read, 0],
+      write: [:io_write, 0],
+      tell: [:io_tell, -1]
+    }.freeze
+    private_constant :CALLBACKS
+
+    attr_reader :io, :struct, :error
+
+    def initialize(io)
+      @io = io
+      @struct = Native::VirtualIO.new
+      # The struct only holds C function pointers; keep the procs referenced
+      # so they aren't garbage collected while libsndfile may call them.
+      @callbacks = callbacks
+      @callbacks.each { |name, callback| @struct[name] = callback }
+    end
+
+    # Raises (and clears) the exception an IO callback caught, if any.
+    def raise_error!
+      return unless @error
+
+      error = @error
+      @error = nil
+      raise error
+    end
+
+    private
+
+    # The procs ignore the user_data pointer libsndfile passes last.
+    def callbacks
+      CALLBACKS.transform_values do |(method_name, failure_value)|
+        ->(*args) { guard(failure_value) { send(method_name, *args[0...-1]) } }
+      end
+    end
+
+    def guard(failure_value)
+      yield
+    rescue StandardError => e
+      @error ||= e
+      failure_value
+    end
+
+    def io_length
+      return io.size if io.respond_to?(:size)
+      return io.stat.size if io.respond_to?(:stat)
+
+      -1
+    end
+
+    def io_seek(offset, whence)
+      io.seek(offset, whence)
+      io.pos
+    end
+
+    def io_read(ptr, count)
+      data = io.read(count)
+      return 0 if data.nil? || data.empty?
+
+      ptr.put_bytes(0, data)
+      data.bytesize
+    end
+
+    def io_write(ptr, count)
+      io.write(ptr.get_bytes(0, count))
+    end
+
+    def io_tell
+      io.pos
+    end
+  end
+end