rockbox_ffi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78ae6470117f6b52f565285e04c0d65742da1296fc3b336ad6cf3c246266c5ee
-  data.tar.gz: 11281048c1996c24ff83ec3ceb1f5d66c8529527f2f0f91e3498836eb4fc39ad
+  metadata.gz: 65435e6c7a7b4ef8e59f3bc088ce2c9eb978b34d49e134c3e42413e9790bb333
+  data.tar.gz: 0d14838882902eaa6818a9726518f0c782848ad34e09b6afe6ca9ddbbf6cdd1a
 SHA512:
-  metadata.gz: dcc042306ae5c1ee6afe35a951a0f3ac2da9ad78b33605009b04f755ef23f253efb061f2ddb64afef34760b0a5642b1bc77ddbcfb95db8cc99b1d1198a41feb7
-  data.tar.gz: 9bf8d8eacd74b7cdef21bfe8bd80f810c58ae742e752f9a12709bd9df296f8a9b502ab014b5335fec522800f6c232dedf6796f168c5a8e07a3ddbea2f36cdb96
+  metadata.gz: f4275075ebc6d35b7b495dfc3a081b97960f5dc81f8f279372acf5b852fc0723776f536f9f87602811499a23d1653de9a8c5b072144444fe15dd0cd4b4dc1066
+  data.tar.gz: 5b4a35ca244aed1f570cf2d639a131eb8244645fe4ebe86513193345a95716107c72c67f7037f195e8048bff4f885c1d3c8af1fdd218ffabcf200860b841e363

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/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

@@ -121,6 +121,32 @@ module RockboxFFI
     extern "float rb_player_volume(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,39 +125,48 @@ 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
 
     def volume
@@ -163,11 +184,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.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rockbox_ffi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tsiry Sandratraina