Class: RockboxFFI::Player

Inherits:
Object
  • Object
show all
Defined in:
lib/rockbox_ffi/player.rb

Overview

Queue-based player with native ReplayGain and Rockbox crossfade.

A Player owns a live audio output device and a background engine thread — construct it only where an output device exists. Call #close when done, or use the block form Player.open(...) { |p| ... }.

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.

Constant Summary collapse

DEFAULT_CONFIG = 
{
  sample_rate: 0, # 0 => device default
  buffer_seconds: 4.0,
  volume: 1.0,
  replaygain_mode: ReplayGainMode::OFF,
  replaygain_preamp_db: 0.0,
  replaygain_prevent_clipping: true,
  crossfade_mode: CrossfadeMode::OFF,
  fade_out_delay_ms: 0,
  fade_out_duration_ms: 2000,
  fade_in_delay_ms: 0,
  fade_in_duration_ms: 2000,
  mix_mode: MixMode::CROSSFADE,
  # Audio output backend. nil/"" => cpal (the default device). Other specs:
  #   "stdout" (or "-"), "fifo:/path", "unix:/path" (listen),
  #   "unix-connect:/path", "tcp:host:port" (listen), "tcp-connect:host:port".
  # A listening socket blocks until a client connects. In stdout mode fd 1 IS
  # the raw S16LE stereo PCM stream, so the host must keep stdout clean
  # (e.g. pipe to `ffplay -f s16le -ar 44100 -ac 2 -`).
  output: nil,
  resume_file: nil, # an .m3u8 to auto-persist queue + position to
  resume_save_interval_ms: 0 # 0 => 5 s default
}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**opts) ⇒ Player

Create a player with configuration overrides (see DEFAULT_CONFIG keys). sample_rate: 0 means the device default. Passing resume_file: enables auto-persisting the queue + exact position to that .m3u8 file. output: selects the audio backend (nil/"" => cpal; see DEFAULT_CONFIG for the full spec-string list).



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/rockbox_ffi/player.rb', line 68

def initialize(**opts)
  c = DEFAULT_CONFIG.merge(opts)
  resume_file = c[:resume_file].nil? ? nil : c[:resume_file].to_s
  output = c[:output].nil? || c[:output].to_s.empty? ? nil : c[:output].to_s
  ptr = Lib.rb_player_new_with_output(
    output,
    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]), resume_file,
    Integer(c[:resume_save_interval_ms])
  )
  init_ptr(ptr)
end

Class Method Details

.default ⇒ Object

Player on the default device with Rockbox default settings.



57
58
59
60
61
 
# File 'lib/rockbox_ffi/player.rb', line 57

def self.default
  player = allocate
  player.send(:init_ptr, Lib.rb_player_new)
  player
end

.open(**opts) ⇒ Object

Open a Player; if a block is given, close it automatically afterwards.



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/rockbox_ffi/player.rb', line 45

def self.open(**opts)
  player = new(**opts)
  return player unless block_given?

  begin
    yield player
  ensure
    player.close
  end
end

Instance Method Details

#balance ⇒ Object

Current stereo balance, -100 (full left) to +100 (full right).



210
211
212
 
# File 'lib/rockbox_ffi/player.rb', line 210

def balance
  Lib.rb_player_balance(@ptr)
end

#clear_queue ⇒ Object

Empty the queue and stop playback (also clears any saved resume state).



139
140
141
142
 
# File 'lib/rockbox_ffi/player.rb', line 139

def clear_queue
  Lib.rb_player_clear_queue(@ptr)
  self
end

#clear_resume ⇒ Object

Delete the resume file.



419
420
421
 
# File 'lib/rockbox_ffi/player.rb', line 419

def clear_resume
  Lib.rb_player_clear_resume(@ptr)
end

#close ⇒ Object

-- lifecycle --------------------------------------------------------



86
87
88
89
90
91
92
 
# File 'lib/rockbox_ffi/player.rb', line 86

def close
  return if @ptr.nil?

  ObjectSpace.undefine_finalizer(self)
  Lib.rb_player_free(@ptr)
  @ptr = nil
end

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/rockbox_ffi/player.rb', line 94

def closed?
  @ptr.nil?
end

#dsp_settings ⇒ Object

A snapshot of the current DSP settings as a Hash with symbol keys.



387
388
389
390
391
392
 
# File 'lib/rockbox_ffi/player.rb', line 387

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

#enqueue(path) ⇒ Object

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.



113
114
115
116
 
# File 'lib/rockbox_ffi/player.rb', line 113

def enqueue(path)
  Lib.rb_player_enqueue(@ptr, path.to_s)
  self
end

#eq_enabled? ⇒ Boolean

Whether the parametric equalizer is currently enabled.

Returns:

  • (Boolean) 


264
265
266
 
# File 'lib/rockbox_ffi/player.rb', line 264

def eq_enabled?
  !Lib.rb_player_is_eq_enabled(@ptr).zero?
end

#export_m3u(path) ⇒ Object

Export the current queue to an .m3u8 (atomic). Returns true on success.



444
445
446
 
# File 'lib/rockbox_ffi/player.rb', line 444

def export_m3u(path)
  Lib.rb_player_export_m3u(@ptr, path.to_s).zero?
end

#import_m3u(path, position, index = 0) ⇒ Object

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



426
427
428
429
430
431
432
433
 
# File 'lib/rockbox_ffi/player.rb', line 426

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

#insert(paths, position, index = 0) ⇒ Object

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).



121
122
123
124
125
126
 
# File 'lib/rockbox_ffi/player.rb', line 121

def insert(paths, position, index = 0)
  Lib.rb_player_insert_json(
    @ptr, JSON.generate(Array(paths).map(&:to_s)), Integer(position), Integer(index)
  )
  self
end

#load_m3u(path) ⇒ Object

Replace the queue with a playlist file. Returns the loaded paths as an Array.



436
437
438
439
440
441
 
# File 'lib/rockbox_ffi/player.rb', line 436

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

#next ⇒ Object 



173
174
175
176
 
# File 'lib/rockbox_ffi/player.rb', line 173

def next
  Lib.rb_player_next(@ptr)
  self
end

#pause ⇒ Object 



158
159
160
161
 
# File 'lib/rockbox_ffi/player.rb', line 158

def pause
  Lib.rb_player_pause(@ptr)
  self
end

#play ⇒ Object

-- transport --------------------------------------------------------



153
154
155
156
 
# File 'lib/rockbox_ffi/player.rb', line 153

def play
  Lib.rb_player_play(@ptr)
  self
end

#previous ⇒ Object 



178
179
180
181
 
# File 'lib/rockbox_ffi/player.rb', line 178

def previous
  Lib.rb_player_previous(@ptr)
  self
end

#queue ⇒ Object

The current queue as an Array of String paths/URLs.



145
146
147
148
149
150
 
# File 'lib/rockbox_ffi/player.rb', line 145

def queue
  s = RockboxFFI.take_string(Lib.rb_player_queue_json(@ptr))
  return [] if s.nil?

  JSON.parse(s)
end

#remove(index) ⇒ Object

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.



133
134
135
136
 
# File 'lib/rockbox_ffi/player.rb', line 133

def remove(index)
  Lib.rb_player_remove(@ptr, Integer(index))
  self
end

#repeat ⇒ Object

The current repeat mode as an Integer (see RepeatMode).



252
253
254
 
# File 'lib/rockbox_ffi/player.rb', line 252

def repeat
  Lib.rb_player_repeat(@ptr)
end

#resume ⇒ Object

-- resume ----------------------------------------------------------- Restore the queue + exact position from the resume file (does NOT auto-play). Returns a Hash index:, elapsed_ms: or nil.



406
407
408
409
410
411
 
# File 'lib/rockbox_ffi/player.rb', line 406

def resume
  s = RockboxFFI.take_string(Lib.rb_player_resume(@ptr))
  return nil if s.nil?

  JSON.parse(s, symbolize_names: true)
end

#sample_rate ⇒ Object 



214
215
216
 
# File 'lib/rockbox_ffi/player.rb', line 214

def sample_rate
  Lib.rb_player_sample_rate(@ptr)
end

#save_resume ⇒ Object

Force-persist the current queue + position to the resume file now.



414
415
416
 
# File 'lib/rockbox_ffi/player.rb', line 414

def save_resume
  Lib.rb_player_save_resume(@ptr)
end

#seek_ms(ms) ⇒ Object 



188
189
190
191
 
# File 'lib/rockbox_ffi/player.rb', line 188

def seek_ms(ms)
  Lib.rb_player_seek_ms(@ptr, Integer(ms))
  self
end

#set_balance(balance) ⇒ Object

Stereo balance, -100 (full left) to +100 (full right); 0 = centre.



200
201
202
203
 
# File 'lib/rockbox_ffi/player.rb', line 200

def set_balance(balance)
  Lib.rb_player_set_balance(@ptr, Integer(balance))
  self
end

#set_bass(bass_db) ⇒ Object

Bass gain in dB.



297
298
299
300
 
# File 'lib/rockbox_ffi/player.rb', line 297

def set_bass(bass_db)
  Lib.rb_player_set_bass(@ptr, Integer(bass_db))
  self
end

#set_bass_cutoff(hz) ⇒ Object

Bass tone-control cutoff frequency in Hz.



309
310
311
312
 
# File 'lib/rockbox_ffi/player.rb', line 309

def set_bass_cutoff(hz)
  Lib.rb_player_set_bass_cutoff(@ptr, Integer(hz))
  self
end

#set_bass_enhancement(strength, precut) ⇒ Object

Bass enhancement: strength and precut (in dB).



332
333
334
335
 
# File 'lib/rockbox_ffi/player.rb', line 332

def set_bass_enhancement(strength, precut)
  Lib.rb_player_set_bass_enhancement(@ptr, Integer(strength), Integer(precut))
  self
end

#set_channel_mode(mode) ⇒ Object

Channel mode (see ChannelMode).



353
354
355
356
 
# File 'lib/rockbox_ffi/player.rb', line 353

def set_channel_mode(mode)
  Lib.rb_player_set_channel_mode(@ptr, Integer(mode))
  self
end

#set_compressor(threshold_db, makeup_gain, ratio, knee, attack_ms, release_ms) ⇒ Object

Dynamic-range compressor: threshold (dB), makeup gain, ratio, knee, attack (ms), release (ms).



366
367
368
369
370
371
372
 
# File 'lib/rockbox_ffi/player.rb', line 366

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

#set_crossfade(mode, fade_out_delay_ms: 0, fade_out_duration_ms: 2000, fade_in_delay_ms: 0, fade_in_duration_ms: 2000, mix_mode: MixMode::CROSSFADE) ⇒ Object 



218
219
220
221
222
223
224
225
226
 
# File 'lib/rockbox_ffi/player.rb', line 218

def set_crossfade(mode, fade_out_delay_ms: 0, fade_out_duration_ms: 2000,
                  fade_in_delay_ms: 0, fade_in_duration_ms: 2000,
                  mix_mode: MixMode::CROSSFADE)
  Lib.rb_player_set_crossfade(
    @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

#set_crossfeed(mode, direct_gain, cross_gain, hf_gain, hf_cutoff) ⇒ Object

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.



323
324
325
326
327
328
329
 
# File 'lib/rockbox_ffi/player.rb', line 323

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

#set_dither(enabled) ⇒ Object

Enable/disable output dithering.



375
376
377
378
 
# File 'lib/rockbox_ffi/player.rb', line 375

def set_dither(enabled)
  Lib.rb_player_set_dither(@ptr, RockboxFFI.b(enabled))
  self
end

#set_eq_band(band, cutoff_hz, q, gain_db) ⇒ Object

Configure one EQ band: band index, cutoff_hz center frequency, q factor, gain_db gain in dB.



270
271
272
273
 
# File 'lib/rockbox_ffi/player.rb', line 270

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

#set_eq_enabled(enabled) ⇒ Object

-- DSP -------------------------------------------------------------- Enable/disable the parametric equalizer.



258
259
260
261
 
# File 'lib/rockbox_ffi/player.rb', line 258

def set_eq_enabled(enabled)
  Lib.rb_player_set_eq_enabled(@ptr, RockboxFFI.b(enabled))
  self
end

#set_eq_precut(db) ⇒ Object

Global EQ pre-cut in dB.



276
277
278
279
 
# File 'lib/rockbox_ffi/player.rb', line 276

def set_eq_precut(db)
  Lib.rb_player_set_eq_precut(@ptr, Float(db))
  self
end

#set_eq_preset(preset) ⇒ Object

Apply a built-in EQ preset (see EqPreset).



282
283
284
285
 
# File 'lib/rockbox_ffi/player.rb', line 282

def set_eq_preset(preset)
  Lib.rb_player_set_eq_preset(@ptr, Integer(preset))
  self
end

#set_fatigue_reduction(strength) ⇒ Object

Listening-fatigue reduction (treble roll-off): strength.



338
339
340
341
 
# File 'lib/rockbox_ffi/player.rb', line 338

def set_fatigue_reduction(strength)
  Lib.rb_player_set_fatigue_reduction(@ptr, Integer(strength))
  self
end

#set_pitch(ratio) ⇒ Object

Pitch shift ratio.



381
382
383
384
 
# File 'lib/rockbox_ffi/player.rb', line 381

def set_pitch(ratio)
  Lib.rb_player_set_pitch(@ptr, Integer(ratio))
  self
end

#set_queue(paths) ⇒ Object

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



106
107
108
109
 
# File 'lib/rockbox_ffi/player.rb', line 106

def set_queue(paths)
  Lib.rb_player_set_queue_json(@ptr, JSON.generate(Array(paths).map(&:to_s)))
  self
end

#set_repeat(mode) ⇒ Object

Set the repeat mode (see RepeatMode: OFF=0, ONE=1, ALL=2).



246
247
248
249
 
# File 'lib/rockbox_ffi/player.rb', line 246

def set_repeat(mode)
  Lib.rb_player_set_repeat(@ptr, Integer(mode))
  self
end

#set_replaygain(mode, preamp_db, prevent_clipping) ⇒ Object

mode: see ReplayGainMode (OFF=0, TRACK=1, ALBUM=2).



229
230
231
232
 
# File 'lib/rockbox_ffi/player.rb', line 229

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

#set_shuffle(enabled) ⇒ Object

Enable/disable shuffle.



235
236
237
238
 
# File 'lib/rockbox_ffi/player.rb', line 235

def set_shuffle(enabled)
  Lib.rb_player_set_shuffle(@ptr, RockboxFFI.b(enabled))
  self
end

#set_stereo_width(percent) ⇒ Object

Stereo width as a percentage.



359
360
361
362
 
# File 'lib/rockbox_ffi/player.rb', line 359

def set_stereo_width(percent)
  Lib.rb_player_set_stereo_width(@ptr, Integer(percent))
  self
end

#set_surround(delay_ms, balance, cutoff_low_hz, cutoff_high_hz) ⇒ Object

Surround effect: delay (ms), balance, low/high cutoff frequencies (Hz).



344
345
346
347
348
349
350
 
# File 'lib/rockbox_ffi/player.rb', line 344

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

#set_tone(bass_db, treble_db, bass_cutoff_hz, treble_cutoff_hz) ⇒ Object

Bass/treble tone controls with explicit cutoff frequencies.



288
289
290
291
292
293
294
 
# File 'lib/rockbox_ffi/player.rb', line 288

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

#set_treble(treble_db) ⇒ Object

Treble gain in dB.



303
304
305
306
 
# File 'lib/rockbox_ffi/player.rb', line 303

def set_treble(treble_db)
  Lib.rb_player_set_treble(@ptr, Integer(treble_db))
  self
end

#set_treble_cutoff(hz) ⇒ Object

Treble tone-control cutoff frequency in Hz.



315
316
317
318
 
# File 'lib/rockbox_ffi/player.rb', line 315

def set_treble_cutoff(hz)
  Lib.rb_player_set_treble_cutoff(@ptr, Integer(hz))
  self
end

#set_volume(vol) ⇒ Object

-- settings ---------------------------------------------------------



194
195
196
197
 
# File 'lib/rockbox_ffi/player.rb', line 194

def set_volume(vol)
  Lib.rb_player_set_volume(@ptr, Float(vol))
  self
end

#shuffle_enabled? ⇒ Boolean

Whether shuffle is currently enabled.

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/rockbox_ffi/player.rb', line 241

def shuffle_enabled?
  !Lib.rb_player_is_shuffle_enabled(@ptr).zero?
end

#skip_to(index) ⇒ Object 



183
184
185
186
 
# File 'lib/rockbox_ffi/player.rb', line 183

def skip_to(index)
  Lib.rb_player_skip_to(@ptr, Integer(index))
  self
end

#status ⇒ Object

-- status ----------------------------------------------------------- A snapshot of the player's status as a Hash with symbol keys.



396
397
398
399
400
401
 
# File 'lib/rockbox_ffi/player.rb', line 396

def status
  s = RockboxFFI.take_string(Lib.rb_player_status_json(@ptr))
  raise "rb_player_status_json returned NULL" if s.nil?

  JSON.parse(s, symbolize_names: true)
end

#stop ⇒ Object 



168
169
170
171
 
# File 'lib/rockbox_ffi/player.rb', line 168

def stop
  Lib.rb_player_stop(@ptr)
  self
end

#toggle ⇒ Object 



163
164
165
166
 
# File 'lib/rockbox_ffi/player.rb', line 163

def toggle
  Lib.rb_player_toggle(@ptr)
  self
end

#volume ⇒ Object 



205
206
207
 
# File 'lib/rockbox_ffi/player.rb', line 205

def volume
  Lib.rb_player_volume(@ptr)
end