rockbox_ffi 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65435e6c7a7b4ef8e59f3bc088ce2c9eb978b34d49e134c3e42413e9790bb333
-  data.tar.gz: 0d14838882902eaa6818a9726518f0c782848ad34e09b6afe6ca9ddbbf6cdd1a
+  metadata.gz: 98d2db65260fc33b5cfd9cf8963c2f96b782079c999ded173f64611a1f3d2554
+  data.tar.gz: 8b6fa4f9f221aad0367c913cc6ce494ea97ce62d3658309cc6ed8252003e28d1
 SHA512:
-  metadata.gz: f4275075ebc6d35b7b495dfc3a081b97960f5dc81f8f279372acf5b852fc0723776f536f9f87602811499a23d1653de9a8c5b072144444fe15dd0cd4b4dc1066
-  data.tar.gz: 5b4a35ca244aed1f570cf2d639a131eb8244645fe4ebe86513193345a95716107c72c67f7037f195e8048bff4f885c1d3c8af1fdd218ffabcf200860b841e363
+  metadata.gz: 97340abbfae011f7f3f09a0463046c4831eef6d429ea6d0f1ea0a814a8aac085a12309d46fe7e5ee670772aed59cf9045cbfe72606bdf34e0aab685c534aab04
+  data.tar.gz: b28b979145c98b851ab27cf731fb9929603a946a17435e656cb2f350af594bc8fefe525545c6bd2dafa3dd3a6236dcf998b672636f3d09ce16c95b94069d3d3d

data/README.md

@@ -5,7 +5,8 @@
 ![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,
+Ruby bindings for the Rockbox **DSP**, **metadata**, **codecs**, 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.
@@ -53,28 +54,40 @@ RockboxFFI::Dsp.open(44_100) do |dsp|
   processed = dsp.process(samples)                # Array<Integer>
 end
 
+# --- codecs (decode a file to PCM, one chunk at a time) ---------------
+RockboxFFI::Decoder.open("song.flac") do |dec|
+  dec.metadata[:title]                            # tags from the open file
+  dec.each_chunk do |samples, sample_rate|        # Array<Integer>, Hz
+    # samples: interleaved-stereo signed 16-bit PCM
+  end
+  dec.finished                                    # => [true, 0]  (0 = clean)
+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"])
+  # Queue entries may be local files, http(s):// URLs to remote media,
+  # or live-radio / streaming URLs — mix and match freely.
+  player.set_queue(["a.flac", "https://example.com/b.mp3", "http://radio.example/stream"])
   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.
+`Dsp`, `Decoder`, 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` |
+| Namespace              | Contents                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------ |
+| `RockboxFFI::Metadata` | `read(path) => Hash`, `probe(filename) => String \| nil`                                   |
+| `RockboxFFI::Dsp`      | EQ / tone / surround / compressor / ReplayGain, `process(samples)`                         |
+| `RockboxFFI::Decoder`  | codec engine: `metadata`, `each_chunk` / `next_chunk`, `seek_ms`, `elapsed_ms`, `finished` |
+| `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>`

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)"
@@ -106,6 +115,8 @@ module RockboxFFI
     extern "void rb_player_set_queue_json(void*, void*)"
     extern "void rb_player_enqueue(void*, void*)"
     extern "void rb_player_insert_json(void*, void*, int32_t, size_t)"
+    extern "void rb_player_remove(void*, size_t)"
+    extern "void rb_player_clear_queue(void*)"
     extern "void* rb_player_queue_json(void*)"
     extern "void rb_player_play(void*)"
     extern "void rb_player_pause(void*)"
@@ -116,9 +127,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

@@ -114,6 +114,22 @@ module RockboxFFI
       self
     end
 
+    # Remove the track at +index+ (0-based) from the queue. An out-of-range
+    # index is ignored. Removing a track before the current one keeps the
+    # current track playing; removing the currently-playing track hard-cuts to
+    # the track that slides into its place; removing the last remaining track
+    # stops playback.
+    def remove(index)
+      Lib.rb_player_remove(@ptr, Integer(index))
+      self
+    end
+
+    # Empty the queue and stop playback (also clears any saved resume state).
+    def clear_queue
+      Lib.rb_player_clear_queue(@ptr)
+      self
+    end
+
     # The current queue as an Array of String paths/URLs.
     def queue
       s = RockboxFFI.take_string(Lib.rb_player_queue_json(@ptr))
@@ -169,10 +185,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.5.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.5.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