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.

Types

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

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

M3uEntry(
  path: String,
  duration_ms: option.Option(Int),
  title: option.Option(String),
)

Player

</>

Opaque player handle (a NIF resource).

pub type Player

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,
  )
}

Constructors

Status(
  state: String,
  index: option.Option(Int),
  position_ms: Int,
  duration_ms: Int,
  queue_len: Int,
)

Values

clear_resume

</>

pub fn clear_resume(player: Player) -> Nil

Delete the resume file (forget the saved state).

default_config

</>

pub fn default_config() -> Config

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

enqueue

</>

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

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,
) -> Nil

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

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.

</>

pub fn next(player: Player) -> Nil

pause

</>

pub fn pause(player: Player) -> Nil

play

</>

pub fn play(player: Player) -> Nil

</>

pub fn previous(player: Player) -> Nil

queue

</>

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

The current queue as a list of paths / URLs.

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

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

seek_ms

</>

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

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,
) -> Nil

set_queue

</>

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

Replace the queue with a list of file paths (or http(s):// URLs).

set_replaygain

</>

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

set_volume

</>

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

skip_to

</>

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

status

</>

pub fn status(player: Player) -> Status

A snapshot of the player’s status.

stop

</>

pub fn stop(player: Player) -> Nil

toggle

</>

pub fn toggle(player: Player) -> Nil

volume

</>

pub fn volume(player: Player) -> Float

with_config

</>

pub fn with_config(c: Config) -> Player

Create a player with explicit configuration (including resume).