rockbox_ffi 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65435e6c7a7b4ef8e59f3bc088ce2c9eb978b34d49e134c3e42413e9790bb333
-  data.tar.gz: 0d14838882902eaa6818a9726518f0c782848ad34e09b6afe6ca9ddbbf6cdd1a
+  metadata.gz: 9e881324e0bb82a716a98417325a1ec9823d3a0f1f015444c6e2332f7b942c65
+  data.tar.gz: 70e45aa728fb5d2449e1849f993780a0dad201f32113eb4f352344df0bed1fb6
 SHA512:
-  metadata.gz: f4275075ebc6d35b7b495dfc3a081b97960f5dc81f8f279372acf5b852fc0723776f536f9f87602811499a23d1653de9a8c5b072144444fe15dd0cd4b4dc1066
-  data.tar.gz: 5b4a35ca244aed1f570cf2d639a131eb8244645fe4ebe86513193345a95716107c72c67f7037f195e8048bff4f885c1d3c8af1fdd218ffabcf200860b841e363
+  metadata.gz: b76132c6b6db3f4eee20a990707b9e65e4a7a65cd490f1d690dbf0c8c72338a7c855cf75c12deb74171d6dd3833f2394dc33ad745e87172b0d1423e631e32f59
+  data.tar.gz: 7ef952e10d6a0728a4ef251ef43480ab6bc4d5d7fe3b7514b3c933f9cef99768ec129552f964cf3641ed98973e5831ab6272690f30b4c0fc6eca8a02d06d0f0e

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/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,9 +125,11 @@ 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)"

data/lib/rockbox_ffi/player.rb

@@ -169,10 +169,21 @@ module RockboxFFI
       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

data/lib/rockbox_ffi/version.rb

@@ -1,3 +1,3 @@
 module RockboxFFI
-  VERSION = "0.3.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.3.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