rockbox_ffi - v1.5.0

rockbox/player

Queue-based player with native ReplayGain and Rockbox crossfade.

A Player owns a live audio output device and a background engine thread, so it only works where an output device exists. The handle is a NIF resource, freed by the BEAM garbage collector (which stops playback).

ReplayGain mode here uses the player values: 0 off, 1 track, 2 album. Crossfade mode: 0 off, 1 auto-skip, 2 manual-skip, 3 shuffle, 4 shuffle-or-manual, 5 always. Mix mode: 0 crossfade, 1 mix.

Mutating functions return the Player, so they can be piped:

p
|> player.set_queue(tracks)
|> player.set_shuffle(True)
|> player.set_repeat(player.All)
|> player.play

Types

BassEnhancement

</>

The bass-enhancement section of dsp_settings.

pub type BassEnhancement {
  BassEnhancement(strength: Int, precut: Int)
}

Constructors 

  • BassEnhancement(strength: Int, precut: Int)

ChannelMode

</>

Channel-mixing mode (set_channel_mode). Values map to the ABI’s integer mode ids 0..6.

pub type ChannelMode {
  Stereo
  Mono
  Custom
  MonoLeft
  MonoRight
  Karaoke
  Swap
}

Constructors 

  • Stereo
  • Mono
  • Custom
  • MonoLeft
  • MonoRight
  • Karaoke
  • Swap

Compressor

</>

The compressor section of dsp_settings.

pub type Compressor {
  Compressor(
    threshold_db: Int,
    makeup_gain: Int,
    ratio: Int,
    knee: Int,
    attack_ms: Int,
    release_ms: Int,
  )
}

Constructors 

  • Compressor(
  threshold_db: Int,
  makeup_gain: Int,
  ratio: Int,
  knee: Int,
  attack_ms: Int,
  release_ms: Int,
)

Config

</>

Player configuration. sample_rate: 0 means the output device default.

resume_file (an .m3u8 path) enables auto-persistence of the queue and exact position: None (the default) disables it. resume_save_interval_ms of 0 uses Rockbox’s 5 s default.

pub type Config {
  Config(
    sample_rate: Int,
    buffer_seconds: Float,
    volume: Float,
    replaygain_mode: Int,
    replaygain_preamp_db: Float,
    replaygain_prevent_clipping: Bool,
    crossfade_mode: Int,
    fade_out_delay_ms: Int,
    fade_out_duration_ms: Int,
    fade_in_delay_ms: Int,
    fade_in_duration_ms: Int,
    mix_mode: Int,
    resume_file: option.Option(String),
    resume_save_interval_ms: Int,
  )
}

Constructors 

  • Config(
  sample_rate: Int,
  buffer_seconds: Float,
  volume: Float,
  replaygain_mode: Int,
  replaygain_preamp_db: Float,
  replaygain_prevent_clipping: Bool,
  crossfade_mode: Int,
  fade_out_delay_ms: Int,
  fade_out_duration_ms: Int,
  fade_in_delay_ms: Int,
  fade_in_duration_ms: Int,
  mix_mode: Int,
  resume_file: option.Option(String),
  resume_save_interval_ms: Int,
)

Crossfeed

</>

The crossfeed (headphone) section of dsp_settings.

pub type Crossfeed {
  Crossfeed(
    mode: String,
    direct_gain: Int,
    cross_gain: Int,
    high_freq_gain: Int,
    high_freq_cutoff: Int,
  )
}

Constructors 

  • Crossfeed(
  mode: String,
  direct_gain: Int,
  cross_gain: Int,
  high_freq_gain: Int,
  high_freq_cutoff: Int,
)

CrossfeedMode

</>

Crossfeed mode (set_crossfeed). Values map to the ABI’s integer mode ids: 0 off, 1 Meier, 2 custom.

pub type CrossfeedMode {
  CrossfeedOff
  Meier
  CrossfeedCustom
}

Constructors 

  • CrossfeedOff
  • Meier
  • CrossfeedCustom

DspSettings

</>

The whole DSP chain state, as returned by dsp_settings.

pub type DspSettings {
  DspSettings(
    equalizer: Equalizer,
    tone: Tone,
    surround: Surround,
    channel_mode: String,
    stereo_width: Int,
    compressor: Compressor,
    dither: Bool,
    pitch: Int,
    crossfeed: Crossfeed,
    bass_enhancement: BassEnhancement,
    fatigue_reduction: Int,
  )
}

Constructors

EqBand

</>

One EQ band as reported by dsp_settings.

pub type EqBand {
  EqBand(cutoff_hz: Int, q: Float, gain_db: Float)
}

Constructors 

  • EqBand(cutoff_hz: Int, q: Float, gain_db: Float)

EqPreset

</>

A built-in graphic-EQ preset (set_eq_preset). Values map to the ABI’s integer preset ids 0..20.

pub type EqPreset {
  Flat
  Acoustic
  BassBoost
  BassReducer
  Classical
  Dance
  Deep
  Electronic
  HipHop
  Jazz
  Latin
  Loudness
  Lounge
  Piano
  Pop
  RnB
  Rock
  SmallSpeakers
  TrebleBoost
  TrebleReducer
  VocalBoost
}

Constructors 

  • Flat
  • Acoustic
  • BassBoost
  • BassReducer
  • Classical
  • Dance
  • Deep
  • Electronic
  • HipHop
  • Jazz
  • Latin
  • Loudness
  • Lounge
  • Piano
  • Pop
  • RnB
  • Rock
  • SmallSpeakers
  • TrebleBoost
  • TrebleReducer
  • VocalBoost

Equalizer

</>

The graphic EQ section of dsp_settings.

pub type Equalizer {
  Equalizer(enabled: Bool, precut_db: Float, bands: List(EqBand))
}

Constructors 

  • Equalizer(enabled: Bool, precut_db: Float, bands: List(EqBand))

InsertPosition

</>

Where an insert / import_m3u places its tracks relative to the queue.

  • Prepend — before everything.
  • Insert — as a block right after the current track.
  • InsertNext — immediately next (single-track semantics).
  • InsertLast — at the end.
  • InsertShuffled — shuffled into the queue.
  • InsertLastShuffled — appended then shuffled among the new tail.
  • Replace — clear the queue first.
  • Index(i) — at explicit index i.
pub type InsertPosition {
  Prepend
  Insert
  InsertNext
  InsertLast
  InsertShuffled
  InsertLastShuffled
  Replace
  Index(Int)
}

Constructors 

  • Prepend
  • Insert
  • InsertNext
  • InsertLast
  • InsertShuffled
  • InsertLastShuffled
  • Replace
  • Index(Int)

M3uEntry

</>

One entry parsed from a playlist file by m3u_read.

pub type M3uEntry {
  M3uEntry(
    path: String,
    duration_ms: option.Option(Int),
    title: option.Option(String),
  )
}

Constructors

Player

</>

Opaque player handle (a NIF resource).

pub type Player

RepeatMode

</>

Repeat mode (set_repeat / repeat). Values map to the ABI’s integer mode ids: 0 off, 1 one, 2 all.

pub type RepeatMode {
  Off
  One
  All
}

Constructors 

  • Off
  • One
  • All

ResumeState

</>

Restored playback state as returned by resume / load_resume.

pub type ResumeState {
  ResumeState(tracks: List(String), index: Int, elapsed_ms: Int)
}

Constructors 

  • ResumeState(tracks: List(String), index: Int, elapsed_ms: Int)

Status

</>

A snapshot of the player’s status.

pub type Status {
  Status(
    state: String,
    index: option.Option(Int),
    position_ms: Int,
    duration_ms: Int,
    queue_len: Int,
    shuffle: Bool,
    repeat: String,
  )
}

Constructors 

  • Status(
  state: String,
  index: option.Option(Int),
  position_ms: Int,
  duration_ms: Int,
  queue_len: Int,
  shuffle: Bool,
  repeat: String,
)

Surround

</>

The surround section of dsp_settings.

pub type Surround {
  Surround(
    delay_ms: Int,
    balance: Int,
    cutoff_low_hz: Int,
    cutoff_high_hz: Int,
  )
}

Constructors 

  • Surround(
  delay_ms: Int,
  balance: Int,
  cutoff_low_hz: Int,
  cutoff_high_hz: Int,
)

Tone

</>

The bass/treble tone controls of dsp_settings.

pub type Tone {
  Tone(
    bass_db: Int,
    treble_db: Int,
    bass_cutoff_hz: Int,
    treble_cutoff_hz: Int,
  )
}

Constructors 

  • Tone(
  bass_db: Int,
  treble_db: Int,
  bass_cutoff_hz: Int,
  treble_cutoff_hz: Int,
)

Values

balance

</> 
pub fn balance(player: Player) -> Int

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

channel_mode_to_int

</> 
pub fn channel_mode_to_int(mode: ChannelMode) -> Int

Encode a ChannelMode as the ABI’s integer id (0..6).

clear_queue

</> 
pub fn clear_queue(player: Player) -> Player

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

clear_resume

</> 
pub fn clear_resume(player: Player) -> Player

Delete the resume file (forget the saved state).

crossfeed_mode_to_int

</> 
pub fn crossfeed_mode_to_int(mode: CrossfeedMode) -> Int

Encode a CrossfeedMode as the ABI’s integer id (0/1/2).

default_config

</> 
pub fn default_config() -> Config

Rockbox-default configuration (device sample rate, no crossfade, ReplayGain off, full volume, resume disabled).

dsp_settings

</> 
pub fn dsp_settings(player: Player) -> DspSettings

Read back the whole DSP chain state.

enqueue

</> 
pub fn enqueue(player: Player, path: String) -> Player

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.

eq_preset_to_int

</> 
pub fn eq_preset_to_int(preset: EqPreset) -> Int

Encode an EqPreset as the ABI’s integer id (0..20).

export_m3u

</> 
pub fn export_m3u(
  player: Player,
  path: String,
) -> Result(Nil, Nil)

Export the current queue to an .m3u8 (atomic). Ok(Nil) / Error(Nil).

import_m3u

</> 
pub fn import_m3u(
  player: Player,
  path: String,
  position: InsertPosition,
) -> List(String)

Import a playlist file into the queue at position; returns the imported paths.

insert

</> 
pub fn insert(
  player: Player,
  paths: List(String),
  position: InsertPosition,
) -> Player

Insert a list of paths / URLs into the queue at position.

is_eq_enabled

</> 
pub fn is_eq_enabled(player: Player) -> Bool

Whether the graphic equalizer is currently enabled.

is_shuffle_enabled

</> 
pub fn is_shuffle_enabled(player: Player) -> Bool

Whether shuffle playback is currently enabled.

is_url

</> 
pub fn is_url(s: String) -> Bool

Whether a string looks like an http(s):// URL.

load_m3u

</> 
pub fn load_m3u(player: Player, path: String) -> List(String)

Replace the queue with a playlist file; returns the loaded paths.

load_resume

</> 
pub fn load_resume(path: String) -> option.Option(ResumeState)

Peek at a resume file without a player. None if it is missing/unreadable.

m3u_read

</> 
pub fn m3u_read(path: String) -> Result(List(M3uEntry), Nil)

Parse a playlist file into its entries. Error(Nil) if it cannot be read.

m3u_write

</> 
pub fn m3u_write(
  path: String,
  paths: List(String),
) -> Result(Nil, Nil)

Write a list of paths as an .m3u8. Ok(Nil) / Error(Nil).

new

</> 
pub fn new() -> Player

Create a player on the default device with default settings.

next

</> 
pub fn next(player: Player) -> Player

Skip to the next track.

pause

</> 
pub fn pause(player: Player) -> Player

Pause playback.

play

</> 
pub fn play(player: Player) -> Player

Start (or resume) playback.

previous

</> 
pub fn previous(player: Player) -> Player

Skip to the previous track.

queue

</> 
pub fn queue(player: Player) -> List(String)

The current queue as a list of paths / URLs.

remove

</> 
pub fn remove(player: Player, index: Int) -> Player

Remove the track at zero-based index 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.

repeat

</> 
pub fn repeat(player: Player) -> RepeatMode

The current repeat mode (off / one / all).

repeat_mode_from_int

</> 
pub fn repeat_mode_from_int(value: Int) -> RepeatMode

Decode the ABI’s integer id (0/1/2) into a RepeatMode (unknown → Off).

repeat_mode_to_int

</> 
pub fn repeat_mode_to_int(mode: RepeatMode) -> Int

Encode a RepeatMode as the ABI’s integer id (0/1/2).

resume

</> 
pub fn resume(player: Player) -> option.Option(ResumeState)

Restore the queue and exact position from the configured resume file (does NOT auto-play). None if there is nothing to resume.

sample_rate

</> 
pub fn sample_rate(player: Player) -> Int

save_resume

</> 
pub fn save_resume(player: Player) -> Player

Persist the current queue + position to the resume file right now.

seek_ms

</> 
pub fn seek_ms(player: Player, ms: Int) -> Player

Seek to ms within the current track.

set_balance

</> 
pub fn set_balance(player: Player, balance: Int) -> Player

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

set_bass

</> 
pub fn set_bass(player: Player, bass_db: Int) -> Player

Set the bass tone gain, in dB.

set_bass_cutoff

</> 
pub fn set_bass_cutoff(player: Player, hz: Int) -> Player

Set the bass tone cutoff frequency, in Hz.

set_bass_enhancement

</> 
pub fn set_bass_enhancement(
  player: Player,
  strength: Int,
  precut: Int,
) -> Player

Configure bass enhancement (strength and precut).

set_channel_mode

</> 
pub fn set_channel_mode(
  player: Player,
  mode: ChannelMode,
) -> Player

Set the channel-mixing mode.

set_compressor

</> 
pub fn set_compressor(
  player: Player,
  threshold_db: Int,
  makeup_gain: Int,
  ratio: Int,
  knee: Int,
  attack_ms: Int,
  release_ms: Int,
) -> Player

Configure the dynamic-range compressor.

set_crossfade

</> 
pub fn set_crossfade(
  player: Player,
  mode: Int,
  fade_out_delay_ms: Int,
  fade_out_duration_ms: Int,
  fade_in_delay_ms: Int,
  fade_in_duration_ms: Int,
  mix_mode: Int,
) -> Player

Configure crossfade behaviour.

set_crossfeed

</> 
pub fn set_crossfeed(
  player: Player,
  mode: CrossfeedMode,
  direct_gain: Int,
  cross_gain: Int,
  high_freq_gain: Int,
  high_freq_cutoff: Int,
) -> Player

Configure the crossfeed (headphone) effect. direct_gain, cross_gain and high_freq_gain are gains; high_freq_cutoff is in Hz. The gain values only take effect in CrossfeedCustom mode.

set_dither

</> 
pub fn set_dither(player: Player, enabled: Bool) -> Player

Enable or disable output dithering.

set_eq_band

</> 
pub fn set_eq_band(
  player: Player,
  band: Int,
  cutoff_hz: Int,
  q: Float,
  gain_db: Float,
) -> Player

Configure one EQ band: cutoff_hz in Hz, q factor, gain_db in dB.

set_eq_enabled

</> 
pub fn set_eq_enabled(player: Player, enabled: Bool) -> Player

Enable or disable the graphic equalizer.

set_eq_precut

</> 
pub fn set_eq_precut(player: Player, db: Float) -> Player

Set the EQ pre-cut (headroom), in dB.

set_eq_preset

</> 
pub fn set_eq_preset(player: Player, preset: EqPreset) -> Player

Apply a built-in EQ preset.

set_fatigue_reduction

</> 
pub fn set_fatigue_reduction(
  player: Player,
  strength: Int,
) -> Player

Set the listening-fatigue reduction strength.

set_pitch

</> 
pub fn set_pitch(player: Player, ratio: Int) -> Player

Set the pitch ratio (Rockbox’s fixed-point pitch value).

set_queue

</> 
pub fn set_queue(player: Player, paths: List(String)) -> Player

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.

set_repeat

</> 
pub fn set_repeat(player: Player, mode: RepeatMode) -> Player

Set the repeat mode (off / one / all).

set_replaygain

</> 
pub fn set_replaygain(
  player: Player,
  mode: Int,
  preamp_db: Float,
  prevent_clipping: Bool,
) -> Player

Configure ReplayGain (mode, pre-amp in dB, clipping prevention).

set_shuffle

</> 
pub fn set_shuffle(player: Player, enabled: Bool) -> Player

Enable or disable shuffle playback.

set_stereo_width

</> 
pub fn set_stereo_width(player: Player, percent: Int) -> Player

Set the stereo width, as a percentage.

set_surround

</> 
pub fn set_surround(
  player: Player,
  delay_ms: Int,
  balance: Int,
  cutoff_low_hz: Int,
  cutoff_high_hz: Int,
) -> Player

Configure the surround effect (delay in ms, balance, cutoffs in Hz).

set_tone

</> 
pub fn set_tone(
  player: Player,
  bass_db: Int,
  treble_db: Int,
  bass_cutoff_hz: Int,
  treble_cutoff_hz: Int,
) -> Player

Set the bass/treble tone controls (gains in dB, cutoffs in Hz).

set_treble

</> 
pub fn set_treble(player: Player, treble_db: Int) -> Player

Set the treble tone gain, in dB.

set_treble_cutoff

</> 
pub fn set_treble_cutoff(player: Player, hz: Int) -> Player

Set the treble tone cutoff frequency, in Hz.

set_volume

</> 
pub fn set_volume(player: Player, volume: Float) -> Player

Set the output volume (0.0..1.0).

skip_to

</> 
pub fn skip_to(player: Player, index: Int) -> Player

Skip to the track at index in the queue.

status

</> 
pub fn status(player: Player) -> Status

A snapshot of the player’s status.

stop

</> 
pub fn stop(player: Player) -> Player

Stop playback.

toggle

</> 
pub fn toggle(player: Player) -> Player

Toggle between play and pause.

volume

</> 
pub fn volume(player: Player) -> Float

with_config

</> 
pub fn with_config(c: Config) -> Player

Create a player with explicit configuration (including resume).

✨ Search Document