ffi-sndfile 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b113eec6ca95e787da990c8492074e91536d69f0d88c0f14ce54b36b48191080
+  data.tar.gz: dd944287fbcb0def4f3194ec136b3c4e9c007819e7e3970994bf444c7fc0b8b2
+SHA512:
+  metadata.gz: 0fd357282d36ca986a2301099b2f1966c337c042f265e10571fc4d6bf47e4830818bbf6fc363bd45d27a65329368ab6f0edf6e538ae2f9fdb80b539bdc582025
+  data.tar.gz: cf60f0f27122780304cbd27e59d941ccacc7b0917459590622af232762ec7de852036cb922989bb9c1f98b5724169880610120c70f9d2ac74f04bd7fd8233151

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Roel van Dijk
+
+MIT License
+
+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,230 @@
+# ffi-sndfile
+
+Ruby FFI bindings for [libsndfile](https://libsndfile.github.io/libsndfile/), the library for reading and writing sound files: WAV, AIFF, FLAC, Ogg/Vorbis, Opus, MP3, CAF and many more.
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed.
+
+## Installation
+
+### Requirements
+
+- Ruby 3.2 or newer
+- libsndfile 1.0.28 or newer, including its development files:
+  - Ubuntu / Debian: `sudo apt-get install libsndfile1-dev`
+  - Fedora: `sudo dnf install libsndfile-devel`
+  - Arch Linux: `sudo pacman -S libsndfile`
+  - macOS (Homebrew): `brew install libsndfile`
+
+Check your version with `pkg-config --modversion sndfile`. With libsndfile older than 1.0.28, `require "sndfile"` raises a `LoadError` that names the version it found. MP3 support (the `:mpeg` format and `bitrate_mode`) needs libsndfile 1.1.0 or newer, built with MPEG support.
+
+### Gem Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ffi-sndfile"
+```
+
+And run:
+
+```bash
+bundle install
+```
+
+Then load it with `require "sndfile"` (or `require "ffi-sndfile"`; Bundler's auto-require uses that one). The library lives in the `SndFile` module.
+
+## Usage
+
+### Reading a Sound File
+
+`SndFile.open` (the same as `SndFile::SoundFile.open`) opens a file. With a block, it closes the file afterwards (also when the block raises) and returns the block's value:
+
+```ruby
+require "sndfile"
+
+SndFile.open("song.flac") do |file|
+  file.samplerate  # => 44100
+  file.channels    # => 2
+  file.frames      # => 9_261_000
+  file.duration    # => 210.0 (seconds)
+  file.format      # => #<SndFile::Format flac/pcm_16>
+
+  # Read in buffers of 4096 frames
+  file.each_buffer(4096) do |samples|
+    # samples is a flat Array, channels interleaved: [left, right, left, right, ...]
+  end
+end
+```
+
+Samples are floats from -1.0 to 1.0 by default. Pass `type:` to get another sample type; libsndfile converts between it and the file's encoding:
+
+| `type:` | Values |
+|---|---|
+| `:float` (default) | Floats, -1.0 to 1.0 |
+| `:double` | Floats, -1.0 to 1.0 |
+| `:short` | 16 bit integers, -32768 to 32767 |
+| `:int` | 32 bit integers |
+
+```ruby
+SndFile.open("take.wav") do |file|
+  file.read(1024)                 # up to 1024 frames as floats ([] at the end of the file)
+  file.read(1024, type: :short)   # the next 1024 frames as 16 bit integers
+  file.seek(0)                    # back to the first frame; also seek(n, :cur) and seek(-n, :end)
+  file.read                       # everything up to the end of the file
+end
+```
+
+Without a block, `open` returns the `SndFile::SoundFile`; call `close` when you're done. The file is also closed when it is garbage collected, but don't rely on that when writing: closing is what writes the final header.
+
+### Writing a Sound File
+
+Writing needs a sample rate, a channel count and a format. The format can come from the file name's extension:
+
+```ruby
+samples = Array.new(44_100) { |i| 0.5 * Math.sin(2 * Math::PI * 440 * i / 44_100) } # one second of A4
+
+SndFile.open("a4.wav", :write, samplerate: 44_100, channels: 1) do |file|
+  file.write(samples)  # => 44100 (frames written)
+end
+```
+
+Or give it with `format:` (a major format such as `:wav` or `:flac`) and optionally `subtype:` (the encoding) and `endian:`:
+
+```ruby
+SndFile.open("a4.aiff", :write, format: :aiff, subtype: :pcm_24, samplerate: 48_000, channels: 2) do |file|
+  file << [0.1, -0.1] << [0.2, -0.2]  # two stereo frames
+end
+```
+
+Without `subtype:`, common formats use a sensible default: `:pcm_16` for WAV, AIFF, FLAC and the like, `:vorbis` for Ogg and `:mpeg_layer_iii` for MP3. An unknown name or a combination libsndfile can't write (such as `format: :wav, subtype: :vorbis`) raises `ArgumentError`. Open a file with `:rdwr` to read and write it, for example to append.
+
+### Ogg/Vorbis with Vorbis Comments
+
+String metadata (title, artist, ...) is written in the format's own way: as Vorbis comments in Ogg and FLAC files, as an INFO chunk in WAV files, and so on. Most formats need the strings, and encoder settings such as the quality, before the first audio is written, so pass them to `open` or set them first thing:
+
+```ruby
+SndFile.open("song.ogg", :write, samplerate: 44_100, channels: 2,
+                                 strings: { title: "Heart of Gold", artist: "Neil Young" }) do |file|
+  file.strings.album = "Harvest"
+  file.strings[:date] = "1972"
+  file.vbr_quality = 0.6  # 0.0 (smallest file) to 1.0 (best quality)
+
+  file.write(samples)
+end
+
+SndFile.open("song.ogg") do |file|
+  file.format        # => #<SndFile::Format ogg/vorbis>
+  file.strings.title # => "Heart of Gold"
+  file.strings.to_h  # => {title: "Heart of Gold", artist: "Neil Young", date: "1972", album: "Harvest"}
+end
+```
+
+The strings are `title`, `copyright`, `software`, `artist`, `comment`, `date`, `album`, `license`, `tracknumber` (also `track_number`) and `genre`. They are read back as UTF-8. Setting a string after audio was written, or one the format doesn't support, raises `SndFile::SndFileError`.
+
+Use `format: :ogg, subtype: :opus` (or a `.opus` file name) for Ogg/Opus.
+
+### Files in Memory and Other IO Objects
+
+Instead of a path, you can pass an IO-like object, such as a `StringIO`, a `File` or a socket. libsndfile reads and writes it through `#read`, `#write`, `#seek` and `#pos`. A format is needed for writing, since there is no file name to take it from:
+
+```ruby
+require "stringio"
+
+io = StringIO.new(+"".b)
+SndFile.open(io, :write, format: :ogg, samplerate: 44_100, channels: 1) { |file| file.write(samples) }
+io.string  # => "OggS\x00\x02..."
+
+io.rewind
+SndFile.open(io) { |file| file.frames }  # => 44100
+```
+
+Exceptions raised by the IO object are raised again by the `SndFile` call that caused them.
+
+### Other Settings
+
+```ruby
+file.compression_level = 0.8   # FLAC, Ogg, MP3: 0.0 (fastest) to 1.0 (smallest)
+file.bitrate_mode = :variable  # MP3: :constant, :average or :variable
+file.normalize_float = false   # read and write floats unscaled (default: -1.0..1.0)
+file.signal_max                # the largest absolute sample value
+file.update_header_now         # make a file being written readable already
+file.truncate(1000)            # cut the file to 1000 frames
+file.byterate                  # current bytes per second, or nil
+file.log_info                  # libsndfile's log of opening the file
+```
+
+Every other libsndfile command is available through `file.command`, which takes an `SFC_*` constant or its name as a symbol and passes the data on, for example a `SndFile::Native::BroadcastInfo` struct for the Broadcast WAV `bext` chunk:
+
+```ruby
+bext = SndFile::Native::BroadcastInfo.new
+bext.set_string(:description, "Field recording")
+
+SndFile.open("field.wav", :write, samplerate: 48_000, channels: 2) do |file|
+  file.command(:set_broadcast_info, bext)  # => 1 (SF_TRUE); before any audio is written
+  file.write(samples)
+end
+```
+
+### Formats
+
+```ruby
+SndFile::Format.new(:ogg, :vorbis).to_i                 # => 2097248 (SF_FORMAT_OGG | SF_FORMAT_VORBIS)
+SndFile::Format.new(0x170002)                           # => #<SndFile::Format flac/pcm_16>
+SndFile::Format.new(:flac).valid?(samplerate: 44_100, channels: 2)  # => true
+
+SndFile.major_formats.map(&:name)   # => ["AIFF (Apple/SGI)", "AU (Sun/NeXT)", ...]
+SndFile.subtypes.map(&:name)        # => ["Signed 8 bit PCM", "Signed 16 bit PCM", ...]
+SndFile.simple_formats              # common combinations, each with its format, name and extension
+SndFile::Formats.describe(:vorbis)  # => #<data SndFile::FormatDescription format=..., name="Vorbis", extension=nil>
+```
+
+The lists come from the loaded libsndfile, so they show what this installation supports.
+
+### Errors
+
+Every libsndfile error is raised as a subclass of `SndFile::SndFileError`, so `rescue SndFile::SndFileError` catches them all. The message is libsndfile's own error text, and `#code` is libsndfile's error number.
+
+| Class | libsndfile error |
+|---|---|
+| `SndFile::UnrecognisedFormatError` | `SF_ERR_UNRECOGNISED_FORMAT`: not a sound file, or a format libsndfile can't read |
+| `SndFile::SystemError` | `SF_ERR_SYSTEM`: an operating system error, such as a missing file |
+| `SndFile::MalformedFileError` | `SF_ERR_MALFORMED_FILE`: the file is damaged |
+| `SndFile::UnsupportedEncodingError` | `SF_ERR_UNSUPPORTED_ENCODING`: an encoding libsndfile can't decode |
+| `SndFile::SndFileError` | any of libsndfile's other, internal errors |
+| `SndFile::ClosedFileError` | the `SoundFile` was used after it was closed |
+
+### libsndfile Version
+
+`SndFile.version` describes the loaded libsndfile library:
+
+```ruby
+SndFile.version.to_s       # => "libsndfile-1.2.2"
+SndFile.version.number     # => "1.2.2"
+SndFile.version >= "1.1.0" # => true
+```
+
+### Threads
+
+libsndfile calls that read or write a file (`open`, `read`, `write`, `seek`, `close`, ...) let other Ruby threads keep running while they wait on the disk.
+
+### Low-level libsndfile Functions
+
+Every function in `sndfile.h` is attached to `SndFile::Native`, an `FFI::Library`, for anything `SndFile::SoundFile` doesn't cover. Every struct is there too (`Native::Info` for `SF_INFO`, `Native::Instrument`, `Native::CartInfo`, `Native::ChunkInfo`, ...), and every constant is in `SndFile` (`SndFile::SF_FORMAT_OGG`, `SndFile::SFC_GET_LOG_INFO`, ...). Parameters for modes, string types, commands and seek origins also take symbols:
+
+```ruby
+info = SndFile::Native::Info.new
+sndfile = SndFile::Native.sf_open("take.wav", :read, info)
+info[:frames]                                   # => 1000
+SndFile::Native.sf_get_string(sndfile, :title)  # => "Old Man"
+SndFile::Native.sf_close(sndfile)               # => 0
+```
+
+`sf_open`, `sf_open_fd` and `sf_open_virtual` return a handle that closes itself when it is garbage collected, unless you close it with `Native.sf_close` first; they raise a `SndFile::SndFileError` instead of returning `NULL`. Otherwise these functions return libsndfile's error codes instead of raising, and their API follows libsndfile rather than this gem.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the specs and which Ruby versions changes need to support.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/ffi-sndfile.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `require "ffi-sndfile"` and
+# `Bundler.require` load the library. Same as `require "sndfile"`.
+require "sndfile"

data/lib/sndfile/commands.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SndFile
+  # Methods for SoundFile that wrap libsndfile's sf_command. #command gives
+  # access to every SFC_* command; the other methods cover common ones.
+  #
+  # Encoder settings (#vbr_quality=, #compression_level=, #bitrate_mode=)
+  # must be set before the first audio data is written.
+  module Commands
+    # Runs an sf_command and returns its integer result. +command+ is an
+    # SFC_* constant or its symbol (e.g. :get_log_info); +data+ is a pointer
+    # (or FFI::Struct) of +size+ bytes, as the command expects.
+    def command(command, data = nil, size = data.respond_to?(:size) ? data.size : 0)
+      Native.sf_command(handle, command, data, size)
+    end
+
+    # libsndfile's log of what it did while opening the file.
+    def log_info
+      buffer = FFI::MemoryPointer.new(:char, 4096)
+      command(SFC_GET_LOG_INFO, buffer, buffer.size)
+      buffer.read_string
+    end
+
+    # Sets the encoding quality for variable bit rate formats such as Ogg
+    # Vorbis, Opus, FLAC and MP3: 0.0 (lowest) to 1.0 (highest).
+    def vbr_quality=(quality)
+      set_double(SFC_SET_VBR_ENCODING_QUALITY, quality, "VBR encoding quality")
+    end
+
+    # Sets the compression level for formats such as FLAC, Ogg and MP3:
+    # 0.0 (least compression) to 1.0 (most compression).
+    def compression_level=(level)
+      set_double(SFC_SET_COMPRESSION_LEVEL, level, "compression level")
+    end
+
+    # The bitrate mode (:constant, :average or :variable), for MPEG files.
+    # Returns nil when the format has none.
+    def bitrate_mode
+      mode = command(SFC_GET_BITRATE_MODE)
+      Native.enum_type(:sf_bitrate_mode)[mode] unless mode.negative?
+    end
+
+    def bitrate_mode=(mode)
+      value = FFI::MemoryPointer.new(:int)
+      value.write_int(Native.enum_type(:sf_bitrate_mode).to_native(mode, nil))
+      check_command(SFC_SET_BITRATE_MODE, value, value.size, "bitrate mode #{mode.inspect}")
+    end
+
+    # Whether floating point data is normalized to -1.0..1.0 when reading
+    # and writing (libsndfile's default is true).
+    def normalize_float?
+      command(SFC_GET_NORM_FLOAT) == SF_TRUE
+    end
+
+    def normalize_float=(normalize)
+      command(SFC_SET_NORM_FLOAT, nil, normalize ? SF_TRUE : SF_FALSE)
+    end
+
+    # Writes the file header now, so the file is valid while it is being
+    # written.
+    def update_header_now
+      command(SFC_UPDATE_HEADER_NOW)
+      self
+    end
+
+    # Truncates the file to +frames+ frames.
+    def truncate(frames)
+      value = FFI::MemoryPointer.new(:int64)
+      value.write_int64(frames)
+      return self if command(SFC_FILE_TRUNCATE, value).zero?
+
+      raise SndFileError, "Cannot truncate #{inspect} to #{frames} frames"
+    end
+
+    # The largest absolute sample value in the file (SFC_CALC_SIGNAL_MAX),
+    # or with normalized: true, as a fraction of the format's full scale.
+    def signal_max(normalized: false)
+      value = FFI::MemoryPointer.new(:double)
+      command(normalized ? SFC_CALC_NORM_SIGNAL_MAX : SFC_CALC_SIGNAL_MAX, value)
+      Error.check_sndfile(handle)
+      value.read_double
+    end
+
+    private
+
+    def set_double(command_id, number, description)
+      value = FFI::MemoryPointer.new(:double)
+      value.write_double(Float(number))
+      check_command(command_id, value, value.size, "#{description} #{number}")
+    end
+
+    # Runs a SET command that returns SF_TRUE on success.
+    def check_command(command_id, data, size, description)
+      return if command(command_id, data, size) == SF_TRUE
+
+      raise SndFileError, "Cannot set #{description} for #{format} files"
+    end
+  end
+end

data/lib/sndfile/constants.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+# The constants from sndfile.h, in the order of that header, with its comments.
+module SndFile
+  # The following file types can be read and written. A file type would
+  # consist of a major type (ie SF_FORMAT_WAV) bitwise ORed with a minor type
+  # (ie SF_FORMAT_PCM). SF_FORMAT_TYPEMASK and SF_FORMAT_SUBMASK can be used
+  # to separate the major and minor file types.
+
+  # Major formats.
+  SF_FORMAT_WAV               = 0x010000
+  SF_FORMAT_AIFF              = 0x020000
+  SF_FORMAT_AU                = 0x030000
+  SF_FORMAT_RAW               = 0x040000
+  SF_FORMAT_PAF               = 0x050000
+  SF_FORMAT_SVX               = 0x060000
+  SF_FORMAT_NIST              = 0x070000
+  SF_FORMAT_VOC               = 0x080000
+  SF_FORMAT_IRCAM             = 0x0A0000
+  SF_FORMAT_W64               = 0x0B0000
+  SF_FORMAT_MAT4              = 0x0C0000
+  SF_FORMAT_MAT5              = 0x0D0000
+  SF_FORMAT_PVF               = 0x0E0000
+  SF_FORMAT_XI                = 0x0F0000
+  SF_FORMAT_HTK               = 0x100000
+  SF_FORMAT_SDS               = 0x110000
+  SF_FORMAT_AVR               = 0x120000
+  SF_FORMAT_WAVEX             = 0x130000
+  SF_FORMAT_SD2               = 0x160000
+  SF_FORMAT_FLAC              = 0x170000
+  SF_FORMAT_CAF               = 0x180000
+  SF_FORMAT_WVE               = 0x190000
+  SF_FORMAT_OGG               = 0x200000
+  SF_FORMAT_MPC2K             = 0x210000
+  SF_FORMAT_RF64              = 0x220000
+  SF_FORMAT_MPEG              = 0x230000
+
+  # Subtypes from here on.
+  SF_FORMAT_PCM_S8            = 0x0001
+  SF_FORMAT_PCM_16            = 0x0002
+  SF_FORMAT_PCM_24            = 0x0003
+  SF_FORMAT_PCM_32            = 0x0004
+  SF_FORMAT_PCM_U8            = 0x0005
+  SF_FORMAT_FLOAT             = 0x0006
+  SF_FORMAT_DOUBLE            = 0x0007
+  SF_FORMAT_ULAW              = 0x0010
+  SF_FORMAT_ALAW              = 0x0011
+  SF_FORMAT_IMA_ADPCM         = 0x0012
+  SF_FORMAT_MS_ADPCM          = 0x0013
+  SF_FORMAT_GSM610            = 0x0020
+  SF_FORMAT_VOX_ADPCM         = 0x0021
+  SF_FORMAT_NMS_ADPCM_16      = 0x0022
+  SF_FORMAT_NMS_ADPCM_24      = 0x0023
+  SF_FORMAT_NMS_ADPCM_32      = 0x0024
+  SF_FORMAT_G721_32           = 0x0030
+  SF_FORMAT_G723_24           = 0x0031
+  SF_FORMAT_G723_40           = 0x0032
+  SF_FORMAT_DWVW_12           = 0x0040
+  SF_FORMAT_DWVW_16           = 0x0041
+  SF_FORMAT_DWVW_24           = 0x0042
+  SF_FORMAT_DWVW_N            = 0x0043
+  SF_FORMAT_DPCM_8            = 0x0050
+  SF_FORMAT_DPCM_16           = 0x0051
+  SF_FORMAT_VORBIS            = 0x0060
+  SF_FORMAT_OPUS              = 0x0064
+  SF_FORMAT_ALAC_16           = 0x0070
+  SF_FORMAT_ALAC_20           = 0x0071
+  SF_FORMAT_ALAC_24           = 0x0072
+  SF_FORMAT_ALAC_32           = 0x0073
+  SF_FORMAT_MPEG_LAYER_I      = 0x0080
+  SF_FORMAT_MPEG_LAYER_II     = 0x0081
+  SF_FORMAT_MPEG_LAYER_III    = 0x0082
+
+  # Endian-ness options.
+  SF_ENDIAN_FILE              = 0x00000000
+  SF_ENDIAN_LITTLE            = 0x10000000
+  SF_ENDIAN_BIG               = 0x20000000
+  SF_ENDIAN_CPU               = 0x30000000
+
+  SF_FORMAT_SUBMASK           = 0x0000FFFF
+  SF_FORMAT_TYPEMASK          = 0x0FFF0000
+  SF_FORMAT_ENDMASK           = 0x30000000
+
+  # The following are the valid command numbers for the sf_command()
+  # interface. The use of these commands is documented in the file
+  # command.html in the doc directory of the source code distribution.
+  SFC_GET_LIB_VERSION             = 0x1000
+  SFC_GET_LOG_INFO                = 0x1001
+  SFC_GET_CURRENT_SF_INFO         = 0x1002
+  SFC_GET_NORM_DOUBLE             = 0x1010
+  SFC_GET_NORM_FLOAT              = 0x1011
+  SFC_SET_NORM_DOUBLE             = 0x1012
+  SFC_SET_NORM_FLOAT              = 0x1013
+  SFC_SET_SCALE_FLOAT_INT_READ    = 0x1014
+  SFC_SET_SCALE_INT_FLOAT_WRITE   = 0x1015
+  SFC_GET_SIMPLE_FORMAT_COUNT     = 0x1020
+  SFC_GET_SIMPLE_FORMAT           = 0x1021
+  SFC_GET_FORMAT_INFO             = 0x1028
+  SFC_GET_FORMAT_MAJOR_COUNT      = 0x1030
+  SFC_GET_FORMAT_MAJOR            = 0x1031
+  SFC_GET_FORMAT_SUBTYPE_COUNT    = 0x1032
+  SFC_GET_FORMAT_SUBTYPE          = 0x1033
+  SFC_CALC_SIGNAL_MAX             = 0x1040
+  SFC_CALC_NORM_SIGNAL_MAX        = 0x1041
+  SFC_CALC_MAX_ALL_CHANNELS       = 0x1042
+  SFC_CALC_NORM_MAX_ALL_CHANNELS  = 0x1043
+  SFC_GET_SIGNAL_MAX              = 0x1044
+  SFC_GET_MAX_ALL_CHANNELS        = 0x1045
+  SFC_SET_ADD_PEAK_CHUNK          = 0x1050
+  SFC_UPDATE_HEADER_NOW           = 0x1060
+  SFC_SET_UPDATE_HEADER_AUTO      = 0x1061
+  SFC_FILE_TRUNCATE               = 0x1080
+  SFC_SET_RAW_START_OFFSET        = 0x1090
+  SFC_SET_DITHER_ON_WRITE         = 0x10A0
+  SFC_SET_DITHER_ON_READ          = 0x10A1
+  SFC_GET_DITHER_INFO_COUNT       = 0x10A2
+  SFC_GET_DITHER_INFO             = 0x10A3
+  SFC_GET_EMBED_FILE_INFO         = 0x10B0
+  SFC_SET_CLIPPING                = 0x10C0
+  SFC_GET_CLIPPING                = 0x10C1
+  SFC_GET_CUE_COUNT               = 0x10CD
+  SFC_GET_CUE                     = 0x10CE
+  SFC_SET_CUE                     = 0x10CF
+  SFC_GET_INSTRUMENT              = 0x10D0
+  SFC_SET_INSTRUMENT              = 0x10D1
+  SFC_GET_LOOP_INFO               = 0x10E0
+  SFC_GET_BROADCAST_INFO          = 0x10F0
+  SFC_SET_BROADCAST_INFO          = 0x10F1
+  SFC_GET_CHANNEL_MAP_INFO        = 0x1100
+  SFC_SET_CHANNEL_MAP_INFO        = 0x1101
+  SFC_RAW_DATA_NEEDS_ENDSWAP      = 0x1110
+  # Support for Wavex Ambisonics Format
+  SFC_WAVEX_SET_AMBISONIC         = 0x1200
+  SFC_WAVEX_GET_AMBISONIC         = 0x1201
+  # RF64 files can be set so that on-close, writable files that have less
+  # than 4GB of data in them are converted to RIFF/WAV, as per EBU
+  # recommendations.
+  SFC_RF64_AUTO_DOWNGRADE         = 0x1210
+
+  SFC_SET_VBR_ENCODING_QUALITY    = 0x1300
+  SFC_SET_COMPRESSION_LEVEL       = 0x1301
+
+  # Ogg format commands
+  SFC_SET_OGG_PAGE_LATENCY_MS     = 0x1302
+  SFC_SET_OGG_PAGE_LATENCY        = 0x1303
+  SFC_GET_OGG_STREAM_SERIALNO     = 0x1306
+
+  SFC_GET_BITRATE_MODE            = 0x1304
+  SFC_SET_BITRATE_MODE            = 0x1305
+
+  # Cart Chunk support
+  SFC_SET_CART_INFO               = 0x1400
+  SFC_GET_CART_INFO               = 0x1401
+
+  # Opus files original samplerate metadata
+  SFC_SET_ORIGINAL_SAMPLERATE     = 0x1500
+  SFC_GET_ORIGINAL_SAMPLERATE     = 0x1501
+
+  # Following commands for testing only.
+  SFC_TEST_IEEE_FLOAT_REPLACE     = 0x6001
+
+  # These SFC_SET_ADD_* values are deprecated and will disappear at some
+  # time in the future. They currently do nothing and will continue to do
+  # nothing.
+  SFC_SET_ADD_HEADER_PAD_CHUNK    = 0x1051
+  SFC_SET_ADD_DITHER_ON_WRITE     = 0x1070
+  SFC_SET_ADD_DITHER_ON_READ      = 0x1071
+
+  # String types that can be set and read from files. Not all file types
+  # support this and even the file types which support one, may not support
+  # all string types.
+  SF_STR_TITLE                = 0x01
+  SF_STR_COPYRIGHT            = 0x02
+  SF_STR_SOFTWARE             = 0x03
+  SF_STR_ARTIST               = 0x04
+  SF_STR_COMMENT              = 0x05
+  SF_STR_DATE                 = 0x06
+  SF_STR_ALBUM                = 0x07
+  SF_STR_LICENSE              = 0x08
+  SF_STR_TRACKNUMBER          = 0x09
+  SF_STR_GENRE                = 0x10
+
+  # Use the following as the start and end index when doing metadata
+  # transcoding.
+  SF_STR_FIRST                = SF_STR_TITLE
+  SF_STR_LAST                 = SF_STR_GENRE
+
+  # True and false
+  SF_FALSE                    = 0
+  SF_TRUE                     = 1
+
+  # Modes for opening files.
+  SFM_READ                    = 0x10
+  SFM_WRITE                   = 0x20
+  SFM_RDWR                    = 0x30
+
+  SF_AMBISONIC_NONE           = 0x40
+  SF_AMBISONIC_B_FORMAT       = 0x41
+
+  # Public error values. These are guaranteed to remain unchanged for the
+  # duration of the library major version number.
+  SF_ERR_NO_ERROR             = 0
+  SF_ERR_UNRECOGNISED_FORMAT  = 1
+  SF_ERR_SYSTEM               = 2
+  SF_ERR_MALFORMED_FILE       = 3
+  SF_ERR_UNSUPPORTED_ENCODING = 4
+
+  # Channel map values (used with SFC_SET/GET_CHANNEL_MAP).
+  SF_CHANNEL_MAP_INVALID                = 0
+  SF_CHANNEL_MAP_MONO                   = 1
+  SF_CHANNEL_MAP_LEFT                   = 2
+  SF_CHANNEL_MAP_RIGHT                  = 3
+  SF_CHANNEL_MAP_CENTER                 = 4
+  SF_CHANNEL_MAP_FRONT_LEFT             = 5
+  SF_CHANNEL_MAP_FRONT_RIGHT            = 6
+  SF_CHANNEL_MAP_FRONT_CENTER           = 7
+  SF_CHANNEL_MAP_REAR_CENTER            = 8
+  SF_CHANNEL_MAP_REAR_LEFT              = 9
+  SF_CHANNEL_MAP_REAR_RIGHT             = 10
+  SF_CHANNEL_MAP_LFE                    = 11
+  SF_CHANNEL_MAP_FRONT_LEFT_OF_CENTER   = 12
+  SF_CHANNEL_MAP_FRONT_RIGHT_OF_CENTER  = 13
+  SF_CHANNEL_MAP_SIDE_LEFT              = 14
+  SF_CHANNEL_MAP_SIDE_RIGHT             = 15
+  SF_CHANNEL_MAP_TOP_CENTER             = 16
+  SF_CHANNEL_MAP_TOP_FRONT_LEFT         = 17
+  SF_CHANNEL_MAP_TOP_FRONT_RIGHT        = 18
+  SF_CHANNEL_MAP_TOP_FRONT_CENTER       = 19
+  SF_CHANNEL_MAP_TOP_REAR_LEFT          = 20
+  SF_CHANNEL_MAP_TOP_REAR_RIGHT         = 21
+  SF_CHANNEL_MAP_TOP_REAR_CENTER        = 22
+  SF_CHANNEL_MAP_AMBISONIC_B_W          = 23
+  SF_CHANNEL_MAP_AMBISONIC_B_X          = 24
+  SF_CHANNEL_MAP_AMBISONIC_B_Y          = 25
+  SF_CHANNEL_MAP_AMBISONIC_B_Z          = 26
+  SF_CHANNEL_MAP_MAX                    = 27
+
+  # Bitrate mode values (for use with SFC_GET/SET_BITRATE_MODE)
+  SF_BITRATE_MODE_CONSTANT    = 0
+  SF_BITRATE_MODE_AVERAGE     = 1
+  SF_BITRATE_MODE_VARIABLE    = 2
+
+  # Enums and typedefs for adding dither on read and write.
+  # Reserved for future implementation.
+  SFD_DEFAULT_LEVEL           = 0
+  SFD_CUSTOM_LEVEL            = 0x40000000
+  SFD_NO_DITHER               = 500
+  SFD_WHITE                   = 501
+  SFD_TRIANGULAR_PDF          = 502
+
+  # The loop mode field in SF_INSTRUMENT will be one of the following.
+  SF_LOOP_NONE                = 800
+  SF_LOOP_FORWARD             = 801
+  SF_LOOP_BACKWARD            = 802
+  SF_LOOP_ALTERNATING         = 803
+
+  # sf_seek () uses the same values for whence (SEEK_SET, SEEK_CUR and
+  # SEEK_END) as stdio.h function fseek ().
+  SF_SEEK_SET                 = 0
+  SF_SEEK_CUR                 = 1
+  SF_SEEK_END                 = 2
+
+  SF_COUNT_MAX                = (2**63) - 1
+end