ffi-sndfile 0.1.0

data/lib/sndfile/error.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Exception classes for libsndfile errors.
+module SndFile
+  # Base class of every error this gem raises for libsndfile. #code is
+  # libsndfile's error number (see sf_error), or nil when there is none.
+  class SndFileError < StandardError
+    attr_reader :code
+
+    def initialize(message = nil, code: nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  class UnrecognisedFormatError < SndFileError; end
+  class SystemError < SndFileError; end
+  class MalformedFileError < SndFileError; end
+  class UnsupportedEncodingError < SndFileError; end
+
+  # Raised when a SoundFile is used after it was closed.
+  class ClosedFileError < SndFileError; end
+
+  # Maps libsndfile's error numbers to exception classes.
+  module Error
+    # libsndfile's public error numbers. It also has many private numbers
+    # (which may change between versions); those raise a plain SndFileError.
+    ERROR_CLASSES = {
+      SF_ERR_UNRECOGNISED_FORMAT => UnrecognisedFormatError,
+      SF_ERR_SYSTEM => SystemError,
+      SF_ERR_MALFORMED_FILE => MalformedFileError,
+      SF_ERR_UNSUPPORTED_ENCODING => UnsupportedEncodingError
+    }.freeze
+
+    # Raises the matching SndFileError for a non-zero libsndfile error
+    # number. The message is the file's error text (sf_strerror) when
+    # +sndfile+ is given, otherwise libsndfile's text for the number.
+    def self.check_error(error_number, sndfile = nil)
+      return unless error_number.is_a?(Integer) && error_number != SF_ERR_NO_ERROR
+
+      raise_error(error_number, sndfile ? file_message(sndfile) : nil)
+    end
+
+    # Raises when libsndfile has recorded an error for +sndfile+ (sf_error).
+    def self.check_sndfile(sndfile)
+      check_error(Native.sf_error(sndfile), sndfile)
+    end
+
+    # Raises the error of a failed sf_open, sf_open_fd or sf_open_virtual,
+    # which libsndfile keeps in global state (sf_error(NULL)). That state is
+    # not cleared, so only call this right after the failure.
+    def self.raise_open_error
+      error_number = Native.sf_error(nil)
+      error_number = SF_ERR_SYSTEM if error_number == SF_ERR_NO_ERROR
+      raise_error(error_number, file_message(nil))
+    end
+
+    def self.raise_error(error_number, message)
+      message ||= number_message(error_number) || "libsndfile error #{error_number}"
+      raise ERROR_CLASSES.fetch(error_number, SndFileError).new(message, code: error_number)
+    end
+
+    # sf_strerror's text, unless it says there is no error. It is more
+    # specific than sf_error_number's, e.g. it names the missing file.
+    def self.file_message(sndfile)
+      message = Native.sf_strerror(sndfile)
+      message unless message.nil? || message.empty? || message == number_message(SF_ERR_NO_ERROR)
+    rescue StandardError
+      nil
+    end
+
+    def self.number_message(error_number)
+      message = Native.sf_error_number(error_number)
+      message unless message.nil? || message.empty?
+    rescue StandardError
+      nil
+    end
+    private_class_method :raise_error, :file_message, :number_message
+  end
+end

data/lib/sndfile/format.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SndFile
+  # A libsndfile format: a major format (the container, such as :ogg), a
+  # subtype (the encoding, such as :vorbis) and an endianness. libsndfile
+  # ORs these together into one integer, which #to_i returns.
+  class Format
+    # The subtype used when only a major format is given.
+    DEFAULT_SUBTYPES = {
+      wav: :pcm_16, wavex: :pcm_16, aiff: :pcm_16, au: :pcm_16, raw: :pcm_16,
+      w64: :pcm_16, caf: :pcm_16, rf64: :pcm_16, flac: :pcm_16,
+      ogg: :vorbis, mpeg: :mpeg_layer_iii
+    }.freeze
+
+    # Formats for common file name extensions, used by Format.for_path.
+    EXTENSIONS = {
+      "wav" => [:wav], "aif" => [:aiff], "aiff" => [:aiff], "aifc" => [:aiff],
+      "au" => [:au], "snd" => [:au], "raw" => [:raw], "w64" => [:w64],
+      "caf" => [:caf], "rf64" => [:rf64], "flac" => [:flac],
+      "ogg" => %i[ogg vorbis], "oga" => %i[ogg vorbis], "opus" => %i[ogg opus],
+      "mp3" => %i[mpeg mpeg_layer_iii]
+    }.freeze
+
+    # Converts +value+ (a Format, an Integer, a major format Symbol or an
+    # Array such as [:ogg, :vorbis]) to a Format.
+    def self.coerce(value, subtype = nil, endian = nil)
+      case value
+      when Format then value
+      when Integer then new(value)
+      when Symbol, String then new(value, subtype, endian || :file)
+      when Array then new(*value)
+      else raise ArgumentError, "Expected a Format, Integer, Symbol or Array, got #{value.class}"
+      end
+    end
+
+    # The format for a file name's extension, or nil for unknown extensions.
+    def self.for_path(path)
+      extension = ::File.extname(path.to_s).delete_prefix(".").downcase
+      EXTENSIONS[extension]&.then { |args| new(*args) }
+    end
+
+    # Builds a format from a major format and subtype (symbols or integer
+    # constants), or from a complete format integer.
+    def initialize(major, subtype = nil, endian = :file)
+      @to_i = if major.is_a?(Integer) && subtype.nil?
+                major
+              else
+                major_code = code(:sf_major_format, major)
+                subtype ||= default_subtype(major_code)
+                major_code | code(:sf_subtype, subtype) | code(:sf_endian, endian)
+              end
+      freeze
+    end
+
+    attr_reader :to_i
+    alias to_int to_i
+
+    # The major format, as a symbol such as :wav (or the integer if unknown).
+    def major
+      symbol(:sf_major_format, to_i & SF_FORMAT_TYPEMASK)
+    end
+
+    # The subtype, as a symbol such as :pcm_16 (or the integer if unknown).
+    def subtype
+      symbol(:sf_subtype, to_i & SF_FORMAT_SUBMASK)
+    end
+
+    # The endianness: :file, :little, :big or :cpu.
+    def endian
+      symbol(:sf_endian, to_i & SF_FORMAT_ENDMASK)
+    end
+
+    # Whether libsndfile can write this format with the given sample rate
+    # and channel count (sf_format_check).
+    def valid?(samplerate:, channels:)
+      info = Native::Info.new
+      info[:format] = to_i
+      info[:samplerate] = samplerate
+      info[:channels] = channels
+      Native.sf_format_check(info) == SF_TRUE
+    end
+
+    def ==(other)
+      other.is_a?(Format) && to_i == other.to_i
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_i].hash
+    end
+
+    # "ogg/vorbis", "wav/pcm_16/big", or just "flac" for a format without a
+    # subtype (as in the Formats listings).
+    def to_s
+      parts = [major, subtype].reject { |part| part.equal?(0) }
+      parts << endian unless endian == :file
+      parts.join("/")
+    end
+
+    def inspect
+      "#<#{self.class.name} #{self}>"
+    end
+
+    private
+
+    def code(enum_name, value)
+      return value if value.is_a?(Integer)
+
+      enum = Native.enum_type(enum_name)
+      enum[value.to_s.downcase.to_sym] or
+        raise ArgumentError, "Unknown #{enum_name.to_s.delete_prefix("sf_").tr("_", " ")}: #{value.inspect}"
+    end
+
+    def default_subtype(major_code)
+      DEFAULT_SUBTYPES.fetch(Native.enum_type(:sf_major_format)[major_code]) do
+        raise ArgumentError, "A subtype is needed for #{symbol(:sf_major_format, major_code).inspect} files"
+      end
+    end
+
+    def symbol(enum_name, value)
+      Native.enum_type(enum_name)[value] || value
+    end
+  end
+end

data/lib/sndfile/formats.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SndFile
+  # A format libsndfile supports, as listed by SndFile.major_formats,
+  # SndFile.subtypes and SndFile.simple_formats: its Format, a description
+  # and (for major and simple formats) the usual file extension.
+  FormatDescription = Data.define(:format, :name, :extension)
+
+  # Lists the formats the loaded libsndfile supports, using its
+  # SFC_GET_FORMAT_* commands.
+  module Formats
+    # The major formats (containers), e.g. "WAV (Microsoft)".
+    def self.major_formats
+      list(SFC_GET_FORMAT_MAJOR_COUNT, SFC_GET_FORMAT_MAJOR)
+    end
+
+    # The subtypes (encodings), e.g. "Signed 16 bit PCM".
+    def self.subtypes
+      list(SFC_GET_FORMAT_SUBTYPE_COUNT, SFC_GET_FORMAT_SUBTYPE)
+    end
+
+    # Common combinations of major format and subtype.
+    def self.simple_formats
+      list(SFC_GET_SIMPLE_FORMAT_COUNT, SFC_GET_SIMPLE_FORMAT)
+    end
+
+    # The description of one format (SFC_GET_FORMAT_INFO), or nil when
+    # libsndfile doesn't know it. Takes a major format or a subtype alone,
+    # as an integer or anything Format.coerce accepts.
+    def self.describe(format)
+      code = format.is_a?(Symbol) ? symbol_code(format) : Format.coerce(format).to_i
+      info = Native::FormatInfo.new
+      info[:format] = code
+      return unless Native.sf_command(nil, SFC_GET_FORMAT_INFO, info, info.size).zero?
+
+      description(info)
+    end
+
+    def self.list(count_command, item_command)
+      count = FFI::MemoryPointer.new(:int)
+      Native.sf_command(nil, count_command, count, count.size)
+      Array.new(count.read_int) do |index|
+        info = Native::FormatInfo.new
+        info[:format] = index
+        Native.sf_command(nil, item_command, info, info.size)
+        description(info)
+      end
+    end
+
+    def self.description(info)
+      FormatDescription.new(format: Format.new(info[:format]), name: info[:name], extension: info[:extension])
+    end
+
+    def self.symbol_code(symbol)
+      Native.enum_type(:sf_major_format)[symbol] || Native.enum_type(:sf_subtype)[symbol] or
+        raise ArgumentError, "Unknown format #{symbol.inspect}"
+    end
+    private_class_method :list, :description, :symbol_code
+  end
+end

data/lib/sndfile/info.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SndFile
+  # What libsndfile knows about an open sound file (its SF_INFO): the number
+  # of frames, sample rate, channel count, Format, number of sections and
+  # whether it is seekable.
+  Info = Data.define(:frames, :samplerate, :channels, :format, :sections, :seekable) do
+    # Builds an Info from a Native::Info struct.
+    def self.from_native(struct)
+      new(frames: struct[:frames],
+          samplerate: struct[:samplerate],
+          channels: struct[:channels],
+          format: Format.new(struct[:format]),
+          sections: struct[:sections],
+          seekable: struct[:seekable] == SF_TRUE)
+    end
+
+    def seekable?
+      seekable
+    end
+
+    # The length in seconds, or nil when the sample rate is unknown.
+    def duration
+      frames.fdiv(samplerate) if samplerate.positive?
+    end
+  end
+end

data/lib/sndfile/library_version.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SndFile
+  # The version of the loaded libsndfile library (sf_version_string), as
+  # returned by SndFile.version.
+  class LibraryVersion
+    include Comparable
+
+    # The oldest libsndfile with every function these bindings attach.
+    # Some sf_command commands are newer: the MPEG formats and
+    # SFC_GET/SET_BITRATE_MODE need 1.1.0.
+    MINIMUM = "1.0.28"
+
+    attr_reader :string, :major, :minor, :patch
+
+    # Raises LoadError when the loaded libsndfile is older than MINIMUM.
+    def self.ensure_supported!
+      version = new
+      return version if version >= MINIMUM
+
+      raise LoadError, "ffi-sndfile needs libsndfile #{MINIMUM} or newer, but found #{version.number}"
+    end
+
+    # Parses a version string such as "libsndfile-1.2.2" (the default is the
+    # loaded library's).
+    def initialize(string = Native.sf_version_string)
+      @string = string
+      match = string.to_s.match(/(\d+)\.(\d+)\.(\d+)/)
+      raise ArgumentError, "Cannot parse libsndfile version #{string.inspect}" unless match
+
+      @major, @minor, @patch = match.captures.map(&:to_i)
+    end
+
+    # "major.minor.patch", e.g. "1.2.2".
+    def number
+      [major, minor, patch].join(".")
+    end
+
+    def <=>(other)
+      other = other.number if other.is_a?(LibraryVersion)
+      Gem::Version.new(number) <=> Gem::Version.new(other.to_s)
+    end
+
+    def to_s
+      @string
+    end
+
+    def inspect
+      "#<#{self.class.name} #{number}>"
+    end
+  end
+end

data/lib/sndfile/native/enums.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SndFile
+  # FFI enum types for the libsndfile constants in SndFile (see
+  # constants.rb). Functions that take these values are attached with the
+  # enum type, so they accept symbols such as :read or :title as well as the
+  # integer constants. Each symbol is the constant's name without its prefix,
+  # in lower case: SFC_SET_VBR_ENCODING_QUALITY is :set_vbr_encoding_quality.
+  module Native
+    # Defines an enum named +name+ from the constants +prefix+<suffix>.
+    def self.constant_enum(name, prefix, suffixes)
+      values = suffixes.flat_map do |suffix|
+        [suffix.downcase.to_sym, SndFile.const_get(:"#{prefix}#{suffix}")]
+      end
+      enum name, values
+    end
+    private_class_method :constant_enum
+
+    constant_enum :sf_major_format, "SF_FORMAT_", %w[
+      WAV AIFF AU RAW PAF SVX NIST VOC IRCAM W64 MAT4 MAT5 PVF XI HTK SDS AVR
+      WAVEX SD2 FLAC CAF WVE OGG MPC2K RF64 MPEG
+    ]
+
+    constant_enum :sf_subtype, "SF_FORMAT_", %w[
+      PCM_S8 PCM_16 PCM_24 PCM_32 PCM_U8 FLOAT DOUBLE ULAW ALAW IMA_ADPCM
+      MS_ADPCM GSM610 VOX_ADPCM NMS_ADPCM_16 NMS_ADPCM_24 NMS_ADPCM_32 G721_32
+      G723_24 G723_40 DWVW_12 DWVW_16 DWVW_24 DWVW_N DPCM_8 DPCM_16 VORBIS OPUS
+      ALAC_16 ALAC_20 ALAC_24 ALAC_32 MPEG_LAYER_I MPEG_LAYER_II MPEG_LAYER_III
+    ]
+
+    constant_enum :sf_endian, "SF_ENDIAN_", %w[FILE LITTLE BIG CPU]
+
+    commands = SndFile.constants.grep(/\ASFC_/).map { |name| name.to_s.delete_prefix("SFC_") }
+    constant_enum :sf_command, "SFC_", commands
+
+    constant_enum :sf_str, "SF_STR_", %w[
+      TITLE COPYRIGHT SOFTWARE ARTIST COMMENT DATE ALBUM LICENSE TRACKNUMBER GENRE
+    ]
+
+    constant_enum :sf_mode, "SFM_", %w[READ WRITE RDWR]
+
+    constant_enum :sf_ambisonic, "SF_AMBISONIC_", %w[NONE B_FORMAT]
+
+    constant_enum :sf_error, "SF_ERR_", %w[
+      NO_ERROR UNRECOGNISED_FORMAT SYSTEM MALFORMED_FILE UNSUPPORTED_ENCODING
+    ]
+
+    constant_enum :sf_channel_map, "SF_CHANNEL_MAP_", %w[
+      INVALID MONO LEFT RIGHT CENTER FRONT_LEFT FRONT_RIGHT FRONT_CENTER
+      REAR_CENTER REAR_LEFT REAR_RIGHT LFE FRONT_LEFT_OF_CENTER
+      FRONT_RIGHT_OF_CENTER SIDE_LEFT SIDE_RIGHT TOP_CENTER TOP_FRONT_LEFT
+      TOP_FRONT_RIGHT TOP_FRONT_CENTER TOP_REAR_LEFT TOP_REAR_RIGHT
+      TOP_REAR_CENTER AMBISONIC_B_W AMBISONIC_B_X AMBISONIC_B_Y AMBISONIC_B_Z
+    ]
+
+    constant_enum :sf_bitrate_mode, "SF_BITRATE_MODE_", %w[CONSTANT AVERAGE VARIABLE]
+
+    constant_enum :sf_dither, "SFD_", %w[NO_DITHER WHITE TRIANGULAR_PDF]
+
+    constant_enum :sf_loop_mode, "SF_LOOP_", %w[NONE FORWARD BACKWARD ALTERNATING]
+
+    constant_enum :sf_seek_whence, "SF_SEEK_", %w[SET CUR END]
+  end
+end

data/lib/sndfile/native/functions.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module SndFile
+  # attach_function declarations for every function in sndfile.h.
+  module Native
+    # These `attach_function` declarations are in the order of sndfile.h, with
+    # its comments. Parameters that take SFM_*, SF_STR_*, SFC_* or SF_SEEK_*
+    # values use the FFI enums from enums.rb, so they accept symbols such as
+    # :read or :title as well as the integer constants.
+    # sf_open, sf_open_fd and sf_open_virtual return a Handle, which closes
+    # itself when it is garbage collected, and raise a SndFileError instead of
+    # returning NULL.
+    # Calls that read or write the file are attached with `blocking: true` so
+    # they release Ruby's GVL; pass them an FFI::MemoryPointer, never a Ruby
+    # string's memory.
+
+    # Open the specified file for read, write or both. On error, this will
+    # return a NULL pointer. To find the error number, pass a NULL SNDFILE
+    # to sf_strerror ().
+    # All calls to sf_open() should be matched with a call to sf_close().
+    attach_function :sf_open, [:string, :sf_mode, Info.by_ref], Handle, blocking: true
+
+    # Use the existing file descriptor to create a SNDFILE object. If close_desc
+    # is TRUE, the file descriptor will be closed when sf_close() is called. If
+    # it is FALSE, the descriptor will not be closed.
+    # When passed a descriptor like this, the library will assume that the start
+    # of file header is at the current file offset. This allows sound files within
+    # larger container files to be read and/or written.
+    attach_function :sf_open_fd, [:int, :sf_mode, Info.by_ref, :int], Handle, blocking: true
+
+    attach_function :sf_open_virtual, [VirtualIO.by_ref, :sf_mode, Info.by_ref, :pointer], Handle
+
+    # sf_error () returns a error number which can be translated to a text
+    # string using sf_error_number().
+    attach_function :sf_error, [:sndfile], :int
+
+    # sf_strerror () returns to the caller a pointer to the current error message for
+    # the given SNDFILE.
+    attach_function :sf_strerror, [:sndfile], :string
+
+    # sf_error_number () allows the retrieval of the error string for each internal
+    # error number.
+    attach_function :sf_error_number, [:int], :string
+
+    # The following two error functions are deprecated but they will remain in the
+    # library for the foreseeable future. The function sf_strerror() should be used
+    # in their place.
+    attach_function :sf_perror, [:sndfile], :int
+    attach_function :sf_error_str, %i[sndfile pointer size_t], :int
+
+    # Allow the caller to retrieve information from or change aspects of the
+    # library behaviour.
+    attach_function :sf_command, %i[sndfile sf_command pointer int], :int
+
+    # Return TRUE if fields of the SF_INFO struct are a valid combination of values.
+    attach_function :sf_format_check, [Info.by_ref], :int
+
+    # Seek within the waveform data chunk of the SNDFILE.
+    # An offset of zero with whence set to SEEK_SET will position the
+    # read / write pointer to the first data sample.
+    # On success sf_seek returns the current position in (multi-channel)
+    # samples from the start of the file.
+    # On error all of these functions return -1.
+    attach_function :sf_seek, %i[sndfile sf_count_t sf_seek_whence], :sf_count_t, blocking: true
+
+    # Functions for retrieving and setting string data within sound files.
+    # Not all file types support this features; AIFF and WAV do.
+    # On error, sf_set_string() returns non-zero while sf_get_string()
+    # returns NULL.
+    attach_function :sf_set_string, %i[sndfile sf_str string], :int
+    attach_function :sf_get_string, %i[sndfile sf_str], :string
+
+    # Return the library version string.
+    # (sf_version_string is attached in native.rb, before the version check)
+
+    # Return the current byterate at this point in the file. The byte rate in this
+    # case is the number of bytes per second of audio data.
+    # Returns -1 for unknown.
+    attach_function :sf_current_byterate, [:sndfile], :int
+
+    # Functions for reading/writing the waveform data of a sound file.
+    attach_function :sf_read_raw, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_write_raw, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    # Functions for reading and writing the data chunk in terms of frames.
+    # The number of items actually read/written = frames * number of channels.
+    # All of these read/write function return number of frames read/written.
+    attach_function :sf_readf_short, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_writef_short, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_readf_int, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_writef_int, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_readf_float, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_writef_float, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_readf_double, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_writef_double, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    # Functions for reading and writing the data chunk in terms of items.
+    # Otherwise similar to above.
+    # All of these read/write function return number of items read/written.
+    attach_function :sf_read_short, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_write_short, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_read_int, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_write_int, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_read_float, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_write_float, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    attach_function :sf_read_double, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+    attach_function :sf_write_double, %i[sndfile pointer sf_count_t], :sf_count_t, blocking: true
+
+    # Close the SNDFILE and clean up all memory allocations associated with this
+    # file.
+    # Returns 0 on success, or an error number.
+    # (Attached as sf_close_pointer. Native.sf_close also stops a Handle from
+    # being closed a second time when it is garbage collected.)
+    attach_function :sf_close_pointer, :sf_close, [:sndfile], :int, blocking: true
+
+    def self.sf_close(sndfile)
+      sndfile.autorelease = false if sndfile.is_a?(Handle)
+      sf_close_pointer(sndfile)
+    end
+
+    # If the file is opened SFM_WRITE or SFM_RDWR, call fsync() on the file
+    # to force the writing of data to disk. If the file is opened SFM_READ
+    # no action is taken.
+    attach_function :sf_write_sync, [:sndfile], :void, blocking: true
+
+    # The function sf_wchar_open() is Windows Only!
+    # Open a file passing in a Windows Unicode filename. Otherwise, this is
+    # the same as sf_open().
+    attach_function :sf_wchar_open, [:pointer, :sf_mode, Info.by_ref], Handle, blocking: true if FFI::Platform.windows?
+
+    # Getting and setting of chunks from within a sound file.
+    #
+    # These functions allow the getting and setting of chunks within a sound file
+    # (for those formats which allow it).
+
+    # Set the specified chunk info (must be done before any audio data is written
+    # to the file). This will fail for format specific reserved chunks.
+    # The chunk_info->data pointer must be valid until the file is closed.
+    # Returns SF_ERR_NO_ERROR on success or non-zero on failure.
+    attach_function :sf_set_chunk, [:sndfile, ChunkInfo.by_ref], :int
+
+    # Get an iterator for all chunks matching chunk_info.
+    # If chunk_info is NULL, an iterator to all chunks in the SNDFILE* handle
+    #     is returned.
+    # If no matching chunks are found in the sndfile, NULL is returned.
+    # The memory for the iterator belongs to the SNDFILE* handle and is freed when
+    # sf_close() is called.
+    attach_function :sf_get_chunk_iterator, [:sndfile, ChunkInfo.by_ref], :pointer
+
+    # Iterate through chunks by incrementing the iterator.
+    # If iterator points to the last chunk, this will free all resources
+    #      associated with iterator and return NULL.
+    attach_function :sf_next_chunk_iterator, [:pointer], :pointer
+
+    # Get the size of the specified chunk.
+    # If the specified chunk exists, the size will be returned in the
+    #      datalen field of the SF_CHUNK_INFO struct.
+    # The function will return SF_ERR_NO_ERROR on success or non-zero on
+    # failure.
+    attach_function :sf_get_chunk_size, [:pointer, ChunkInfo.by_ref], :int
+
+    # Get the specified chunk data.
+    # If the specified chunk exists, up to chunk_info->datalen bytes of
+    #      the chunk data will be copied into the chunk_info->data buffer
+    #      (allocated by the caller).
+    # The function will return SF_ERR_NO_ERROR on success or non-zero on
+    # failure.
+    attach_function :sf_get_chunk_data, [:pointer, ChunkInfo.by_ref], :int
+  end
+end

data/lib/sndfile/native/handle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SndFile
+  module Native
+    # An owned SNDFILE* handle, as returned by Native.sf_open, sf_open_fd and
+    # sf_open_virtual. It is closed with sf_close when it is garbage
+    # collected, unless it was closed before (see SoundFile#close).
+    class Handle < FFI::AutoPointer
+      def self.release(ptr)
+        Native.sf_close_pointer(ptr)
+      end
+
+      # Called by FFI to wrap the pointer that the sf_open functions return.
+      # They return NULL when the file can't be opened; this raises the
+      # matching SndFileError with libsndfile's message instead.
+      def self.from_native(ptr, ctx)
+        Error.raise_open_error if ptr.null?
+
+        super
+      end
+    end
+  end
+end