rockbox_ffi 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78ae6470117f6b52f565285e04c0d65742da1296fc3b336ad6cf3c246266c5ee
-  data.tar.gz: 11281048c1996c24ff83ec3ceb1f5d66c8529527f2f0f91e3498836eb4fc39ad
+  metadata.gz: 9e881324e0bb82a716a98417325a1ec9823d3a0f1f015444c6e2332f7b942c65
+  data.tar.gz: 70e45aa728fb5d2449e1849f993780a0dad201f32113eb4f352344df0bed1fb6
 SHA512:
-  metadata.gz: dcc042306ae5c1ee6afe35a951a0f3ac2da9ad78b33605009b04f755ef23f253efb061f2ddb64afef34760b0a5642b1bc77ddbcfb95db8cc99b1d1198a41feb7
-  data.tar.gz: 9bf8d8eacd74b7cdef21bfe8bd80f810c58ae742e752f9a12709bd9df296f8a9b502ab014b5335fec522800f6c232dedf6796f168c5a8e07a3ddbea2f36cdb96
+  metadata.gz: b76132c6b6db3f4eee20a990707b9e65e4a7a65cd490f1d690dbf0c8c72338a7c855cf75c12deb74171d6dd3833f2394dc33ad745e87172b0d1423e631e32f59
+  data.tar.gz: 7ef952e10d6a0728a4ef251ef43480ab6bc4d5d7fe3b7514b3c933f9cef99768ec129552f964cf3641ed98973e5831ab6272690f30b4c0fc6eca8a02d06d0f0e

data/README.md

@@ -10,6 +10,10 @@ 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.
 
+> 📖 **Sound settings reference** — the equalizer, tone, crossfeed, compressor
+> and other DSP controls mirror Rockbox's own. See the official
+> [Rockbox manual — Sound Settings](https://download.rockbox.org/daily/manual/rockbox-ipodvideo/rockbox-buildch6.html).
+
 ## Setup
 
 Build the shared library once (from the repo root):

data/examples/play.rb

@@ -13,9 +13,16 @@ FIXTURE = File.join(REPO, "crates", "rocksky", "fixtures", "08 - Internet Money
 file = ARGV[0] || FIXTURE
 
 player = RockboxFFI::Player.new(volume: 0.8)
-player.set_queue([file])
-player.play
+# Mutating setters return self, so the setup reads as one fluent chain.
+# DSP: Bass Boost preset + a +7 dB bass / +4 dB treble lift.
+player
+  .set_queue([file])
+  .set_eq_preset(RockboxFFI::EqPreset::BASS_BOOST)
+  .set_bass(7)
+  .set_treble(4)
+  .play
 puts "▶ playing #{file}"
+puts "eq: BassBoost preset, bass +7 dB, treble +4 dB"
 
 # Reinstall a SIGINT handler AFTER the player boots: the native audio engine
 # installs its own signal handler while starting the output device, which

data/lib/rockbox_ffi/decoder.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RockboxFFI
+  # Decode a local audio file to interleaved-stereo S16 PCM, one chunk at a
+  # time, using the Rockbox codec engine.
+  #
+  # The codec state is process-wide, so only one Decoder may decode at a time
+  # and it must be used from one thread. Call #close when done, or use the block
+  # form Decoder.open(path) { |dec| ... }.
+  class Decoder
+    # Open a Decoder for +path+; if a block is given, close it automatically
+    # afterwards.
+    def self.open(path)
+      dec = new(path)
+      return dec unless block_given?
+
+      begin
+        yield dec
+      ensure
+        dec.close
+      end
+    end
+
+    def initialize(path)
+      @ptr = Lib.rb_decoder_open(path.to_s)
+      raise "could not open decoder for #{path.inspect}" 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_decoder_free(@ptr)
+      @ptr = nil
+    end
+
+    def closed?
+      @ptr.nil?
+    end
+
+    def self.finalizer(ptr)
+      proc { Lib.rb_decoder_free(ptr) }
+    end
+    private_class_method :finalizer
+
+    # -- metadata ---------------------------------------------------------
+    # Tags and stream properties (same shape as Metadata.read). Returns a Hash
+    # with symbol keys. Raises on failure.
+    def metadata
+      s = RockboxFFI.take_string(Lib.rb_decoder_metadata_json(@ptr))
+      raise "rb_decoder_metadata_json returned NULL" if s.nil?
+
+      JSON.parse(s, symbolize_names: true)
+    end
+
+    # -- decoding ---------------------------------------------------------
+    # Next buffer of decoded PCM as +[samples, sample_rate]+, where +samples+
+    # is an Array of interleaved stereo int16 Integers. Returns nil at end of
+    # track (or after a codec error — see #finished).
+    def next_chunk
+      out_len = "\0" * Fiddle::SIZEOF_VOIDP      # size_t* out-param (i16 count)
+      out_rate = "\0" * Fiddle::SIZEOF_INT       # uint32_t* out-param (Hz)
+      ptr = Lib.rb_decoder_next_chunk(@ptr, out_len, out_rate)
+
+      produced = out_len.unpack1(Fiddle::SIZEOF_VOIDP == 8 ? "Q" : "L")
+      return nil if ptr.null? || produced.zero?
+
+      rate = out_rate.unpack1("L")
+      begin
+        ptr.size = produced * 2
+        [ptr[0, produced * 2].unpack("s<*"), rate]
+      ensure
+        Lib.rb_buffer_free(ptr, produced)
+      end
+    end
+
+    # Yield each +[samples, sample_rate]+ chunk until end of track. Returns an
+    # Enumerator when no block is given.
+    def each_chunk
+      return enum_for(:each_chunk) unless block_given?
+
+      while (chunk = next_chunk)
+        yield chunk
+      end
+    end
+
+    # Request a seek to +ms+ milliseconds.
+    def seek_ms(ms)
+      Lib.rb_decoder_seek_ms(@ptr, Integer(ms))
+    end
+
+    # Playback position last reported by the codec, in milliseconds.
+    def elapsed_ms
+      Lib.rb_decoder_elapsed_ms(@ptr)
+    end
+
+    # +[done, code]+: +done+ is true once the track has ended; +code+ is the
+    # exit status (0 = clean end, negative = codec error), valid only when
+    # +done+.
+    def finished
+      out_code = "\0" * Fiddle::SIZEOF_INT       # int32_t* out-param
+      r = Lib.rb_decoder_finished(@ptr, out_code)
+      done = r == true || r == 1
+      [done, out_code.unpack1("l")]
+    end
+  end
+end

data/lib/rockbox_ffi/enums.rb

@@ -18,6 +18,13 @@ module RockboxFFI
     ALBUM = 2
   end
 
+  # Values for Player#set_repeat / #repeat.
+  module RepeatMode
+    OFF = 0
+    ONE = 1
+    ALL = 2
+  end
+
   module CrossfadeMode
     OFF = 0
     AUTO_SKIP = 1
@@ -54,4 +61,47 @@ module RockboxFFI
     KARAOKE = 5
     SWAP = 6
   end
+
+  # Built-in EQ presets for Player#set_eq_preset.
+  module EqPreset
+    FLAT = 0
+    ACOUSTIC = 1
+    BASS_BOOST = 2
+    BASS_REDUCER = 3
+    CLASSICAL = 4
+    DANCE = 5
+    DEEP = 6
+    ELECTRONIC = 7
+    HIP_HOP = 8
+    JAZZ = 9
+    LATIN = 10
+    LOUDNESS = 11
+    LOUNGE = 12
+    PIANO = 13
+    POP = 14
+    RNB = 15
+    ROCK = 16
+    SMALL_SPEAKERS = 17
+    TREBLE_BOOST = 18
+    TREBLE_REDUCER = 19
+    VOCAL_BOOST = 20
+  end
+
+  # Crossfeed mode for Player#set_crossfeed.
+  module CrossfeedMode
+    OFF = 0
+    MEIER = 1
+    CUSTOM = 2
+  end
+
+  # Channel mode for Player#set_channel_mode.
+  module ChannelMode
+    STEREO = 0
+    MONO = 1
+    CUSTOM = 2
+    MONO_LEFT = 3
+    MONO_RIGHT = 4
+    KARAOKE = 5
+    SWAP = 6
+  end
 end

data/lib/rockbox_ffi/ffi.rb

@@ -98,6 +98,15 @@ module RockboxFFI
     extern "void* rb_meta_read_json(void*)"
     extern "void* rb_meta_probe(void*)"
 
+    # ---- decoder ------------------------------------------------------
+    extern "void* rb_decoder_open(void*)"
+    extern "void rb_decoder_free(void*)"
+    extern "void* rb_decoder_metadata_json(void*)"
+    extern "int16_t* rb_decoder_next_chunk(void*, void*, void*)"
+    extern "void rb_decoder_seek_ms(void*, uint64_t)"
+    extern "uint64_t rb_decoder_elapsed_ms(void*)"
+    extern "bool rb_decoder_finished(void*, 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)"
@@ -116,11 +125,39 @@ module RockboxFFI
     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_balance(void*, int32_t)"
     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 "int32_t rb_player_balance(void*)"
     extern "uint32_t rb_player_sample_rate(void*)"
     extern "void* rb_player_status_json(void*)"
+    extern "void rb_player_set_shuffle(void*, bool)"
+    extern "bool rb_player_is_shuffle_enabled(void*)"
+    extern "void rb_player_set_repeat(void*, int32_t)"
+    extern "int32_t rb_player_repeat(void*)"
+
+    # ---- player DSP ---------------------------------------------------
+    extern "void rb_player_set_eq_enabled(void*, bool)"
+    extern "bool rb_player_is_eq_enabled(void*)"
+    extern "void rb_player_set_eq_band(void*, size_t, int32_t, float, float)"
+    extern "void rb_player_set_eq_precut(void*, float)"
+    extern "void rb_player_set_eq_preset(void*, int32_t)"
+    extern "void rb_player_set_tone(void*, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_player_set_bass(void*, int32_t)"
+    extern "void rb_player_set_treble(void*, int32_t)"
+    extern "void rb_player_set_bass_cutoff(void*, int32_t)"
+    extern "void rb_player_set_treble_cutoff(void*, int32_t)"
+    extern "void rb_player_set_crossfeed(void*, int32_t, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_player_set_bass_enhancement(void*, int32_t, int32_t)"
+    extern "void rb_player_set_fatigue_reduction(void*, int32_t)"
+    extern "void rb_player_set_surround(void*, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_player_set_channel_mode(void*, int32_t)"
+    extern "void rb_player_set_stereo_width(void*, int32_t)"
+    extern "void rb_player_set_compressor(void*, int32_t, int32_t, int32_t, int32_t, int32_t, int32_t)"
+    extern "void rb_player_set_dither(void*, bool)"
+    extern "void rb_player_set_pitch(void*, int32_t)"
+    extern "void* rb_player_dsp_settings_json(void*)"
 
     # ---- resume -------------------------------------------------------
     extern "void* rb_player_resume(void*)"

data/lib/rockbox_ffi/player.rb

@@ -11,6 +11,11 @@ module RockboxFFI
   #
   # ReplayGain +mode+ here uses the *player* values: 0 off, 1 track, 2 album
   # (see ReplayGainMode) — distinct from the DSP encoding.
+  #
+  # Mutating setters (queue, transport, settings, DSP) return +self+ so calls
+  # can be fluently chained, e.g.
+  #   player.set_queue([file]).set_shuffle(true).play
+  # Getters/queries and lifecycle methods keep their own return values.
   class Player
     DEFAULT_CONFIG = {
       sample_rate: 0, # 0 => device default
@@ -85,12 +90,18 @@ module RockboxFFI
     private_class_method :finalizer
 
     # -- queue ------------------------------------------------------------
+    # Replace the queue. Each entry may be a local file path, an http(s)://
+    # URL to a finite remote file, or a live-radio / streaming URL.
     def set_queue(paths)
       Lib.rb_player_set_queue_json(@ptr, JSON.generate(Array(paths).map(&:to_s)))
+      self
     end
 
+    # Append one track to the queue. +path+ may be a local file path, an
+    # http(s):// URL to a finite remote file, or a live-radio / streaming URL.
     def enqueue(path)
       Lib.rb_player_enqueue(@ptr, path.to_s)
+      self
     end
 
     # Insert +paths+ (a path/URL or Array of them) into the queue at
@@ -100,6 +111,7 @@ module RockboxFFI
       Lib.rb_player_insert_json(
         @ptr, JSON.generate(Array(paths).map(&:to_s)), Integer(position), Integer(index)
       )
+      self
     end
 
     # The current queue as an Array of String paths/URLs.
@@ -113,45 +125,65 @@ module RockboxFFI
     # -- transport --------------------------------------------------------
     def play
       Lib.rb_player_play(@ptr)
+      self
     end
 
     def pause
       Lib.rb_player_pause(@ptr)
+      self
     end
 
     def toggle
       Lib.rb_player_toggle(@ptr)
+      self
     end
 
     def stop
       Lib.rb_player_stop(@ptr)
+      self
     end
 
     def next
       Lib.rb_player_next(@ptr)
+      self
     end
 
     def previous
       Lib.rb_player_previous(@ptr)
+      self
     end
 
     def skip_to(index)
       Lib.rb_player_skip_to(@ptr, Integer(index))
+      self
     end
 
     def seek_ms(ms)
       Lib.rb_player_seek_ms(@ptr, Integer(ms))
+      self
     end
 
     # -- settings ---------------------------------------------------------
     def set_volume(vol)
       Lib.rb_player_set_volume(@ptr, Float(vol))
+      self
+    end
+
+    # Stereo balance, -100 (full left) to +100 (full right); 0 = centre.
+    def set_balance(balance)
+      Lib.rb_player_set_balance(@ptr, Integer(balance))
+      self
     end
 
     def volume
       Lib.rb_player_volume(@ptr)
     end
 
+    # Current stereo balance, -100 (full left) to +100 (full right).
+    def balance
+      Lib.rb_player_balance(@ptr)
+    end
+
     def sample_rate
       Lib.rb_player_sample_rate(@ptr)
     end
@@ -163,11 +195,173 @@ module RockboxFFI
         @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)
       )
+      self
     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))
+      self
+    end
+
+    # Enable/disable shuffle.
+    def set_shuffle(enabled)
+      Lib.rb_player_set_shuffle(@ptr, RockboxFFI.b(enabled))
+      self
+    end
+
+    # Whether shuffle is currently enabled.
+    def shuffle_enabled?
+      !Lib.rb_player_is_shuffle_enabled(@ptr).zero?
+    end
+
+    # Set the repeat mode (see RepeatMode: OFF=0, ONE=1, ALL=2).
+    def set_repeat(mode)
+      Lib.rb_player_set_repeat(@ptr, Integer(mode))
+      self
+    end
+
+    # The current repeat mode as an Integer (see RepeatMode).
+    def repeat
+      Lib.rb_player_repeat(@ptr)
+    end
+
+    # -- DSP --------------------------------------------------------------
+    # Enable/disable the parametric equalizer.
+    def set_eq_enabled(enabled)
+      Lib.rb_player_set_eq_enabled(@ptr, RockboxFFI.b(enabled))
+      self
+    end
+
+    # Whether the parametric equalizer is currently enabled.
+    def eq_enabled?
+      !Lib.rb_player_is_eq_enabled(@ptr).zero?
+    end
+
+    # Configure one EQ band: +band+ index, +cutoff_hz+ center frequency,
+    # +q+ factor, +gain_db+ gain in dB.
+    def set_eq_band(band, cutoff_hz, q, gain_db)
+      Lib.rb_player_set_eq_band(@ptr, Integer(band), Integer(cutoff_hz), Float(q), Float(gain_db))
+      self
+    end
+
+    # Global EQ pre-cut in dB.
+    def set_eq_precut(db)
+      Lib.rb_player_set_eq_precut(@ptr, Float(db))
+      self
+    end
+
+    # Apply a built-in EQ preset (see EqPreset).
+    def set_eq_preset(preset)
+      Lib.rb_player_set_eq_preset(@ptr, Integer(preset))
+      self
+    end
+
+    # Bass/treble tone controls with explicit cutoff frequencies.
+    def set_tone(bass_db, treble_db, bass_cutoff_hz, treble_cutoff_hz)
+      Lib.rb_player_set_tone(
+        @ptr, Integer(bass_db), Integer(treble_db),
+        Integer(bass_cutoff_hz), Integer(treble_cutoff_hz)
+      )
+      self
+    end
+
+    # Bass gain in dB.
+    def set_bass(bass_db)
+      Lib.rb_player_set_bass(@ptr, Integer(bass_db))
+      self
+    end
+
+    # Treble gain in dB.
+    def set_treble(treble_db)
+      Lib.rb_player_set_treble(@ptr, Integer(treble_db))
+      self
+    end
+
+    # Bass tone-control cutoff frequency in Hz.
+    def set_bass_cutoff(hz)
+      Lib.rb_player_set_bass_cutoff(@ptr, Integer(hz))
+      self
+    end
+
+    # Treble tone-control cutoff frequency in Hz.
+    def set_treble_cutoff(hz)
+      Lib.rb_player_set_treble_cutoff(@ptr, Integer(hz))
+      self
+    end
+
+    # Crossfeed for headphone listening. +mode+ (see CrossfeedMode: OFF=0,
+    # MEIER=1, CUSTOM=2), plus direct/cross/high-frequency gains and the
+    # high-frequency cutoff (Hz) used in CUSTOM mode.
+    def set_crossfeed(mode, direct_gain, cross_gain, hf_gain, hf_cutoff)
+      Lib.rb_player_set_crossfeed(
+        @ptr, Integer(mode), Integer(direct_gain), Integer(cross_gain),
+        Integer(hf_gain), Integer(hf_cutoff)
+      )
+      self
+    end
+
+    # Bass enhancement: +strength+ and +precut+ (in dB).
+    def set_bass_enhancement(strength, precut)
+      Lib.rb_player_set_bass_enhancement(@ptr, Integer(strength), Integer(precut))
+      self
+    end
+
+    # Listening-fatigue reduction (treble roll-off): +strength+.
+    def set_fatigue_reduction(strength)
+      Lib.rb_player_set_fatigue_reduction(@ptr, Integer(strength))
+      self
+    end
+
+    # Surround effect: delay (ms), balance, low/high cutoff frequencies (Hz).
+    def set_surround(delay_ms, balance, cutoff_low_hz, cutoff_high_hz)
+      Lib.rb_player_set_surround(
+        @ptr, Integer(delay_ms), Integer(balance),
+        Integer(cutoff_low_hz), Integer(cutoff_high_hz)
+      )
+      self
+    end
+
+    # Channel mode (see ChannelMode).
+    def set_channel_mode(mode)
+      Lib.rb_player_set_channel_mode(@ptr, Integer(mode))
+      self
+    end
+
+    # Stereo width as a percentage.
+    def set_stereo_width(percent)
+      Lib.rb_player_set_stereo_width(@ptr, Integer(percent))
+      self
+    end
+
+    # Dynamic-range compressor: threshold (dB), makeup gain, ratio, knee,
+    # attack (ms), release (ms).
+    def set_compressor(threshold_db, makeup_gain, ratio, knee, attack_ms, release_ms)
+      Lib.rb_player_set_compressor(
+        @ptr, Integer(threshold_db), Integer(makeup_gain), Integer(ratio),
+        Integer(knee), Integer(attack_ms), Integer(release_ms)
+      )
+      self
+    end
+
+    # Enable/disable output dithering.
+    def set_dither(enabled)
+      Lib.rb_player_set_dither(@ptr, RockboxFFI.b(enabled))
+      self
+    end
+
+    # Pitch shift ratio.
+    def set_pitch(ratio)
+      Lib.rb_player_set_pitch(@ptr, Integer(ratio))
+      self
+    end
+
+    # A snapshot of the current DSP settings as a Hash with symbol keys.
+    def dsp_settings
+      s = RockboxFFI.take_string(Lib.rb_player_dsp_settings_json(@ptr))
+      raise "rb_player_dsp_settings_json returned NULL" if s.nil?
+
+      JSON.parse(s, symbolize_names: true)
     end
 
     # -- status -----------------------------------------------------------

data/lib/rockbox_ffi/version.rb

@@ -1,3 +1,3 @@
 module RockboxFFI
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/rockbox_ffi.rb

@@ -3,7 +3,7 @@
 # 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.
+# RockboxFFI::Dsp, RockboxFFI::Player, and RockboxFFI::Decoder.
 
 require "rockbox_ffi/version"
 require "rockbox_ffi/ffi"
@@ -11,6 +11,7 @@ require "rockbox_ffi/enums"
 require "rockbox_ffi/metadata"
 require "rockbox_ffi/dsp"
 require "rockbox_ffi/player"
+require "rockbox_ffi/decoder"
 
 require "json"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rockbox_ffi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tsiry Sandratraina
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-12 00:00:00.000000000 Z
+date: 2026-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle
@@ -37,6 +37,7 @@ files:
 - examples/play.rb
 - examples/smoke.rb
 - lib/rockbox_ffi.rb
+- lib/rockbox_ffi/decoder.rb
 - lib/rockbox_ffi/dsp.rb
 - lib/rockbox_ffi/enums.rb
 - lib/rockbox_ffi/ffi.rb