@spec balance(t()) :: integer()

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

@spec clear_queue(t()) :: t()

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

@spec clear_resume(t()) :: t()

Delete the resume file (forget the saved state). Returns the player handle.

@spec dsp_settings(t()) :: map()

The full DSP-chain state as an atom-keyed map.

@spec enqueue(t(), Path.t()) :: t()

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.

@spec eq_enabled?(t()) :: boolean()

Whether the equalizer is currently enabled.

@spec export_m3u(t(), Path.t()) :: :ok | {:error, :export_failed}

Export the current queue to an .m3u8 file (atomic write).

@spec import_m3u(t(), Path.t(), Rockbox.InsertPosition.t() | 0..7, non_neg_integer()) ::
  {:ok, [String.t()]} | {:error, term()}

Import an .m3u/.m3u8 playlist into the queue at position.

Returns {:ok, [path, ...]} with the imported entries, or {:error, reason}. index is only used when position is :index (7).

@spec insert(t(), [Path.t()], Rockbox.InsertPosition.t() | 0..7, non_neg_integer()) ::
  t()

Insert file paths / URLs into the queue at position.

position is a Rockbox.InsertPosition atom (or its integer code); index is only used when position is :index (7).

@spec load_m3u(t(), Path.t()) :: {:ok, [String.t()]} | {:error, term()}

Replace the queue with an .m3u/.m3u8 playlist file.

Returns {:ok, [path, ...]} with the loaded entries, or {:error, reason}.

@spec new() :: t() | nil

Create a player on the default device with default settings.

@spec new(keyword() | map()) :: t() | nil

Create a player with configuration overrides (see @default_config keys). sample_rate: 0 means the device default.

Pass resume_file: "/path/to/state.m3u8" (optionally with resume_save_interval_ms:) to enable automatic queue+position persistence; restore it later with resume/1.

@spec queue(t()) :: [String.t()]

The current queue as a list of path/URL strings.

@spec remove(t(), non_neg_integer()) :: t()

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.

@spec repeat(t()) :: Rockbox.RepeatMode.t()

The current repeat mode as a Rockbox.RepeatMode atom (:off/:one/:all).

@spec resume(t()) :: {:ok, map()} | {:error, :absent}

Restore the queue + exact position from the player's resume file (does NOT auto-play). Returns {:ok, %{tracks: [...], index: i, elapsed_ms: ms}} or {:error, :absent} when there is nothing to resume.

@spec save_resume(t()) :: t()

Persist the queue + exact position to the resume file now. Returns the player handle.

@spec set_balance(t(), integer()) :: t()

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

@spec set_bass(t(), integer()) :: t()

Set the bass tone axis in dB, leaving treble and cutoffs unchanged.

@spec set_bass_cutoff(t(), integer()) :: t()

Override the bass tone shelf cutoff in Hz (0 = native default); gains unchanged.

@spec set_bass_enhancement(t(), integer(), integer()) :: t()

Perceptual bass enhancement. strength is a percentage (0 = off); precut is in tenths of a dB (<= 0).

@spec set_channel_mode(t(), Rockbox.ChannelMode.t() | 0..6) :: t()

Channel mixing mode. Accepts a Rockbox.ChannelMode atom (e.g. :mono) or its integer code.

@spec set_compressor(
  t(),
  integer(),
  integer(),
  integer(),
  integer(),
  integer(),
  integer()
) :: t()

Dynamic-range compressor. threshold_db 0 disables it; the remaining arguments are makeup gain, ratio, knee, attack (ms) and release (ms).

@spec set_crossfeed(
  t(),
  Rockbox.CrossfeedMode.t() | 0..2,
  integer(),
  integer(),
  integer(),
  integer()
) :: t()

Headphone crossfeed. mode accepts a Rockbox.CrossfeedMode atom (:off, :meier, :custom) or its integer code.

direct_gain, cross_gain and hf_gain are in tenths of a dB (<= 0); hf_cutoff_hz is in Hz. The cross/high-frequency parameters only apply in :custom mode.

@spec set_dither(t(), boolean()) :: t()

Enable or disable output dithering + noise shaping.

@spec set_eq_band(t(), 0..10, integer(), number(), number()) :: t()

Configure one EQ band (0..10). cutoff_hz in Hz, q a Q factor, gain_db in dB.

@spec set_eq_enabled(t(), boolean()) :: t()

Enable or disable the 10-band parametric equalizer.

@spec set_eq_precut(t(), number()) :: t()

Global EQ pre-cut in dB (attenuation applied before the bands).

@spec set_eq_preset(t(), Rockbox.EqPreset.t() | 0..20) :: t()

Apply a built-in EQ preset. Accepts a Rockbox.EqPreset atom (e.g. :rock) or its integer code.

@spec set_fatigue_reduction(t(), 0..3) :: t()

Auditory fatigue reduction: 0 off, 1 weak, 2 moderate, 3 strong.

@spec set_pitch(t(), integer()) :: t()

Pitch/speed ratio (10000 = normal); pitch and tempo shift together.

@spec set_queue(t(), [Path.t()]) :: t()

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.

@spec set_repeat(t(), Rockbox.RepeatMode.t() | 0..2) :: t()

Set the repeat mode. Accepts a Rockbox.RepeatMode atom (:off, :one, :all) or its integer code (0, 1, 2).

@spec set_shuffle(t(), boolean()) :: t()

Enable or disable shuffle playback.

@spec set_stereo_width(t(), integer()) :: t()

Custom stereo width in percent (audible with channel mode :custom).

@spec set_surround(t(), integer(), integer(), integer(), integer()) :: t()

Haas surround effect: delay_ms (0 = off), balance %, and the band-split cutoffs in Hz.

@spec set_tone(t(), integer(), integer(), integer(), integer()) :: t()

Bass/treble tone controls in dB, with band-split cutoffs in Hz (0 = the native defaults).

@spec set_treble(t(), integer()) :: t()

Set the treble tone axis in dB, leaving bass and cutoffs unchanged.

@spec set_treble_cutoff(t(), integer()) :: t()

Override the treble tone shelf cutoff in Hz (0 = native default); gains unchanged.

@spec shuffle_enabled?(t()) :: boolean()

Whether shuffle playback is currently enabled.

@spec status(t()) :: map()

A snapshot of the player's status as an atom-keyed map.