rockbox_ffi 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f33beb6b8aa564e0241a6e4cd568eade3679921426a20aa0e15e29fe1ea9c5a
+  data.tar.gz: 45b34e21a05614eeb43df032e8cafbf4cc878d78fb3478f350cf1184610b05f8
+SHA512:
+  metadata.gz: da520edf71f48c5fd922f11a4dc005fb91df3ec21557de38b8d96032ba4b8d1105f189f22772d07379a56436b20b40b884e4c505e9b9a318a4ec4ec2df37e616
+  data.tar.gz: 2d51eb2bc2be6afa6af83c7e14d9f4eb28f52267be782031548b0f93bb4d4f1335437d39648da84d096aab1d735af0c8c4e4d56bdbbfc15fe7c6b830f8b2be6c

data/README.md

@@ -0,0 +1,115 @@
+# rockbox_ffi (Ruby)
+
+[![Gem](https://img.shields.io/gem/v/rockbox_ffi?logo=rubygems&logoColor=white)](https://rubygems.org/gems/rockbox_ffi)
+![Ruby](https://img.shields.io/badge/Ruby-2.6%2B-CC342D?logo=ruby&logoColor=white)
+![FFI](https://img.shields.io/badge/FFI-fiddle-CC342D)
+![License](https://img.shields.io/badge/license-GPL--2.0--or--later-blue)
+
+Ruby bindings for the Rockbox **DSP**, **metadata**, and **playback** engine,
+via [`fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) (Ruby stdlib)
+over the prebuilt `librockbox_ffi` shared library. No native extension is
+compiled — the gem `dlopen`s the shared library at load time.
+
+## Setup
+
+Build the shared library once (from the repo root):
+
+```sh
+cargo build --release -p rockbox-ffi
+```
+
+Then, from this directory:
+
+```sh
+cd bindings/ruby
+bundle install                 # installs rake + minitest (dev only)
+ruby -Ilib examples/smoke.rb   # end-to-end check
+```
+
+The library is located automatically by walking up to
+`target/release/librockbox_ffi.{dylib,so}`. Override with the
+`ROCKBOX_FFI_LIB` environment variable.
+
+## Usage
+
+```ruby
+require "rockbox_ffi"
+
+# --- metadata ---------------------------------------------------------
+meta = RockboxFFI::Metadata.read("song.flac")
+puts "#{meta[:artist]} — #{meta[:title]} (#{meta[:duration_ms]} ms)"
+RockboxFFI::Metadata.probe("track.opus")   # => "Opus"
+
+# --- DSP (interleaved stereo int16) -----------------------------------
+RockboxFFI::Dsp.open(44_100) do |dsp|
+  dsp.eq_enable(true)
+  dsp.set_eq_band(0, 60, 0.7, 3.0)
+  dsp.set_replaygain(RockboxFFI::DspReplayGainMode::TRACK, true, 0.0)
+  dsp.set_replaygain_gains(track_gain_db: -6.02)  # halves amplitude
+  processed = dsp.process(samples)                # Array<Integer>
+end
+
+# --- playback (needs an output device) --------------------------------
+RockboxFFI::Player.open(volume: 0.8) do |player|
+  player.set_replaygain(RockboxFFI::ReplayGainMode::TRACK, 0.0, true)
+  player.set_crossfade(RockboxFFI::CrossfadeMode::ALWAYS)
+  player.set_queue(["a.flac", "b.mp3", "c.opus"])
+  player.play
+  player.status   # => {state: "playing", index: 0, ...}
+end
+```
+
+`Dsp` and `Player` own native resources. Use the block form (`.open`) to close
+them automatically, or call `#close` yourself; a GC finalizer frees the handle
+as a backstop.
+
+## API
+
+| Namespace                | Contents                                                          |
+| ------------------------ | ----------------------------------------------------------------- |
+| `RockboxFFI::Metadata`   | `read(path) => Hash`, `probe(filename) => String \| nil`          |
+| `RockboxFFI::Dsp`        | EQ / tone / surround / compressor / ReplayGain, `process(samples)` |
+| `RockboxFFI::Player`     | queue + transport + crossfade + ReplayGain, `status => Hash`      |
+| `RockboxFFI::*Mode`      | `DspReplayGainMode`, `ReplayGainMode`, `CrossfadeMode`, `MixMode` |
+
+Rich values (metadata, player status) cross the FFI boundary as JSON and come
+back as Hashes with **symbol keys**. Sample buffers are plain `Array<Integer>`
+of interleaved-stereo signed 16-bit samples.
+
+### Two ReplayGain encodings
+
+The DSP and player use *different* mode integers (a quirk of the C ABI):
+
+- `Dsp#set_replaygain` → `DspReplayGainMode` (`TRACK=0, ALBUM=1, SHUFFLE=2, OFF=3`)
+- `Player#set_replaygain` → `ReplayGainMode` (`OFF=0, TRACK=1, ALBUM=2`)
+
+Use the named constants and you won't have to remember which is which.
+
+## Examples
+
+```sh
+ruby -Ilib examples/smoke.rb          # metadata + DSP + player checks
+ruby -Ilib examples/play.rb [path]    # play a file through the output device
+```
+
+## Interactive console
+
+```sh
+./bin/console        # or: rake console
+```
+
+Drops into IRB with `RockboxFFI` loaded and `FIXTURE` pointing at a sample
+track:
+
+```ruby
+RockboxFFI::Metadata.read(FIXTURE)[:title]        # => "Speak"
+p = RockboxFFI::Player.new(volume: 0.6)
+p.set_queue([FIXTURE]); p.play
+p.status[:state]                                  # => "playing"
+```
+
+## Test
+
+```sh
+bundle exec rake test
+```

data/examples/play.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Play an audio file through the real output device.
+#
+# Run: ruby -Ilib examples/play.rb [path-to-audio]
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "rockbox_ffi"
+
+REPO = File.expand_path("../../..", __dir__)
+FIXTURE = File.join(REPO, "crates", "rocksky", "fixtures", "08 - Internet Money - Speak(Explicit).m4a")
+
+file = ARGV[0] || FIXTURE
+
+player = RockboxFFI::Player.new(volume: 0.8)
+player.set_queue([file])
+player.play
+puts "▶ playing #{file}"
+
+# Reinstall a SIGINT handler AFTER the player boots: the native audio engine
+# installs its own signal handler while starting the output device, which
+# otherwise swallows Ctrl-C. We exit! straight away instead of calling
+# player.stop/close — those are blocking native calls that can deadlock
+# against the engine thread. The OS reclaims the output device on exit.
+trap("INT") do
+  puts "\nstopped"
+  exit!(130)
+end
+
+# Poll status until playback finishes (state returns to "stopped").
+loop do
+  st = player.status
+  pos = st[:position_ms] / 1000.0
+  dur = st[:duration_ms] / 1000.0
+  printf("\r[%s] %.1fs / %.1fs   ", st[:state], pos, dur)
+  $stdout.flush
+
+  if st[:state] == "stopped" && st[:position_ms].positive?
+    puts "\n✔ done"
+    break
+  end
+  sleep 0.5
+end
+
+exit!(0)

data/examples/smoke.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# End-to-end smoke test for the Ruby bindings.
+#
+# Run: ruby -Ilib examples/smoke.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "rockbox_ffi"
+
+REPO = File.expand_path("../../..", __dir__)
+FIXTURE = File.join(REPO, "crates", "rocksky", "fixtures", "08 - Internet Money - Speak(Explicit).m4a")
+
+puts "ABI version: #{RockboxFFI.abi_version}"
+
+# -- metadata -----------------------------------------------------------
+meta = RockboxFFI::Metadata.read(FIXTURE)
+puts "codec=#{meta[:codec].inspect} title=#{meta[:title].inspect} " \
+     "artist=#{meta[:artist].inspect} duration_ms=#{meta[:duration_ms]} " \
+     "sample_rate=#{meta[:sample_rate]}"
+raise "codec label should not be empty" if meta[:codec].to_s.empty?
+
+probe = RockboxFFI::Metadata.probe("song.flac")
+puts "probe('song.flac') = #{probe.inspect}"
+raise "expected FLAC, got #{probe.inspect}" unless probe == "FLAC"
+
+# -- DSP: -6.0206 dB track gain should HALVE amplitude ------------------
+rate = 44_100
+RockboxFFI::Dsp.open(rate) do |dsp|
+  dsp.set_replaygain(RockboxFFI::DspReplayGainMode::TRACK, false, 0.0)
+  dsp.set_replaygain_gains(track_gain_db: -6.0206) # x0.5
+
+  sine = RockboxFFI.sine_stereo(1000, 1.0, rate, 16_000)
+  out = dsp.process(sine)
+  peak = out.map(&:abs).max
+  puts "DSP peak after -6.02 dB track gain: #{peak} (expected ~8000)"
+  raise "peak #{peak} out of range" unless (7_600..8_400).cover?(peak)
+end
+
+# -- Player (construct only, no audible playback) -----------------------
+RockboxFFI::Player.open(volume: 0.0) do |player|
+  sr = player.sample_rate
+  puts "Player sample_rate=#{sr}"
+  raise "sample_rate should be > 0" unless sr.positive?
+
+  player.set_volume(0.0)
+  player.set_queue([FIXTURE])
+  sleep 0.1 # the queue command is applied asynchronously by the engine thread
+
+  st = player.status
+  puts "Player status: state=#{st[:state].inspect} queue_len=#{st[:queue_len]}"
+  raise "expected stopped, got #{st[:state].inspect}" unless st[:state] == "stopped"
+  raise "expected queue_len 1, got #{st[:queue_len]}" unless st[:queue_len] == 1
+end
+
+puts "\nALL CHECKS PASSED ✔"

data/lib/rockbox_ffi/dsp.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RockboxFFI
+  # The DSP pipeline: EQ, tone, surround, compressor, ReplayGain, resampler.
+  #
+  # The underlying dsp_config is a process-wide singleton, so only one Dsp may
+  # exist at a time and it must be used from one thread. Call #close when done,
+  # or use the block form Dsp.open(rate) { |dsp| ... }.
+  class Dsp
+    # Open a Dsp; if a block is given, close it automatically afterwards.
+    def self.open(sample_rate)
+      dsp = new(sample_rate)
+      return dsp unless block_given?
+
+      begin
+        yield dsp
+      ensure
+        dsp.close
+      end
+    end
+
+    def initialize(sample_rate)
+      @ptr = Lib.rb_dsp_new(Integer(sample_rate))
+      raise "rb_dsp_new returned NULL" if @ptr.null?
+
+      @finalizer = self.class.send(:finalizer, @ptr)
+      ObjectSpace.define_finalizer(self, @finalizer)
+    end
+
+    # -- lifecycle --------------------------------------------------------
+    def close
+      return if @ptr.nil?
+
+      ObjectSpace.undefine_finalizer(self)
+      Lib.rb_dsp_free(@ptr)
+      @ptr = nil
+    end
+
+    def closed?
+      @ptr.nil?
+    end
+
+    def self.finalizer(ptr)
+      proc { Lib.rb_dsp_free(ptr) }
+    end
+    private_class_method :finalizer
+
+    # -- configuration ----------------------------------------------------
+    def set_input_frequency(hz)
+      Lib.rb_dsp_set_input_frequency(@ptr, Integer(hz))
+    end
+
+    def flush
+      Lib.rb_dsp_flush(@ptr)
+    end
+
+    def eq_enable(enable)
+      Lib.rb_dsp_eq_enable(@ptr, RockboxFFI.b(enable))
+    end
+
+    # Configure one EQ band (0..=9). Band 0 low shelf, 9 high shelf.
+    def set_eq_band(band, cutoff_hz, q, gain_db)
+      Lib.rb_dsp_set_eq_band(@ptr, Integer(band), Integer(cutoff_hz), Float(q), Float(gain_db))
+    end
+
+    def set_eq_precut(db)
+      Lib.rb_dsp_set_eq_precut(@ptr, Float(db))
+    end
+
+    def set_tone(bass_db, treble_db)
+      Lib.rb_dsp_set_tone(@ptr, Integer(bass_db), Integer(treble_db))
+    end
+
+    def set_tone_cutoffs(bass_hz, treble_hz)
+      Lib.rb_dsp_set_tone_cutoffs(@ptr, Integer(bass_hz), Integer(treble_hz))
+    end
+
+    def set_surround(delay_ms, balance, fx1, fx2)
+      Lib.rb_dsp_set_surround(@ptr, Integer(delay_ms), Integer(balance), Integer(fx1), Integer(fx2))
+    end
+
+    def set_channel_config(mode)
+      Lib.rb_dsp_set_channel_config(@ptr, Integer(mode))
+    end
+
+    def set_stereo_width(percent)
+      Lib.rb_dsp_set_stereo_width(@ptr, Integer(percent))
+    end
+
+    def set_compressor(threshold, makeup_gain, ratio, knee, release_time, attack_time)
+      Lib.rb_dsp_set_compressor(
+        @ptr, Integer(threshold), Integer(makeup_gain), Integer(ratio),
+        Integer(knee), Integer(release_time), Integer(attack_time)
+      )
+    end
+
+    # mode: see DspReplayGainMode (TRACK=0, ALBUM=1, SHUFFLE=2, OFF=3).
+    def set_replaygain(mode, noclip, preamp_db)
+      Lib.rb_dsp_set_replaygain(@ptr, Integer(mode), RockboxFFI.b(noclip), Float(preamp_db))
+    end
+
+    # Per-track gains in plain dB / peaks as linear amplitude (1.0 = full
+    # scale). nil for any absent tag (mapped to the ABI's NaN sentinel).
+    def set_replaygain_gains(track_gain_db: nil, album_gain_db: nil, track_peak: nil, album_peak: nil)
+      Lib.rb_dsp_set_replaygain_gains(
+        @ptr, opt(track_gain_db), opt(album_gain_db), opt(track_peak), opt(album_peak)
+      )
+    end
+
+    # Native Q7.24 linear factors (the raw_* fields from Metadata.read),
+    # 0 = not tagged.
+    def set_replaygain_gains_raw(track_gain, album_gain, track_peak, album_peak)
+      Lib.rb_dsp_set_replaygain_gains_raw(
+        @ptr, Integer(track_gain), Integer(album_gain), Integer(track_peak), Integer(album_peak)
+      )
+    end
+
+    # -- processing -------------------------------------------------------
+    # Run interleaved stereo S16 +samples+ (an Array of Integers) through the
+    # pipeline. Returns a new Array of processed samples (length may differ
+    # from the input — the resampler buffers).
+    def process(samples)
+      raise ArgumentError, "input must be interleaved stereo (even length)" if samples.length.odd?
+
+      input = samples.pack("s<*")               # int16 little-endian
+      out_len = "\0" * Fiddle::SIZEOF_VOIDP      # size_t* out-param (written in place)
+      out_ptr = Lib.rb_dsp_process(@ptr, input, samples.length, out_len)
+
+      produced = out_len.unpack1(Fiddle::SIZEOF_VOIDP == 8 ? "Q" : "L")
+      return [] if out_ptr.null? || produced.zero?
+
+      begin
+        out_ptr.size = produced * 2
+        out_ptr[0, produced * 2].unpack("s<*")
+      ensure
+        Lib.rb_buffer_free(out_ptr, produced)
+      end
+    end
+
+    private
+
+    NAN = Float::NAN
+    private_constant :NAN
+
+    # nil -> NaN, the ABI's "tag absent" sentinel.
+    def opt(value)
+      value.nil? ? NAN : Float(value)
+    end
+  end
+
+  # Generate +seconds+ of a sine as interleaved stereo int16 (an Array).
+  def self.sine_stereo(freq_hz, seconds, rate, amplitude = 16_000)
+    n = (seconds * rate).to_i
+    buf = Array.new(n * 2)
+    (0...n).each do |i|
+      s = (Math.sin(i * 2.0 * Math::PI * freq_hz / rate) * amplitude).to_i
+      s = -32_768 if s < -32_768
+      s = 32_767 if s > 32_767
+      buf[i * 2] = s
+      buf[(i * 2) + 1] = s
+    end
+    buf
+  end
+end

data/lib/rockbox_ffi/enums.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RockboxFFI
+  # Note the two *different* ReplayGain encodings in the C ABI.
+
+  # Values for Dsp#set_replaygain (native Rockbox).
+  module DspReplayGainMode
+    TRACK = 0
+    ALBUM = 1
+    SHUFFLE = 2
+    OFF = 3
+  end
+
+  # Values for Player#set_replaygain.
+  module ReplayGainMode
+    OFF = 0
+    TRACK = 1
+    ALBUM = 2
+  end
+
+  module CrossfadeMode
+    OFF = 0
+    AUTO_SKIP = 1
+    MANUAL_SKIP = 2
+    SHUFFLE = 3
+    SHUFFLE_OR_MANUAL = 4
+    ALWAYS = 5
+  end
+
+  module MixMode
+    CROSSFADE = 0
+    MIX = 1
+  end
+
+  module ChannelConfig
+    STEREO = 0
+    MONO = 1
+    CUSTOM = 2
+    MONO_LEFT = 3
+    MONO_RIGHT = 4
+    KARAOKE = 5
+    SWAP = 6
+  end
+end

data/lib/rockbox_ffi/ffi.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+# Fiddle (Ruby stdlib) loader for librockbox_ffi.
+#
+# Declares exactly the functions we call and dlopens the prebuilt shared
+# library — no C is compiled here. The library is located via the
+# ROCKBOX_FFI_LIB env var, then by walking up to the repo's target/release
+# directory. Mirrors include/rockbox_ffi.h — keep in sync with the C ABI.
+
+require "fiddle"
+require "fiddle/import"
+
+module RockboxFFI
+  # Locate the prebuilt shared library. Precedence:
+  #   1. ROCKBOX_FFI_LIB env var (explicit override)
+  #   2. the platform binary bundled in the gem's vendor/ dir (published gems)
+  #   3. target/release, by walking up from here (repo checkout / dev)
+  def self.library_path
+    names = %w[librockbox_ffi.dylib librockbox_ffi.so rockbox_ffi.dll]
+    tried = []
+
+    if (env = ENV["ROCKBOX_FFI_LIB"])
+      tried << env
+      return env if File.exist?(env)
+    end
+
+    # Bundled binary (platform gems ship one under <gem_root>/vendor/).
+    vendor = File.expand_path("../../vendor", __dir__)
+    names.each do |name|
+      cand = File.join(vendor, name)
+      tried << cand
+      return cand if File.exist?(cand)
+    end
+
+    # Walk up from this file looking for target/release (repo checkout).
+    dir = File.expand_path(__dir__)
+    loop do
+      rel = File.join(dir, "target", "release")
+      if File.directory?(rel)
+        names.each do |name|
+          cand = File.join(rel, name)
+          tried << cand
+          return cand if File.exist?(cand)
+        end
+      end
+      parent = File.dirname(dir)
+      break if parent == dir
+
+      dir = parent
+    end
+
+    raise LoadError, "could not locate librockbox_ffi shared library. Set " \
+                     "ROCKBOX_FFI_LIB or run `cargo build --release -p " \
+                     "rockbox-ffi`. Tried:\n  #{tried.join("\n  ")}"
+  end
+
+  # Thin Fiddle wrappers over the C ABI. Every function is a module method
+  # (e.g. `Lib.rb_dsp_new`). Opaque handles and char*/int16* returns come back
+  # as Fiddle::Pointer; scalars come back as Integer/Float.
+  module Lib
+    extend Fiddle::Importer
+    dlload RockboxFFI.library_path
+
+    # Fixed-width C types → Fiddle's native aliases (64-bit LP64 assumed).
+    typealias "uint32_t", "unsigned int"
+    typealias "int32_t", "int"
+    typealias "int16_t", "short"
+    typealias "int64_t", "long long"
+    typealias "uint64_t", "unsigned long long"
+    typealias "size_t", "unsigned long"
+    typealias "bool", "int" # passed as 0/1 in a full register on SysV/AAPCS
+
+    extern "uint32_t rb_ffi_abi_version()"
+
+    extern "void rb_string_free(void*)"
+    extern "void rb_buffer_free(void*, size_t)"
+
+    # ---- DSP ----------------------------------------------------------
+    extern "void* rb_dsp_new(uint32_t)"
+    extern "void rb_dsp_free(void*)"
+    extern "void rb_dsp_set_input_frequency(void*, uint32_t)"
+    extern "void rb_dsp_flush(void*)"
+    extern "void rb_dsp_eq_enable(void*, bool)"
+    extern "void rb_dsp_set_tone(void*, int32_t, int32_t)"
+    extern "void rb_dsp_set_tone_cutoffs(void*, int32_t, int32_t)"
+    extern "void rb_dsp_set_surround(void*, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_dsp_set_channel_config(void*, int32_t)"
+    extern "void rb_dsp_set_stereo_width(void*, int32_t)"
+    extern "void rb_dsp_set_compressor(void*, int32_t, int32_t, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_dsp_set_replaygain(void*, int32_t, bool, float)"
+    extern "void rb_dsp_set_replaygain_gains(void*, float, float, float, float)"
+    extern "void rb_dsp_set_replaygain_gains_raw(void*, int64_t, int64_t, int64_t, int64_t)"
+    extern "void rb_dsp_set_eq_band(void*, size_t, int32_t, float, float)"
+    extern "void rb_dsp_set_eq_precut(void*, float)"
+    extern "void* rb_dsp_process(void*, void*, size_t, void*)"
+
+    # ---- metadata -----------------------------------------------------
+    extern "void* rb_meta_read_json(void*)"
+    extern "void* rb_meta_probe(void*)"
+
+    # ---- player -------------------------------------------------------
+    extern "void* rb_player_new()"
+    extern "void* rb_player_new_with_config(uint32_t, float, float, int32_t, float, bool, int32_t, uint32_t, uint32_t, uint32_t, uint32_t, int32_t)"
+    extern "void rb_player_free(void*)"
+    extern "void rb_player_set_queue_json(void*, void*)"
+    extern "void rb_player_enqueue(void*, void*)"
+    extern "void rb_player_play(void*)"
+    extern "void rb_player_pause(void*)"
+    extern "void rb_player_toggle(void*)"
+    extern "void rb_player_stop(void*)"
+    extern "void rb_player_next(void*)"
+    extern "void rb_player_previous(void*)"
+    extern "void rb_player_skip_to(void*, size_t)"
+    extern "void rb_player_seek_ms(void*, uint64_t)"
+    extern "void rb_player_set_volume(void*, float)"
+    extern "void rb_player_set_crossfade(void*, int32_t, uint32_t, uint32_t, uint32_t, uint32_t, int32_t)"
+    extern "void rb_player_set_replaygain(void*, int32_t, float, bool)"
+    extern "float rb_player_volume(void*)"
+    extern "uint32_t rb_player_sample_rate(void*)"
+    extern "void* rb_player_status_json(void*)"
+  end
+
+  # true/false → 1/0 for the ABI's `bool` (declared as int above).
+  def self.b(flag)
+    flag ? 1 : 0
+  end
+
+  # Copy a heap C string returned by the ABI into a String, then free it.
+  # Returns nil for a NULL pointer (the ABI's error/absent signal).
+  def self.take_string(ptr)
+    return nil if ptr.null?
+
+    begin
+      ptr.to_s.force_encoding("UTF-8")
+    ensure
+      Lib.rb_string_free(ptr)
+    end
+  end
+end

data/lib/rockbox_ffi/metadata.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RockboxFFI
+  # Audio file metadata parsing.
+  module Metadata
+    module_function
+
+    # Parse the metadata of the audio file at +path+.
+    #
+    # Returns a Hash (symbol keys) with tag strings, +:duration_ms+,
+    # +:bitrate+, +:sample_rate+, a nested +:replaygain+ Hash (including the
+    # raw Q7.24 +raw_*+ fields), and optional +:album_art+ / +:cuesheet+
+    # locations. Raises on failure.
+    def read(path)
+      s = RockboxFFI.take_string(Lib.rb_meta_read_json(path.to_s))
+      raise "could not read metadata from #{path.inspect}" if s.nil?
+
+      JSON.parse(s, symbolize_names: true)
+    end
+
+    # Guess the codec label (e.g. "FLAC") from a filename's extension without
+    # opening the file. Returns nil for an unknown extension.
+    def probe(filename)
+      RockboxFFI.take_string(Lib.rb_meta_probe(filename.to_s))
+    end
+  end
+end

data/lib/rockbox_ffi/player.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RockboxFFI
+  # Queue-based player with native ReplayGain and Rockbox crossfade.
+  #
+  # A Player owns a live audio output device and a background engine thread —
+  # construct it only where an output device exists. Call #close when done,
+  # or use the block form Player.open(...) { |p| ... }.
+  #
+  # ReplayGain +mode+ here uses the *player* values: 0 off, 1 track, 2 album
+  # (see ReplayGainMode) — distinct from the DSP encoding.
+  class Player
+    DEFAULT_CONFIG = {
+      sample_rate: 0, # 0 => device default
+      buffer_seconds: 4.0,
+      volume: 1.0,
+      replaygain_mode: ReplayGainMode::OFF,
+      replaygain_preamp_db: 0.0,
+      replaygain_prevent_clipping: true,
+      crossfade_mode: CrossfadeMode::OFF,
+      fade_out_delay_ms: 0,
+      fade_out_duration_ms: 2000,
+      fade_in_delay_ms: 0,
+      fade_in_duration_ms: 2000,
+      mix_mode: MixMode::CROSSFADE
+    }.freeze
+
+    # Open a Player; if a block is given, close it automatically afterwards.
+    def self.open(**opts)
+      player = new(**opts)
+      return player unless block_given?
+
+      begin
+        yield player
+      ensure
+        player.close
+      end
+    end
+
+    # Player on the default device with Rockbox default settings.
+    def self.default
+      player = allocate
+      player.send(:init_ptr, Lib.rb_player_new)
+      player
+    end
+
+    # Create a player with configuration overrides (see DEFAULT_CONFIG keys).
+    # sample_rate: 0 means the device default.
+    def initialize(**opts)
+      c = DEFAULT_CONFIG.merge(opts)
+      ptr = Lib.rb_player_new_with_config(
+        Integer(c[:sample_rate]), Float(c[:buffer_seconds]), Float(c[:volume]),
+        Integer(c[:replaygain_mode]), Float(c[:replaygain_preamp_db]),
+        RockboxFFI.b(c[:replaygain_prevent_clipping]), Integer(c[:crossfade_mode]),
+        Integer(c[:fade_out_delay_ms]), Integer(c[:fade_out_duration_ms]),
+        Integer(c[:fade_in_delay_ms]), Integer(c[:fade_in_duration_ms]),
+        Integer(c[:mix_mode])
+      )
+      init_ptr(ptr)
+    end
+
+    # -- lifecycle --------------------------------------------------------
+    def close
+      return if @ptr.nil?
+
+      ObjectSpace.undefine_finalizer(self)
+      Lib.rb_player_free(@ptr)
+      @ptr = nil
+    end
+
+    def closed?
+      @ptr.nil?
+    end
+
+    def self.finalizer(ptr)
+      proc { Lib.rb_player_free(ptr) }
+    end
+    private_class_method :finalizer
+
+    # -- queue ------------------------------------------------------------
+    def set_queue(paths)
+      Lib.rb_player_set_queue_json(@ptr, JSON.generate(Array(paths).map(&:to_s)))
+    end
+
+    def enqueue(path)
+      Lib.rb_player_enqueue(@ptr, path.to_s)
+    end
+
+    # -- transport --------------------------------------------------------
+    def play
+      Lib.rb_player_play(@ptr)
+    end
+
+    def pause
+      Lib.rb_player_pause(@ptr)
+    end
+
+    def toggle
+      Lib.rb_player_toggle(@ptr)
+    end
+
+    def stop
+      Lib.rb_player_stop(@ptr)
+    end
+
+    def next
+      Lib.rb_player_next(@ptr)
+    end
+
+    def previous
+      Lib.rb_player_previous(@ptr)
+    end
+
+    def skip_to(index)
+      Lib.rb_player_skip_to(@ptr, Integer(index))
+    end
+
+    def seek_ms(ms)
+      Lib.rb_player_seek_ms(@ptr, Integer(ms))
+    end
+
+    # -- settings ---------------------------------------------------------
+    def set_volume(vol)
+      Lib.rb_player_set_volume(@ptr, Float(vol))
+    end
+
+    def volume
+      Lib.rb_player_volume(@ptr)
+    end
+
+    def sample_rate
+      Lib.rb_player_sample_rate(@ptr)
+    end
+
+    def set_crossfade(mode, fade_out_delay_ms: 0, fade_out_duration_ms: 2000,
+                      fade_in_delay_ms: 0, fade_in_duration_ms: 2000,
+                      mix_mode: MixMode::CROSSFADE)
+      Lib.rb_player_set_crossfade(
+        @ptr, Integer(mode), Integer(fade_out_delay_ms), Integer(fade_out_duration_ms),
+        Integer(fade_in_delay_ms), Integer(fade_in_duration_ms), Integer(mix_mode)
+      )
+    end
+
+    # mode: see ReplayGainMode (OFF=0, TRACK=1, ALBUM=2).
+    def set_replaygain(mode, preamp_db, prevent_clipping)
+      Lib.rb_player_set_replaygain(@ptr, Integer(mode), Float(preamp_db), RockboxFFI.b(prevent_clipping))
+    end
+
+    # -- status -----------------------------------------------------------
+    # A snapshot of the player's status as a Hash with symbol keys.
+    def status
+      s = RockboxFFI.take_string(Lib.rb_player_status_json(@ptr))
+      raise "rb_player_status_json returned NULL" if s.nil?
+
+      JSON.parse(s, symbolize_names: true)
+    end
+
+    private
+
+    def init_ptr(ptr)
+      raise "failed to create Player (no output device?)" if ptr.nil? || ptr.null?
+
+      @ptr = ptr
+      ObjectSpace.define_finalizer(self, self.class.send(:finalizer, ptr))
+    end
+  end
+end

data/lib/rockbox_ffi/version.rb

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

data/lib/rockbox_ffi.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Ruby bindings for the Rockbox DSP / metadata / playback engine.
+#
+# Thin Fiddle wrappers over the librockbox_ffi C ABI. See RockboxFFI::Metadata,
+# RockboxFFI::Dsp, and RockboxFFI::Player.
+
+require "rockbox_ffi/version"
+require "rockbox_ffi/ffi"
+require "rockbox_ffi/enums"
+require "rockbox_ffi/metadata"
+require "rockbox_ffi/dsp"
+require "rockbox_ffi/player"
+
+module RockboxFFI
+  # ABI major version of the loaded library (bumped on breaking changes).
+  def self.abi_version
+    Lib.rb_ffi_abi_version
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: rockbox_ffi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- Tsiry Sandratraina
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 'Fiddle-based bindings over the librockbox_ffi C ABI: audio metadata
+  parsing, the Rockbox DSP pipeline (EQ / tone / surround / compressor / ReplayGain),
+  and a queue-based player.'
+email:
+- tsiry.sndr@rocksky.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- examples/play.rb
+- examples/smoke.rb
+- lib/rockbox_ffi.rb
+- lib/rockbox_ffi/dsp.rb
+- lib/rockbox_ffi/enums.rb
+- lib/rockbox_ffi/ffi.rb
+- lib/rockbox_ffi/metadata.rb
+- lib/rockbox_ffi/player.rb
+- lib/rockbox_ffi/version.rb
+- vendor/librockbox_ffi.so
+homepage: https://github.com/tsirysndr/rockboxd
+licenses:
+- GPL-2.0-or-later
+metadata:
+  homepage_uri: https://github.com/tsirysndr/rockboxd
+  source_code_uri: https://github.com/tsirysndr/rockboxd/tree/master/bindings/ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby bindings for the Rockbox DSP / metadata / playback engine
+test_files: []