Playlist
Zaparoo supports keeping a playlist of media in memory and tracking the current position. You can load playlists from files, folders, or define them inline.
Playlist sources
The playlist.play, playlist.load, and playlist.open commands take a source: a folder path, a .pls file path, an inline JSON playlist, or a deck://<id> deck. The playlists feature page documents each format, including how .pls entries are treated as ZapScript and which fields inline JSON uses.
**playlist.play:/media/fat/games/Genesis
Media slots
Playlists can play in the primary slot, the default that is shared with games, or the background slot, which plays alongside whatever is in the primary slot. Add ?slot=background (or ?slot=bg) to load a playlist into the background slot, typically for background music.
**playlist.play:/media/fat/music/album?slot=background
All playlist commands accept the slot argument, so playlist.next, playlist.pause, and the rest can target a specific slot. When omitted, commands act on the active playlist's slot, or the primary slot when no playlist is running. Slots are explained on the audio playback page.
Repeat modes
The playlist.play, playlist.load, and playlist.open commands accept a repeat argument that sets how the playlist loops:
| Value | Behavior |
|---|---|
off | Stop at the end of the playlist (default) |
all | Loop back to the first item after the last |
one | Repeat the current item |
**playlist.play:/media/fat/music/album?repeat=all
playlist.play
Loads a playlist and immediately launches the first item. If the source names the playlist that is already active, it moves to the next item instead, wrapping after the last, or resumes a paused playlist at its position.
Syntax
**playlist.play:[<source>]
Arguments
source (optional)
Path to a folder, .pls file, inline JSON playlist, or deck://<id>. If omitted, resumes the current paused playlist.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
mode | string | - | Set to shuffle for random order |
repeat | string | off | off, all, or one (see Repeat modes) |
slot | string | primary | primary or background media slot |
Examples
Load the Favorites folder as a playlist and launch the first item:
**playlist.play:/media/fat/_@Favorites
Load a playlist file in shuffled order:
**playlist.play:/media/fat/playlist.pls?mode=shuffle
Resume a paused playlist:
**playlist.play
playlist.load
Loads a playlist into memory without launching anything.
Syntax
**playlist.load:<source>
Arguments
source (required)
Path to a folder, .pls file, inline JSON playlist, or deck://<id>.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
mode | string | - | Set to shuffle for random order |
repeat | string | off | off, all, or one (see Repeat modes) |
slot | string | primary | primary or background media slot |
Examples
Load a playlist file:
**playlist.load:/media/fat/playlist.pls
Load a folder in shuffled order:
**playlist.load:/media/fat/games/Genesis?mode=shuffle
playlist.open
Loads a playlist and opens an interactive picker menu to select an item.
MiSTer displays the picker locally. On other platforms, a connected client that supports Core's global UI events can display and answer it. If no renderer is available, the playlist still loads and the picker expires after 30 seconds.
Syntax
**playlist.open:[<source>]
Arguments
source (optional)
Path to a folder, .pls file, inline JSON playlist, or deck://<id>. If omitted, reopens the picker for the current playlist.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
mode | string | - | Set to shuffle for random order |
repeat | string | off | off, all, or one (see Repeat modes) |
slot | string | primary | primary or background media slot |
Examples
Open a picker menu for the playlist:
**playlist.open:/media/fat/playlist.pls
Reopen the picker for the currently active playlist, showing the current position:
**playlist.open
playlist.stop
Stops the current media and clears the playlist from memory.
Syntax
**playlist.stop
Arguments
None.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
slot | string | primary | primary or background media slot |
Examples
Stop playback and clear the playlist:
**playlist.stop
playlist.pause
Pauses the current playlist without clearing it.
Syntax
**playlist.pause
Arguments
None.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
slot | string | primary | primary or background media slot |
Examples
Pause the playlist. Use playlist.play without arguments to resume:
**playlist.pause
playlist.next
Launches the next item in the playlist.
Syntax
**playlist.next
Arguments
None.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
slot | string | primary | primary or background media slot |
Examples
Advance to the next item:
**playlist.next
playlist.previous
Launches the previous item in the playlist.
Syntax
**playlist.previous
Arguments
None.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
slot | string | primary | primary or background media slot |
Examples
Go back to the previous item:
**playlist.previous
playlist.goto
Jumps to a specific position in the playlist.
Syntax
**playlist.goto:<index>
Arguments
index (required)
The 1-based index of the item to launch.
Advanced arguments
| Argument | Type | Default | Description |
|---|---|---|---|
slot | string | primary | primary or background media slot |
Examples
Jump to the first item:
**playlist.goto:1
Jump to the fifth item:
**playlist.goto:5