rockbox_ffi 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f77ffe0b56e69c1749a47007c36837cd2b1a17a1c9cf36fd76a3ce42411af8
-  data.tar.gz: 620692c18aada83e7aa9b1d1e282f159fd804a9db0e2303677f825a04367fa81
+  metadata.gz: 78ae6470117f6b52f565285e04c0d65742da1296fc3b336ad6cf3c246266c5ee
+  data.tar.gz: 11281048c1996c24ff83ec3ceb1f5d66c8529527f2f0f91e3498836eb4fc39ad
 SHA512:
-  metadata.gz: 2217930492eb1d545fa86c0ffad14b90ec9144712320d03c46e595aba2fdc31d28ed1d256040d165a78c967465b3645b146117a40d45ce57ac06269d2e6da079
-  data.tar.gz: c3bed2b5f9238be0d072d46a82b5c6e697ea61dc041915389c8db7a139b3cb2d3805caff51e76571de703f3333653c5dbed0ca27f37ef7af0a4a9d9a2ca8e093
+  metadata.gz: dcc042306ae5c1ee6afe35a951a0f3ac2da9ad78b33605009b04f755ef23f253efb061f2ddb64afef34760b0a5642b1bc77ddbcfb95db8cc99b1d1198a41feb7
+  data.tar.gz: 9bf8d8eacd74b7cdef21bfe8bd80f810c58ae742e752f9a12709bd9df296f8a9b502ab014b5335fec522800f6c232dedf6796f168c5a8e07a3ddbea2f36cdb96

data/README.md

@@ -95,7 +95,7 @@ ruby -Ilib examples/play.rb [path]    # play a file through the output device
 ## Interactive console
 
 ```sh
-./bin/console        # or: rake console
+bundle exec rake console        # or: ./bin/console
 ```
 
 Drops into IRB with `RockboxFFI` loaded and `FIXTURE` pointing at a sample
@@ -108,6 +108,20 @@ p.set_queue([FIXTURE]); p.play
 p.status[:state]                                  # => "playing"
 ```
 
+The console bundles `irb` + `reline`, so **Tab autocompletion** and **syntax
+highlighting** work out of the box — start typing `RockboxFFI::` and press
+`Tab`. Both are on by default; toggle per-session with `irb --noautocomplete`,
+or persist preferences in `~/.irbrc`:
+
+```ruby
+IRB.conf[:USE_AUTOCOMPLETE] = true
+IRB.conf[:USE_COLORIZE]     = true
+```
+
+> Run the console under a modern Ruby (3.x/4.x, e.g. Homebrew's
+> `/opt/homebrew/opt/ruby`). macOS system Ruby 2.6 can't build `fiddle`'s
+> native extension, so `bundle install` fails there.
+
 ## Test
 
 ```sh

data/lib/rockbox_ffi/enums.rb

@@ -32,6 +32,19 @@ module RockboxFFI
     MIX = 1
   end
 
+  # Where inserted tracks land in the queue (Player#insert / #import_m3u).
+  # INDEX (7) uses the explicit +index+ argument.
+  module InsertPosition
+    PREPEND = 0
+    INSERT = 1
+    INSERT_NEXT = 2
+    INSERT_LAST = 3
+    INSERT_SHUFFLED = 4
+    INSERT_LAST_SHUFFLED = 5
+    REPLACE = 6
+    INDEX = 7
+  end
+
   module ChannelConfig
     STEREO = 0
     MONO = 1

data/lib/rockbox_ffi/ffi.rb

@@ -101,9 +101,12 @@ module RockboxFFI
     # ---- 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_new_with_config_ex(uint32_t, float, float, int32_t, float, bool, int32_t, uint32_t, uint32_t, uint32_t, uint32_t, int32_t, void*, uint32_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_insert_json(void*, void*, int32_t, size_t)"
+    extern "void* rb_player_queue_json(void*)"
     extern "void rb_player_play(void*)"
     extern "void rb_player_pause(void*)"
     extern "void rb_player_toggle(void*)"
@@ -118,6 +121,20 @@ module RockboxFFI
     extern "float rb_player_volume(void*)"
     extern "uint32_t rb_player_sample_rate(void*)"
     extern "void* rb_player_status_json(void*)"
+
+    # ---- resume -------------------------------------------------------
+    extern "void* rb_player_resume(void*)"
+    extern "void rb_player_save_resume(void*)"
+    extern "void rb_player_clear_resume(void*)"
+    extern "void* rb_load_resume_json(void*)"
+
+    # ---- m3u / m3u8 playlists -----------------------------------------
+    extern "void* rb_player_import_m3u(void*, void*, int32_t, size_t)"
+    extern "void* rb_player_load_m3u(void*, void*)"
+    extern "int32_t rb_player_export_m3u(void*, void*)"
+    extern "void* rb_m3u_read_json(void*)"
+    extern "int32_t rb_m3u_write_json(void*, void*)"
+    extern "bool rb_is_url(void*)"
   end
 
   # true/false → 1/0 for the ABI's `bool` (declared as int above).

data/lib/rockbox_ffi/player.rb

@@ -24,7 +24,9 @@ module RockboxFFI
       fade_out_duration_ms: 2000,
       fade_in_delay_ms: 0,
       fade_in_duration_ms: 2000,
-      mix_mode: MixMode::CROSSFADE
+      mix_mode: MixMode::CROSSFADE,
+      resume_file: nil, # an .m3u8 to auto-persist queue + position to
+      resume_save_interval_ms: 0 # 0 => 5 s default
     }.freeze
 
     # Open a Player; if a block is given, close it automatically afterwards.
@@ -47,16 +49,19 @@ module RockboxFFI
     end
 
     # Create a player with configuration overrides (see DEFAULT_CONFIG keys).
-    # sample_rate: 0 means the device default.
+    # sample_rate: 0 means the device default. Passing +resume_file:+ enables
+    # auto-persisting the queue + exact position to that .m3u8 file.
     def initialize(**opts)
       c = DEFAULT_CONFIG.merge(opts)
-      ptr = Lib.rb_player_new_with_config(
+      resume_file = c[:resume_file].nil? ? nil : c[:resume_file].to_s
+      ptr = Lib.rb_player_new_with_config_ex(
         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])
+        Integer(c[:mix_mode]), resume_file,
+        Integer(c[:resume_save_interval_ms])
       )
       init_ptr(ptr)
     end
@@ -88,6 +93,23 @@ module RockboxFFI
       Lib.rb_player_enqueue(@ptr, path.to_s)
     end
 
+    # Insert +paths+ (a path/URL or Array of them) into the queue at
+    # +position+ (see InsertPosition). +index+ is only used when position is
+    # InsertPosition::INDEX (7).
+    def insert(paths, position, index = 0)
+      Lib.rb_player_insert_json(
+        @ptr, JSON.generate(Array(paths).map(&:to_s)), Integer(position), Integer(index)
+      )
+    end
+
+    # The current queue as an Array of String paths/URLs.
+    def queue
+      s = RockboxFFI.take_string(Lib.rb_player_queue_json(@ptr))
+      return [] if s.nil?
+
+      JSON.parse(s)
+    end
+
     # -- transport --------------------------------------------------------
     def play
       Lib.rb_player_play(@ptr)
@@ -157,6 +179,51 @@ module RockboxFFI
       JSON.parse(s, symbolize_names: true)
     end
 
+    # -- resume -----------------------------------------------------------
+    # Restore the queue + exact position from the resume file (does NOT
+    # auto-play). Returns a Hash {tracks:, index:, elapsed_ms:} or nil.
+    def resume
+      s = RockboxFFI.take_string(Lib.rb_player_resume(@ptr))
+      return nil if s.nil?
+
+      JSON.parse(s, symbolize_names: true)
+    end
+
+    # Force-persist the current queue + position to the resume file now.
+    def save_resume
+      Lib.rb_player_save_resume(@ptr)
+    end
+
+    # Delete the resume file.
+    def clear_resume
+      Lib.rb_player_clear_resume(@ptr)
+    end
+
+    # -- m3u / m3u8 playlists ---------------------------------------------
+    # Import a playlist file into the queue at +position+ (see InsertPosition;
+    # +index+ only used for INDEX). Returns the imported paths as an Array.
+    def import_m3u(path, position, index = 0)
+      s = RockboxFFI.take_string(
+        Lib.rb_player_import_m3u(@ptr, path.to_s, Integer(position), Integer(index))
+      )
+      return [] if s.nil?
+
+      JSON.parse(s)
+    end
+
+    # Replace the queue with a playlist file. Returns the loaded paths as an Array.
+    def load_m3u(path)
+      s = RockboxFFI.take_string(Lib.rb_player_load_m3u(@ptr, path.to_s))
+      return [] if s.nil?
+
+      JSON.parse(s)
+    end
+
+    # Export the current queue to an .m3u8 (atomic). Returns true on success.
+    def export_m3u(path)
+      Lib.rb_player_export_m3u(@ptr, path.to_s).zero?
+    end
+
     private
 
     def init_ptr(ptr)

data/lib/rockbox_ffi/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module RockboxFFI
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/rockbox_ffi.rb

@@ -12,9 +12,41 @@ require "rockbox_ffi/metadata"
 require "rockbox_ffi/dsp"
 require "rockbox_ffi/player"
 
+require "json"
+
 module RockboxFFI
   # ABI major version of the loaded library (bumped on breaking changes).
   def self.abi_version
     Lib.rb_ffi_abi_version
   end
+
+  # Peek at a resume file without a Player. Returns a Hash
+  # {tracks:, index:, elapsed_ms:} or nil if the file is absent/invalid.
+  def self.load_resume(path)
+    s = take_string(Lib.rb_load_resume_json(path.to_s))
+    return nil if s.nil?
+
+    JSON.parse(s, symbolize_names: true)
+  end
+
+  # Parse a playlist (.m3u / .m3u8) into an Array of Hashes
+  # {path:, duration_ms:, title:}. Returns nil on failure.
+  def self.m3u_read(path)
+    s = take_string(Lib.rb_m3u_read_json(path.to_s))
+    return nil if s.nil?
+
+    JSON.parse(s, symbolize_names: true)
+  end
+
+  # Write +paths+ (a path/URL or Array of them) as an .m3u8. Returns true on
+  # success.
+  def self.m3u_write(path, paths)
+    Lib.rb_m3u_write_json(path.to_s, JSON.generate(Array(paths).map(&:to_s))).zero?
+  end
+
+  # Whether +s+ looks like an http(s):// URL.
+  def self.is_url?(s)
+    r = Lib.rb_is_url(s.to_s)
+    r == true || r == 1
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rockbox_ffi
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Tsiry Sandratraina
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle