rockbox_ffi_nif (rockbox_ffi_nif v1.1.0)
View SourceRaw Erlang NIF surface over the librockbox_ffi C ABI (Rockbox's metadata
parser, codec engine, DSP pipeline and queue-based player).
This is a faithful, low-level 1:1 binding — it takes and returns primitive BEAM terms and does no argument massaging:
- Strings/paths are passed and returned as UTF-8 binaries, never
charlists.
nilis returned in place of a NULL C string. - JSON-returning functions (
*_json) hand back the raw JSON binary; the caller decodes it. - Handles (
RbDsp,RbPlayer,RbDecoder) are opaque NIF resources (reference()) freed automatically by the BEAM garbage collector — there is no explicit close/free. Dropping the last reference stops playback / frees the codec. - PCM is an interleaved-stereo little-endian
int16binary. - Passing a wrong-typed argument (or a handle of the wrong kind) raises
badarg. Every function raises{nif_not_loaded, ?MODULE}if the native library failed to load.
Ergonomic wrappers with atom keyword configs, enum atoms and pipe-friendly
returns live in the language layers (Rockbox.* for Elixir, the rockbox
package for Gleam) — prefer those in application code. The functions here are
shared verbatim between both bindings.
Example — decode a file to PCM
D = rockbox_ffi_nif:decoder_open(<<"/music/song.flac">>),
Meta = rockbox_ffi_nif:decoder_metadata_json(D),
Loop = fun Loop(Acc) ->
case rockbox_ffi_nif:decoder_next_chunk(D) of
nil -> lists:reverse(Acc);
{Pcm, _Rate} -> Loop([Pcm | Acc])
end
end,
Chunks = Loop([]).Example — play a queue
P = rockbox_ffi_nif:player_new(),
rockbox_ffi_nif:player_set_queue_json(P, <<"[\\"/music/a.mp3\\",\\"/music/b.mp3\\"]">>),
rockbox_ffi_nif:player_play(P).Summary
Functions
The ABI version of the loaded native library, as an integer.
Playback position last reported by the codec, in milliseconds.
End-of-track state as {Done, Code}.
Tags and stream properties for an open decoder, as a JSON binary (same shape
as meta_read_json/1). Runs on a dirty IO scheduler.
Decode the next buffer of PCM.
Open a decoder for the local audio file at Path (a binary).
Request a seek to Ms milliseconds into the track. Returns nil.
Enable (true) or disable (false) the equalizer. Returns nil.
Flush internal DSP buffers (e.g. after a seek). Returns nil.
Create a DSP pipeline for interleaved S16LE stereo at Rate Hz.
Run interleaved-stereo S16LE PCM through the pipeline.
Set the channel-mixing mode (integer code: e.g. 0 stereo, mono, swap, …).
Returns nil.
Dynamic-range compressor. Arguments in order: threshold (Th, dB; 0
disables), makeup gain (Mk), ratio, knee, release time (Rel) and attack
time (Atk). Returns nil.
Configure one EQ band. Band is the band index (0-based), Cutoff the centre
frequency in Hz, Q the Q factor, Gain the gain in dB. Returns nil.
Set the global EQ pre-cut (attenuation applied before the bands), in dB.
Returns nil.
Set the input sample rate (Hz) the pipeline resamples from. Returns nil.
Configure ReplayGain. Mode uses the DSP-native codes (0 track, 1 album,
2 shuffle, 3 off), Noclip is clipping prevention (boolean), Preamp is
the pre-amplification in dB. Returns nil.
Supply the current track's ReplayGain values: track/album gains in plain dB
(Tg/Ag) and track/album peaks as linear amplitude (Tp/Ap). Pass the
atom nil for any absent tag. Returns nil.
Like dsp_set_replaygain_gains/5 but with native Q7.24 fixed-point integers
(the raw_* metadata fields); 0 means "not tagged". Returns nil.
Set the custom stereo width, in percent. Returns nil.
Haas surround effect: Delay in ms (0 = off), Balance in percent, and the
two band-split cutoff/effect parameters Fx1/Fx2. Returns nil.
Set the bass and treble tone axes, both in dB. Returns nil.
Set the bass and treble tone shelf cutoff frequencies, in Hz (0 = the native
defaults). Returns nil.
Whether S (a binary) looks like a playable URL rather than a local path.
Read a resume-state file at Path (a binary) without a player, returning its
JSON binary (same shape as player_resume/1) or nil. Runs on a dirty IO
scheduler.
Parse the .m3u/.m3u8 file at Path (a binary) into a JSON array of
path/URL strings (binary), or nil on failure. Runs on a dirty IO scheduler.
Write a JSON array of path/URL strings (Json) to the .m3u8 file at Path
(atomic). Returns an integer status code (0 = success). Runs on a dirty IO
scheduler.
Guess the codec label (e.g. <<"FLAC">>) from a filename's extension without
opening the file. Returns nil for an unrecognised extension.
Parse the tags and stream properties of the audio file at Path (a binary).
The current stereo balance as an integer (-100..+100).
Empty the queue and stop playback (also clears any saved resume state).
Returns nil.
Delete the resume file (forget the saved state). Returns nil. Dirty IO.
The full DSP-chain state as a JSON binary (EQ, tone, surround, compressor, ReplayGain, …).
Append one track (Path, a binary path or URL) to the queue. Returns nil.
Export the current queue to an .m3u8 file at Path (atomic write).
Import an .m3u/.m3u8 playlist at Path into the queue at Position
(insert-position code; Index used only for insert-at-index 7).
Insert tracks (a JSON array of path/URL strings) into the queue at Position
(insert-position code 0..7); Index is only used when Position is
7 (insert-at-index). Returns nil.
Whether the equalizer is currently enabled (true/false).
Whether shuffle is currently enabled (true/false).
Replace the queue with the .m3u/.m3u8 playlist at Path.
Create a player on the default output device with default settings.
Create a player with explicit configuration.
Like player_new_with_config/12 plus resume support.
Skip to the next track in the queue. Returns nil.
Pause playback. Returns nil.
Start (or resume) playback of the current queue. Returns nil.
Skip to the previous track in the queue. Returns nil.
The current queue as a JSON array of path/URL strings (binary), or nil.
Remove the track at zero-based Idx 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.
Returns nil.
The current repeat mode as an integer (0 off, 1 one, 2 all).
Restore the queue + exact position from the player's resume file (does NOT auto-play).
The player's output sample rate, in Hz.
Persist the queue + exact position to the resume file now. Returns nil. Dirty IO.
Seek to Ms milliseconds within the current track. Returns nil.
Set the stereo balance: -100 (full left) to +100 (full right), 0 centred.
Returns nil.
Set the bass tone axis in dB (treble and cutoffs unchanged). Returns nil.
Override the bass shelf cutoff in Hz (0 = native default). Returns nil.
Perceptual bass enhancement: Strength as a percentage (0 = off), Precut
in tenths of a dB (<= 0). Returns nil.
Set the channel-mixing mode by integer code (0 stereo … 6). Returns nil.
Dynamic-range compressor. Arguments in order: threshold (Th, dB; 0
disables), makeup gain (Mk), ratio, knee, attack time (Atk) and release
time (Rel). Returns nil.
Reconfigure crossfade. Mode 0 off … 5 always; FoDel/FoDur fade-out
delay/duration and FiDel/FiDur fade-in delay/duration in ms; Mix 0
crossfade, 1 mix. Returns nil.
Headphone crossfeed. Mode 0 off, 1 Meier, 2 custom. Direct, Cross
and Hf gains are in tenths of a dB (<= 0); HfCutoff in Hz. The cross /
high-frequency parameters only apply in custom mode. Returns nil.
Enable (true) or disable (false) output dithering + noise shaping. Returns nil.
Configure one EQ band: Band index (0..10), Cutoff centre frequency in Hz,
Q factor, Gain in dB. Returns nil.
Enable (true) or disable (false) the equalizer. Returns nil.
Set the global EQ pre-cut, in dB. Returns nil.
Apply a built-in EQ preset by integer code (e.g. rock, jazz, …). Returns nil.
Auditory fatigue reduction: 0 off, 1 weak, 2 moderate, 3 strong. Returns nil.
Pitch/speed ratio (10000 = normal; pitch and tempo shift together). Returns
nil.
Replace the queue from a JSON array of path/URL strings. Returns nil.
Set the repeat mode (0 off, 1 one, 2 all). Returns nil.
Reconfigure ReplayGain. Mode 0 off, 1 track, 2 album; Preamp in dB;
Clip prevents clipping (boolean). Returns nil.
Enable (true) or disable (false) shuffle playback. Returns nil.
Custom stereo width in percent (audible with the custom channel mode). Returns nil.
Haas surround effect: Delay in ms (0 = off), Balance in percent, and the
Low/High band-split cutoffs in Hz. Returns nil.
Bass/treble tone controls: Bass/Treble gains in dB, BassCut/TrebleCut
shelf cutoffs in Hz (0 = native defaults). Returns nil.
Set the treble tone axis in dB (bass and cutoffs unchanged). Returns nil.
Override the treble shelf cutoff in Hz (0 = native default). Returns nil.
Set the output volume (Vol, a float; 1.0 = unity gain). Returns nil.
Jump to the queue entry at zero-based Idx and play it. Returns nil.
A snapshot of the player's status as a JSON binary (playback state, current track, elapsed/total ms, volume, …).
Stop playback and reset the play position. Returns nil.
Toggle between play and pause. Returns nil.
The current output volume as a float.
Functions
The ABI version of the loaded native library, as an integer.
Bump-on-break: a mismatch against the version a binding was built for means
the .so and the Erlang surface have drifted.
1 = rockbox_ffi_nif:abi_version().Playback position last reported by the codec, in milliseconds.
Ms = rockbox_ffi_nif:decoder_elapsed_ms(D).End-of-track state as {Done, Code}.
Done is true once the track has finished. Code is the exit status
(0 = clean end, negative = codec error) and is only meaningful when Done
is true.
{true, 0} = rockbox_ffi_nif:decoder_finished(D).Tags and stream properties for an open decoder, as a JSON binary (same shape
as meta_read_json/1). Runs on a dirty IO scheduler.
Json = rockbox_ffi_nif:decoder_metadata_json(D).Decode the next buffer of PCM.
Returns {Pcm, SampleRate} where Pcm is an interleaved-stereo little-endian
int16 binary and SampleRate is in Hz, or nil at end of track (or after a
codec error — check decoder_finished/1). Runs on a dirty CPU scheduler.
case rockbox_ffi_nif:decoder_next_chunk(D) of
{Pcm, Rate} -> handle(Pcm, Rate);
nil -> eof
end.Open a decoder for the local audio file at Path (a binary).
Returns an opaque decoder handle, or nil if the file cannot be opened or no
codec recognises it. The codec engine is process-wide: only one decoder can
decode at a time — opening a second blocks until the first handle is
garbage-collected. Runs on a dirty CPU scheduler.
D = rockbox_ffi_nif:decoder_open(<<"/music/song.mp3">>).Request a seek to Ms milliseconds into the track. Returns nil.
rockbox_ffi_nif:decoder_seek_ms(D, 30000).Enable (true) or disable (false) the equalizer. Returns nil.
Flush internal DSP buffers (e.g. after a seek). Returns nil.
Create a DSP pipeline for interleaved S16LE stereo at Rate Hz.
Returns an opaque DSP handle, or nil on failure. The DSP wraps a
process-wide singleton, so only one handle should be alive at a time.
Dsp = rockbox_ffi_nif:dsp_new(44100).Run interleaved-stereo S16LE PCM through the pipeline.
Bin is a little-endian int16 binary; the result is the processed PCM as a
binary (possibly empty, and not necessarily the same length as the input).
Runs on a dirty CPU scheduler.
Out = rockbox_ffi_nif:dsp_process(Dsp, In).Set the channel-mixing mode (integer code: e.g. 0 stereo, mono, swap, …).
Returns nil.
Dynamic-range compressor. Arguments in order: threshold (Th, dB; 0
disables), makeup gain (Mk), ratio, knee, release time (Rel) and attack
time (Atk). Returns nil.
Note the argument order (release before attack) differs from
player_set_compressor/7.
Configure one EQ band. Band is the band index (0-based), Cutoff the centre
frequency in Hz, Q the Q factor, Gain the gain in dB. Returns nil.
rockbox_ffi_nif:dsp_set_eq_band(Dsp, 4, 1000, 1.0, 6.0).Set the global EQ pre-cut (attenuation applied before the bands), in dB.
Returns nil.
Set the input sample rate (Hz) the pipeline resamples from. Returns nil.
Configure ReplayGain. Mode uses the DSP-native codes (0 track, 1 album,
2 shuffle, 3 off), Noclip is clipping prevention (boolean), Preamp is
the pre-amplification in dB. Returns nil.
Supply the current track's ReplayGain values: track/album gains in plain dB
(Tg/Ag) and track/album peaks as linear amplitude (Tp/Ap). Pass the
atom nil for any absent tag. Returns nil.
Like dsp_set_replaygain_gains/5 but with native Q7.24 fixed-point integers
(the raw_* metadata fields); 0 means "not tagged". Returns nil.
Set the custom stereo width, in percent. Returns nil.
Haas surround effect: Delay in ms (0 = off), Balance in percent, and the
two band-split cutoff/effect parameters Fx1/Fx2. Returns nil.
Set the bass and treble tone axes, both in dB. Returns nil.
rockbox_ffi_nif:dsp_set_tone(Dsp, 3, -2).Set the bass and treble tone shelf cutoff frequencies, in Hz (0 = the native
defaults). Returns nil.
Whether S (a binary) looks like a playable URL rather than a local path.
true = rockbox_ffi_nif:is_url(<<"http://host/stream.mp3">>),
false = rockbox_ffi_nif:is_url(<<"/music/song.mp3">>).Read a resume-state file at Path (a binary) without a player, returning its
JSON binary (same shape as player_resume/1) or nil. Runs on a dirty IO
scheduler.
Parse the .m3u/.m3u8 file at Path (a binary) into a JSON array of
path/URL strings (binary), or nil on failure. Runs on a dirty IO scheduler.
Write a JSON array of path/URL strings (Json) to the .m3u8 file at Path
(atomic). Returns an integer status code (0 = success). Runs on a dirty IO
scheduler.
Guess the codec label (e.g. <<"FLAC">>) from a filename's extension without
opening the file. Returns nil for an unrecognised extension.
<<"FLAC">> = rockbox_ffi_nif:meta_probe(<<"track.flac">>),
nil = rockbox_ffi_nif:meta_probe(<<"notes.txt">>).Parse the tags and stream properties of the audio file at Path (a binary).
Returns a JSON binary — an object with keys such as codec, title,
artist, duration_ms, sample_rate and a nested replaygain object — or
nil if the file cannot be parsed. Runs on a dirty IO scheduler.
Json = rockbox_ffi_nif:meta_read_json(<<"/music/song.flac">>),
#{<<"title">> := Title} = json:decode(Json).The current stereo balance as an integer (-100..+100).
Empty the queue and stop playback (also clears any saved resume state).
Returns nil.
Delete the resume file (forget the saved state). Returns nil. Dirty IO.
The full DSP-chain state as a JSON binary (EQ, tone, surround, compressor, ReplayGain, …).
Append one track (Path, a binary path or URL) to the queue. Returns nil.
Export the current queue to an .m3u8 file at Path (atomic write).
Returns an integer status code (0 = success, non-zero = failure). Runs on a
dirty IO scheduler.
Import an .m3u/.m3u8 playlist at Path into the queue at Position
(insert-position code; Index used only for insert-at-index 7).
Returns a JSON array of the imported path strings (binary), or nil on
failure. Runs on a dirty IO scheduler.
Insert tracks (a JSON array of path/URL strings) into the queue at Position
(insert-position code 0..7); Index is only used when Position is
7 (insert-at-index). Returns nil.
Whether the equalizer is currently enabled (true/false).
Whether shuffle is currently enabled (true/false).
Replace the queue with the .m3u/.m3u8 playlist at Path.
Returns a JSON array of the loaded path strings (binary), or nil on failure.
Runs on a dirty IO scheduler.
Create a player on the default output device with default settings.
Returns an opaque player handle, or nil if no output device is available. A
player owns a live audio device and a background engine thread; dropping the
last reference stops playback. Runs on a dirty CPU scheduler.
P = rockbox_ffi_nif:player_new().Create a player with explicit configuration.
Arguments: Rate (output sample rate in Hz; 0 = device default), Buf
(buffer length in seconds), Vol (initial volume, 1.0 = unity), RgMode
(player ReplayGain mode: 0 off, 1 track, 2 album), RgPre (ReplayGain
preamp in dB), RgClip (prevent clipping, boolean), Xf (crossfade mode:
0 off … 5 always), fade-out delay/duration and fade-in delay/duration in
ms (FoDel/FoDur/FiDel/FiDur), and Mix (0 crossfade, 1 mix).
Returns a player handle or nil. Runs on a dirty CPU scheduler.
Like player_new_with_config/12 plus resume support.
ResumeFile is a binary .m3u8 path to auto-persist the queue + exact
position to (or the atom nil for none), and ResumeInt the save interval in
ms (0 = the native default). Restore later with player_resume/1. Returns a
player handle or nil. Runs on a dirty CPU scheduler.
Skip to the next track in the queue. Returns nil.
Pause playback. Returns nil.
Start (or resume) playback of the current queue. Returns nil.
Skip to the previous track in the queue. Returns nil.
The current queue as a JSON array of path/URL strings (binary), or nil.
Remove the track at zero-based Idx 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.
Returns nil.
The current repeat mode as an integer (0 off, 1 one, 2 all).
Restore the queue + exact position from the player's resume file (does NOT auto-play).
Returns a JSON binary ({"tracks": [...], "index": i, "elapsed_ms": ms}), or
nil when there is nothing to resume. Runs on a dirty IO scheduler.
The player's output sample rate, in Hz.
Persist the queue + exact position to the resume file now. Returns nil. Dirty IO.
Seek to Ms milliseconds within the current track. Returns nil.
Set the stereo balance: -100 (full left) to +100 (full right), 0 centred.
Returns nil.
Set the bass tone axis in dB (treble and cutoffs unchanged). Returns nil.
Override the bass shelf cutoff in Hz (0 = native default). Returns nil.
Perceptual bass enhancement: Strength as a percentage (0 = off), Precut
in tenths of a dB (<= 0). Returns nil.
Set the channel-mixing mode by integer code (0 stereo … 6). Returns nil.
Dynamic-range compressor. Arguments in order: threshold (Th, dB; 0
disables), makeup gain (Mk), ratio, knee, attack time (Atk) and release
time (Rel). Returns nil.
Note the argument order (attack before release) differs from
dsp_set_compressor/7.
Reconfigure crossfade. Mode 0 off … 5 always; FoDel/FoDur fade-out
delay/duration and FiDel/FiDur fade-in delay/duration in ms; Mix 0
crossfade, 1 mix. Returns nil.
Headphone crossfeed. Mode 0 off, 1 Meier, 2 custom. Direct, Cross
and Hf gains are in tenths of a dB (<= 0); HfCutoff in Hz. The cross /
high-frequency parameters only apply in custom mode. Returns nil.
Enable (true) or disable (false) output dithering + noise shaping. Returns nil.
Configure one EQ band: Band index (0..10), Cutoff centre frequency in Hz,
Q factor, Gain in dB. Returns nil.
rockbox_ffi_nif:player_set_eq_band(P, 5, 2000, 1.0, -3.0).Enable (true) or disable (false) the equalizer. Returns nil.
Set the global EQ pre-cut, in dB. Returns nil.
Apply a built-in EQ preset by integer code (e.g. rock, jazz, …). Returns nil.
Auditory fatigue reduction: 0 off, 1 weak, 2 moderate, 3 strong. Returns nil.
Pitch/speed ratio (10000 = normal; pitch and tempo shift together). Returns
nil.
Replace the queue from a JSON array of path/URL strings. Returns nil.
Each entry may be a local file path, an http(s):// URL to a finite remote
file, or a live streaming / radio URL.
rockbox_ffi_nif:player_set_queue_json(P, <<"[\\"/music/a.mp3\\"]">>).Set the repeat mode (0 off, 1 one, 2 all). Returns nil.
Reconfigure ReplayGain. Mode 0 off, 1 track, 2 album; Preamp in dB;
Clip prevents clipping (boolean). Returns nil.
Enable (true) or disable (false) shuffle playback. Returns nil.
Custom stereo width in percent (audible with the custom channel mode). Returns nil.
Haas surround effect: Delay in ms (0 = off), Balance in percent, and the
Low/High band-split cutoffs in Hz. Returns nil.
Bass/treble tone controls: Bass/Treble gains in dB, BassCut/TrebleCut
shelf cutoffs in Hz (0 = native defaults). Returns nil.
Set the treble tone axis in dB (bass and cutoffs unchanged). Returns nil.
Override the treble shelf cutoff in Hz (0 = native default). Returns nil.
Set the output volume (Vol, a float; 1.0 = unity gain). Returns nil.
Jump to the queue entry at zero-based Idx and play it. Returns nil.
A snapshot of the player's status as a JSON binary (playback state, current track, elapsed/total ms, volume, …).
Json = rockbox_ffi_nif:player_status_json(P).Stop playback and reset the play position. Returns nil.
Toggle between play and pause. Returns nil.
The current output volume as a float.