Playback API

Methods of the playback namespace.

Playback position and timing

Latency compensation & stepped advancement: playback.getPosition, playback:timeHighRes, and playback:stateChanged report positions that already account for output-buffer and DSP latency. Do not subtract latency again when synchronizing lyrics or media. Audio engine readings advance in discrete steps (typically updating every 10–30 ms), independent of the ~100 ms broadcast interval of playback:timeHighRes.
Sampling timestamps & extrapolation: hostTime records the host system timestamp when the position was sampled (Unix epoch milliseconds, on the same clock as Date.now()). Linear extrapolation can estimate inter-sample positions, but cannot eliminate transient stalls or discontinuities during startup, seeking, pause-resume, or crossfading. For video synchronization, use the SDK's MediaElementFollower.
Position event semantics: playback:time provides a coarse display update (~once per second) without sample timestamps. playback:seeked.position and playback.setPosition.actualPosition represent the seek target; the immediately sampled newPosition may still contain the old position.

playback

playback.getCurrentTrack

Report the track now loaded, playing or paused. Always succeeds; found says whether there is one.

This method takes no parameters.

Returns

Field	Type	Description
`found`	`boolean`	Whether a track is loaded.
`track`	Track	The loaded track; absent when `found` is `false`.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getCurrentTrack');

playback.getCurrentTrackIndex

Locate the playing track in its playlist. Known only when playback started from a playlist item; a track played from elsewhere has no location even while a playing playlist exists. The location is also lost once the playing row is removed from the playlist it started from, the playlist included, while the track keeps playing; and there is none while stopped.

Parameter	Type	Required	Description
`includeTrackInfo`	`boolean`	No	`true` adds the track row at that location. Default: `false`.

Returns

Field	Type	Description
`found`	`boolean`	Whether the playing track has a playlist location.
`playlist`	`integer \| null`	Playlist index; `null` when there is no location.
`playlistGuid`	`string \| null`	GUID of that playlist, as `playlistGuid` takes it; `null` when there is no location.
`index`	`integer \| null`	Row in that playlist; `null` when there is no location.
`track`	Track	The track at that location; only with `includeTrackInfo`, and only when the row still exists.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playback.getCurrentTrackIndex');
if (res.success === false) throw new Error(res.error);
const { playlist, index } = res;

playback.getPlaybackOrder

Report the active playback order as its index and its name.

This method takes no parameters.

Returns

Field	Type	Description
`order`	`integer`	Index of the active order, `0` to `6`.
`orderName`	`"default" \| "repeat-playlist" \| "repeat-track" \| "random" \| "shuffle-tracks" \| "shuffle-albums" \| "shuffle-folders"`	Name of the active order.
`name`	`"default" \| "repeat-playlist" \| "repeat-track" \| "random" \| "shuffle-tracks" \| "shuffle-albums" \| "shuffle-folders"`	The same as `orderName`.
`orderIndex`	`integer`	The same as `order`.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getPlaybackOrder');

playback.getPlayingPlaylist

Report the playlist playback was last started from. foobar2000 keeps the pointer after playback stops, so a stopped instance that has played before still reports one.

This method takes no parameters.

Returns

Field	Type	Description
`found`	`boolean`	Whether a playing playlist is known.
`playlist`	`integer \| null`	Playlist index; `null` when none is known.
`playlistGuid`	`string \| null`	GUID of that playlist, as `playlistGuid` takes it; `null` when none is known.
`name`	`string`	Name of that playlist; absent when none is known.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getPlayingPlaylist');

playback.getPosition

Report the playback position together with the length and identity of the track it is in. Everything is zero or empty when nothing is playing.

This method takes no parameters.

Returns

Field	Type	Description
`position`	`number`	Audible position in seconds from the start of the track, already adjusted for output-buffer and DSP latency; do not subtract that latency again. The host advances this reading in steps, typically 10–30 ms apart. It can briefly stall or jump after starting, seeking or resuming, and during crossfades; it is not a sample-accurate clock.
`duration`	`number`	Length of the track in seconds; `0` when nothing is playing or the length is unknown.
`subsong`	`integer`	Subsong identifier of the track; `0` for a whole file.
`path`	`string`	Path as foobar2000 stores it, without a subsong suffix; empty when nothing is playing.
`hostTime`	`number`	Host system time when `position` was read, Unix epoch milliseconds with a fractional part, the same clock as `Date.now()`. While playing and not paused, `position + (Date.now() - hostTime) / 1000` estimates the current position.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getPosition');

playback.getState

Report the transport state and what the current track allows.

This method takes no parameters.

Returns

Field	Type	Description
`state`	`"stopped" \| "playing" \| "paused"`	Transport state.
`canSeek`	`boolean`	Whether the current track can be seeked; `false` when stopped and for streams that do not support it.
`canPause`	`boolean`	Whether the current track can be paused; always `true`.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getState');

playback.getStopAfterCurrent

Report whether playback stops after the current track.

This method takes no parameters.

Returns

Field	Type	Description
`enabled`	`boolean`	Whether playback stops after the current track.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getStopAfterCurrent');

playback.getVolume

Report the output volume on both scales the host uses, and whether it is muted.

This method takes no parameters.

Returns

Field	Type	Description
`volume`	`number`	Volume as a percentage from `0` to `100`, converted from the decibel value; `0` when muted.
`volumeDb`	`number`	Volume in decibels, `-100` (silence) to `0` (full).
`muted`	`boolean`	Whether output is muted; volume `0` counts as muted.
`isMuted`	`boolean`	The same as `muted`.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.getVolume');

playback.mute

Mute or unmute; calls requesting the active state are ignored. Unmuting restores the volume from before muting.

Parameter	Type	Required	Description
`muted`	`boolean`	No	`true` to mute, `false` to unmute. Default: `true`.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.mute', { muted: true });

playback.next

Skip to the next track under the current playback order.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.next');

playback.pause

Pause playback. No-op when stopped.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.pause');

playback.play

Start playback, or resume when paused.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.play');

playback.playOrPause

The same as playPause.

This method takes no parameters.

Returns

Field	Type	Description
`isPlaying`	`boolean`	Whether playback is running after the toggle.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.playOrPause');

playback.playPath

Append one file to the active playlist and play it; a playlist is created when there is none. A |subsong:N suffix selects a subsong of the file. When the active playlist is locked the call fails with LOCKED, and nothing is added or played. A path the media-root check refuses fails with PERMISSION_DENIED; one foobar2000 resolves to nothing fails with NOT_FOUND, the failure carrying path and subsong.

Parameter	Type	Required	Description
`path`	`string`	Yes	File path, optionally with a `\|subsong:N` suffix. Must not be empty.

Returns

Field	Type	Description
`tracksAdded`	`integer`	Number of playlist rows added; `1`.
`path`	`string`	The file path without the subsong suffix.
`subsong`	`integer`	Subsong identifier of the track that plays: the one asked for with `\|subsong:N`, even when foobar2000 did not list it among the file's subsongs; without the suffix, the file's first.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.playPath', { path: 'C:\\Music\\song.flac' });

Use a path|subsong:N value to address an explicit CUE subsong. The path and subsong index are parsed before playback starts.

playback.playPaths

Add several files to the active playlist and start playing one of them. Entries that are not strings or fail the media-root check are dropped and counted in skippedPaths, which only a successful call reports; when every entry is dropped the call fails with INVALID_PARAMS. Each remaining path becomes a track as written: folders and playlist files are not expanded and the file is not opened, so a missing file is added too. When no track can be made the call fails with NOT_FOUND. When the active playlist is locked the call fails with LOCKED, and nothing is cleared, added or played.

Parameter	Type	Required	Description
`paths`	`string[]`	Yes	File paths, each optionally with a `\|subsong:N` suffix. Must not be empty.
`startIndex`	`integer`	No	Which of the added tracks to start with, counted among the tracks that resolved; a value past the end starts the first. At least `0`. Default: `0`.
`replace`	`boolean`	No	`true` clears the active playlist before adding; `false` appends. Default: `false`.

Returns

Field	Type	Description
`tracksAdded`	`integer`	Number of tracks added to the playlist.
`startedAt`	`integer`	Echoes the requested `startIndex`, even if out of range and playback started at the first track.
`skippedPaths`	`integer`	Number of paths the security check dropped before the call ran; present only when at least one was dropped.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.playPaths', { paths: ['C:\\Music\\a.flac', 'C:\\Music\\b.flac'] });

playback.playPause

Toggle between playing and paused; starts playback when stopped. Reports the state that results.

This method takes no parameters.

Returns

Field	Type	Description
`isPlaying`	`boolean`	Whether playback is running after the toggle.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.playPause');

playback.previous

Skip to the previous track under the current playback order.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.previous');

playback.random

Start a random track of the active playlist.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.random');

playback.setPlaybackOrder

Select a playback order by index or by name; exactly one of the two must be given. Reports the order in effect afterwards.

Parameter	Type	Required	Description
`order`	`integer`	No	Order by index, `0` to `6` in the order of `PlaybackOrderName`. Between `0` and `6` inclusive.
`name`	`"default" \| "repeat-playlist" \| "repeat-track" \| "random" \| "shuffle-tracks" \| "shuffle-albums" \| "shuffle-folders"`	No	Order by name.

Returns

Field	Type	Description
`order`	`integer`	Index of the order in effect after the call.
`orderName`	`"default" \| "repeat-playlist" \| "repeat-track" \| "random" \| "shuffle-tracks" \| "shuffle-albums" \| "shuffle-folders"`	Name of the order in effect after the call.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Pass either order (index) or name. Available modes are: 0 (default), 1 (repeat-playlist), 2 (repeat-track), 3 (random), 4 (shuffle-tracks), 5 (shuffle-albums), and 6 (shuffle-folders). Passing out-of-range indices, invalid names, both keys, or neither fails with INVALID_PARAMS and leaves the active order unchanged. The response fields order and name report the order in effect after execution.

await fb2k.invoke('playback.setPlaybackOrder', { name: 'random' });

playback.setPosition

Seek within the current track (playing or paused). Target position is clamped to the track boundary: negative values seek to the beginning, values exceeding duration clamp just before the end to prevent track advance; tracks of unknown length have no upper clamp. Fails with NO_ACTIVE_ITEM with nothing playing, or NOT_SUPPORTED for a track that cannot seek, such as most streams.

Parameter	Type	Required	Description
`position`	`number`	Yes	Target position in seconds.

Returns

Field	Type	Description
`requestedPosition`	`number`	Requested seek position before clamping.
`actualPosition`	`number`	Effective seek position applied to the playback engine after clamping to track boundaries.
`oldPosition`	`number`	Position read before the seek, in seconds, with the same latency compensation as `playback.getPosition`.
`newPosition`	`number`	Position read right after the seek, in seconds, with the same latency compensation as `playback.getPosition`; the engine may still be settling, so this can still be the old position.
`hostTime`	`number`	Host system time when `newPosition` was read, Unix epoch milliseconds with a fractional part, the same clock as `Date.now()`.
`duration`	`number`	Length of the track in seconds; `0` or less when the length is unknown.
`subsong`	`integer`	Subsong identifier of the track.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.setPosition', { position: 42.5 });

playback.setStopAfterCurrent

Arm or disarm stopping after the current track.

Parameter	Type	Required	Description
`enabled`	`boolean`	Yes	`true` to stop after the current track.

Returns

Field	Type	Description
`enabled`	`boolean`	The value now in effect.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.setStopAfterCurrent', { enabled: true });

playback.setVolume

Set output volume as a percentage. Valid range is 0..100 with automatic clamping; 0 mutes.

Parameter	Type	Required	Description
`volume`	`number`	Yes	Output volume percentage; valid range 0..100 with automatic clamping.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playback.setVolume', { volume: 80 });

playback.stop

Stop playback.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.stop');

playback.toggleMute

Flip the mute state and report the new one.

This method takes no parameters.

Returns

Field	Type	Description
`muted`	`boolean`	Whether output is muted after the toggle.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.toggleMute');

playback.toggleStopAfterCurrent

Flip the stop-after-current flag and report the new value.

This method takes no parameters.

Returns

Field	Type	Description
`enabled`	`boolean`	The value after the toggle.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.toggleStopAfterCurrent');

playback.volumeDown

Lower the volume by one of the host's steps: one decibel, landing on a whole decibel.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.volumeDown');

playback.volumeUp

Raise the volume by one of the host's steps: one decibel, landing on a whole decibel.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playback.volumeUp');

playback:stopAfterCurrentChanged: Emitted when the "stop after current" toggle changes. The payload is { enabled }, matching the API response field.
For the full list of playback events and their payload schemas, see Global Events Reference.

Playback API ​

Playback position and timing ​

playback ​

playback.getCurrentTrack ​

playback.getCurrentTrackIndex ​

playback.getPlaybackOrder ​

playback.getPlayingPlaylist ​

playback.getPosition ​

playback.getState ​

playback.getStopAfterCurrent ​

playback.getVolume ​

playback.mute ​

playback.next ​

playback.pause ​

playback.play ​

playback.playOrPause ​

playback.playPath ​

playback.playPaths ​

playback.playPause ​

playback.previous ​

playback.random ​

playback.setPlaybackOrder ​

playback.setPosition ​

playback.setStopAfterCurrent ​

playback.setVolume ​

playback.stop ​

playback.toggleMute ​

playback.toggleStopAfterCurrent ​

playback.volumeDown ​

playback.volumeUp ​

Related events ​

Playback API

Playback position and timing

playback

playback.getCurrentTrack

playback.getCurrentTrackIndex

playback.getPlaybackOrder

playback.getPlayingPlaylist

playback.getPosition

playback.getState

playback.getStopAfterCurrent

playback.getVolume

playback.mute

playback.next

playback.pause

playback.play

playback.playOrPause

playback.playPath

playback.playPaths

playback.playPause

playback.previous

playback.random

playback.setPlaybackOrder

playback.setPosition

playback.setStopAfterCurrent

playback.setVolume

playback.stop

playback.toggleMute

playback.toggleStopAfterCurrent

playback.volumeDown

playback.volumeUp

Related events