Playlists

Playlists in MZAP are stored in a SQLite database and provide persistent, ordered track lists for players.

Creating Playlists

Create a new playlist and add tracks from the media library, local files, or URLs (internet radio streams).

Bulk-Create from a Folder Tree

The Playlists tab has a From Folder button alongside Create Playlist and Import (it is also available from the Library tab). Pick a root folder; MZAP registers it as a library folder and scans it.

What to create

The dialog offers three grouping modes:

One playlist per subfolder (default) — every subfolder containing audio becomes its own playlist.
- Each playlist is named after its leaf folder (SomeAlbum, not Artist - SomeAlbum). Duplicate names are allowed since the source folder is the identity.
- The picked root folder itself is never turned into a playlist, even if it has audio files at the top level — only subfolders become playlists.
One playlist, all files — every audio file under the folder and its subfolders goes into a single playlist.
One playlist, this folder only — only the files sitting directly in the picked folder; subfolders are ignored.

For the two single-playlist modes the dialog shows an editable Playlist name, pre-filled with the picked folder's name. If you choose "this folder only" for a folder with no direct audio files, nothing is created and the result message says so.

Re-running on the same root syncs in place

Run From Folder again on the same root — in any mode — and the matching existing playlist is synced rather than duplicated. Playlists are matched by their stored source path, so each mode updates the playlist it created before:

Existing playlists are matched by their stored source folder, so renaming a playlist in the UI does not break sync.
New files in a subfolder are appended to the corresponding playlist.
Files removed from disk are removed from the playlist — but only tracks that originally came from the source folder; tracks you manually added from elsewhere are preserved.
Reorderings made in the UI are preserved; newly added tracks always append at the end.
Orphan playlists (whose source folder was deleted on disk) are left alone — remove them manually if you no longer want them.
Folder renames are not auto-detected: the old playlist becomes an orphan and a new one appears under the new name.

Bulk-create requires Admin (same as Import). The call is synchronous and waits for the scan + sync pass to complete; for already-scanned folders this is near-instant because unchanged files are skipped by modification time.

The current playlist

Each Playlist player has its own working current playlist. Editing a player's queue — adding files or streams, removing or reordering tracks, changing the play mode, clearing it, or playing a radio station onto the player — affects only this working copy.

Editing never changes your saved playlists. If a player is playing one of your saved library playlists, the first edit forks a private working copy (shown with an Unsaved badge) and leaves the saved playlist untouched. To deliberately change a saved playlist, edit it from the Playlists tab instead.
No duplicate playlists. Opening the same playlist file repeatedly, or playing several radio stations onto a player, reuses the working playlist instead of creating a new identically-named one each time. Re-importing the same .m3u/.pls file re-syncs the existing library playlist rather than adding a copy.
Saving a player's queue promotes the working playlist into a normal, visible library playlist (and writes the file when you save to file).

These per-player working playlists are hidden from the Playlists library list until you save them.

Saving a working queue from the picker

Switching a player to a different playlist replaces its unsaved working queue, so the Select Playlist dialog offers a way to keep it first: when the active queue is unsaved and has at least one track, a Save current queue… action appears at the top of the dialog. Choose it, give the queue a name, and it is stored as a normal library playlist.

The player keeps playing throughout — the working queue is promoted in place and becomes a saved playlist. The action is hidden for players already on a saved playlist.

Editing a playing playlist is seamless

When you edit the queue of a player that is currently playing, the switch to the working copy is seamless: the currently-playing track is carried over unchanged, so playback continues without interruption — no audible gap, and no reconnect for a live stream. Only later track changes use the edited queue. Switching to a genuinely different playlist (Browse Playlists, scheduler) still reloads as expected.

Where a queue comes from

A player shows the source of its current queue in two places — under the player name in the header (visible from any tab) and in the queue info bar above the track list:

📄 File — loaded from or saved to an .m3u file; shows the filename, with the full path on hover.
🎵 Library — a saved playlist from the app's Playlists; shows its name.
✎ Unsaved — a working queue that hasn't been saved yet.

The toolbar above a player's queue groups its actions for clarity and to prevent accidental data loss:

Add / source actions are grouped on the left: Load playlist from file, Add audio file, Load stream, Browse Playlists.
Save is a single dropdown button (download icon) with two choices:
- Save to File… — exports the whole queue to an .m3u/.m3u8 file (desktop only).
- Save to Playlists… — saves the whole queue into the app's Playlists library (append to an existing playlist, or create a new one).
Clear Playlist (trash icon) sits at the far-right edge, separated from the other actions. Clearing the queue always asks for confirmation.

Playback mode

Each player with a playlist can use one of these modes:

Sequential — Play tracks in order
Shuffle — Random order
Repeat One — Loop the current track
Repeat All — Loop the entire playlist

Playback mode belongs to the player, not to the playlist it happens to be pointing at. Each player keeps its own mode, current track, and shuffle order.

Changing a player's mode first moves that player onto its own private working copy of the playlist, so your saved playlist is never modified and other players are never affected.

Setting the mode from the players list and from the player detail view behave identically.
Two players can play the same library playlist with different modes at the same time.
Enabling stream-outage failover — which switches the player to Repeat All — no longer rewrites the saved playlist.

A saved playlist still carries a default mode, which is the mode a player starts with when it first picks that playlist up.

Importing

MZAP can import playlists from standard M3U and PLS files. Importing the same file again re-syncs the existing playlist instead of creating a duplicate.

Playing a Track

Double-clicking a track in a player's playlist starts playback immediately, in a single action — even when the player is stopped. The status panel ("Now Playing" / "Paused" / "Stopped") always reflects the player's real state.

Clearing a Playlist

Clearing a player's queue empties its working playlist and always asks for confirmation first; any saved library playlist is left intact, and you can add tracks again afterwards. Playback is not interrupted, but the bound player's behavior depends on what it is playing:

A player playing a file finishes the current track, then stops automatically. Its track reference is cleared, so a later Play falls back to the (empty or reassigned) playlist.
A player playing an internet radio stream keeps playing — and keeps its station identity — until you stop it manually, since a stream has no natural end. Pause/Play and Stop/Play continue to work, and pressing Play after stopping reconnects the same station.

Once a player is stopped with nothing loaded, the "Now Playing" panel clears the stale title and shows "No audio loaded". A player still playing keeps its title. Clearing a playlist while a player is playing shows a toast: "Playlist cleared. Playback continues until you stop it."

Crossfade

Crossfade smooths the transition between playlist tracks by fading the outgoing track out as the incoming one fades in. The control sits in the player's Playlist tab header, next to the failover shield and the playback-mode selector.

Crossfade is set per player, and the player's own value is authoritative:

A duration of 0 means no crossfade — tracks change with a hard cut.
Default Crossfade Duration in Settings → Audio only seeds the value for newly created players. Changing it does not alter players that already exist.

This means one player can hard-cut while others crossfade — useful when, say, announcements should start instantly but background music should blend.

Stream-outage failover

A player that plays an internet radio stream can automatically fall back to local backup tracks when the stream drops, then return to the stream once it is reachable again — minimizing dead air. No separate backup playlist is needed.

Setting it up

Build the player's queue as [stream URL, local file 1, local file 2, …]. The first stream track is the primary source; the local tracks after it are the backup.
Turn on the shield toggle on the player's Playlist tab, next to the playback-mode selector. It is per-player and off by default.

Enabling failover automatically sets the playlist to Repeat All and turns crossfade on (using a default duration if it was off) — this is what makes the return to the stream seamless.

What happens during an outage

When the stream stalls or drops, playback advances into the local backup tracks. The incoming local track is faded in, so the drop is heard as a fade rather than a cut.
The shield turns amber and an On backup badge appears in the Now Playing area and on the player's card in the Players view. (When failover is on and the stream is healthy, the shield is blue.)
While on backup, MZAP checks at every local-track boundary whether the internet is reachable. As soon as it is, the current local track crossfades directly back into the stream — without playing another backup track first. With short backup files, the return happens very soon after connectivity returns.
If the stream is still down, the player briefly stalls, falls back to local, and retries at the next boundary.
If the local backup tracks are unavailable too, the player keeps retrying the stream, exactly as it did before — failover never makes things worse than no failover.

Switching a player's playlist

Playlist player cards in the Players view show the player's current playlist on a clickable line beneath the type and state badges. Clicking it opens the playlist picker, so you can switch the player to another playlist — or create a new one — without opening the detail panel.

The line shows the same source-aware label and icon as the detail header: the library playlist name, the .m3u file name, or Unsaved for a working queue.
When no playlist is loaded it reads Select Playlist.
It appears only for Playlist-type players, and only if you have permission to control playback.