Playlists and Favorites

Playlists & Favorites

Playlists are curated lists of items that can span multiple collections. They appear as virtual collection tiles alongside your real collections and behave like collections in most respects — you can browse them, search them, set them as the startup collection, and launch items directly from them.

Favorites is a built-in playlist that's always present and can't be deleted. Beyond Favorites, you can create any number of user playlists, populate them via the right-click context menu, and import or export to / from M3U and JSON.

Looking for rule-driven playlists? Smart playlists derive their members from a filter (recently launched, most played, by extension, …) and re-evaluate every time you open them. See Smart Playlists.

Where to find this — Right-click any item → Add to Playlist ▶ or Add to Favorites. Playlist tiles appear at the top level of the collection grid (or wherever they're parented).

Favorites

A built-in, reserved playlist. Auto-created on first access; cannot be deleted; cannot be renamed.

Action	Where
Add an item	Right-click → Add to Favorites
Remove an item	Right-click an item inside Favorites → Remove from Favorites

The toggle in the context menu is contextual: it shows Add to Favorites if the item isn't yet in Favorites, Remove from Favorites if it is.

Items in Favorites carry a small badge in the sidebar's Item tab.

User playlists

Creating a playlist

Three ways:

1. From the context menu — right-click any item → Add to Playlist ▶ → New playlist…. A small dialog asks for a name; the new playlist is created and the item added.
2. Empty playlist — there isn't a dedicated "create empty playlist" action today. The shortest path is option #1 with any item, then remove the item afterward.
3. From an import — see Importing.

Naming and renaming

Each playlist has a unique name. Rename via right-click on the playlist tile → Rename Playlist…. Names can be anything except an empty string and must be unique among playlists.

Adding items

Right-click any item in any collection → Add to Playlist ▶ → [name]. Adding an item that's already in the playlist is a no-op.

Removing items

Right-click an item inside the playlist → Remove from Playlist. The item is removed from the playlist; the underlying item file and its database state are untouched.

Deleting a playlist

Right-click a playlist tile → Delete Playlist. Confirmation prompt. Items aren't deleted — only the playlist itself.

Reserved playlists (Favorites) hide the Delete Playlist option.

Behavior of playlist tiles

Playlists are virtual collections — they appear in the grid as tiles like real collections, but they don't have an INI section, can't be parented elsewhere via the Settings tree, and don't carry their own appearance settings.

What you can do with a playlist tile:

• Open it (Enter) — browse / search / sort / launch its items just like any collection
• Make it the startup collection — set [General] startupCollection=Playlist Name (the name shown in the UI)
• Toggle the sidebar inside it (F9) — sidebar inherits the active collection's styling
• Apply title-pattern cleanup — playlists do not have their own per-collection settings, but the sidebar / grid layout follows the parent context

What you can't do:

• Set per-collection appearance (no INI section to edit)
• Add subcollections under a playlist
• Use the Apply Settings workflow to/from a playlist

Import / export

Exporting

Right-click a playlist tile → Export Playlist…. Use this for the items-only formats (JSON / M3U) below; for a full-fidelity backup that includes every playlist alongside the collection it lives in, export the parent collection as a .kart package instead — playlists now round-trip inside karts.

Two formats:

Format	Lossy?	Notes
JSON	No	Preserves source collection UUID + path. Round-trip safe.
M3U	Yes	Path-per-line. Compatible with media players. Loses cross-collection metadata.

JSON shape

{
  "name": "Playlist Name",
  "items": [
    {
      "source_collection_uuid": "abcd-1234",
      "source_path": "/home/me/Videos/Films/a-film.mkv"
    },
    ...
  ]
}

The source_collection_uuid is generated by Kartend and stable across sessions; it's how playlist items survive collection rename.

M3U shape

#EXTM3U
/home/me/Videos/Films/a-film.mkv
/home/me/Music/Albums/another-album.flac

Standard M3U. Will play in any media player but loses the collection binding. When re-importing into Kartend, items match by absolute path against the live items table; unmatched lines are skipped silently.

Importing

Right-click a playlist tile or use the file menu's import action (in some builds). Pick a .json or .m3u file:

• JSON import — creates a new playlist with the given name. Items match by (source_collection_uuid, source_path) against live items; unmatched items become "ghost rows" that show as un-launchable in the grid (or are filtered out, depending on settings).
• M3U import — creates a new playlist; items match against live items by absolute file path. Unmatched paths are dropped.

Importing a JSON file with a name that already exists prompts for a new name (no merge today; merge is a feature on the wishlist).

Recipes

Curated "10 best" tile

Create a playlist called Top Ten. Add items from various collections. Set as your startup collection:

[General]
startupCollection=Top Ten

When you launch Kartend, you land directly on the playlist.

Cross-collection "currently playing" list

Create a playlist Currently Playing. Add the items you're actively working through. Drop them when you finish.

Pair with a custom field (status=in progress) to mark items individually so you can recover the list state from custom fields if you ever delete the playlist.

Moving a playlist between your own machines

Two options:

• JSON export preserves the source-collection UUID plus each item's path. On import, items match by (uuid, path) against the live items table on the target machine. Works cleanly when both machines share the same collection layout (the typical sync case).
• .kart export of the parent collection bundles every playlist (static and smart) belonging to it, plus the items themselves. The preflight + merge dialogs at import handle path remapping and any conflicts. See Backup & Migration.

M3U export is intentionally lossy — it's intended for handing the list to a media player, not for round-tripping inside Kartend.

Backup all playlists at once

Two options:

• Copy the SQLite file ~/.local/share/kartend/kartend.db — it contains every playlist and membership row.
• Export each owning collection as a .kart — playlists ride along inside the bundle. See Backup & Migration.

A bulk-JSON-export across all playlists is on the wishlist.

How playlists store data

playlists                       playlist_items
─────────────────               ──────────────────────────
id (UUID)                       playlist_id (FK)
name                            position
parent_collection_uuid          source_collection_uuid
reserved_kind ('' or            source_path
  'favorites')

• Items are referenced by (source_collection_uuid, source_path), which makes them stable across rename and rescan.
• position is dense (re-densified on remove) so playlist order is preserved.
• reserved_kind = 'favorites' marks the built-in Favorites playlist. Other reserved kinds may be added in the future (e.g. "Recently Played" as a virtual playlist).

Where to next

• Smart Playlists — rule-driven playlists that re-evaluate on open
• Item Metadata — custom fields, manual files, artwork links per item
• Backup & Migration — .kart package format for full-collection (and playlist) backup or transfer between your own machines
• Search, Sort & Filter — searching inside a playlist works the same as inside a collection

For developers

• Manager: src/modules/data/playlist/ (PlaylistManager).
• Schema: playlists and playlist_items tables, defined in the database migrations.
• Virtual collection synthesis: at MainWindow init, PlaylistManager builds a CollectionConfig for each playlist (isPlaylist=true, playlistId=<uuid>, playlistReservedKind empty or favorites). These appear in the live m_collections list alongside real collections.
• Membership checks: PlaylistManager::containsItem(playlistId, srcUUID, srcPath) is O(1) via an in-memory index.
• Add operations are idempotent; remove re-densifies positions.
• M3U / JSON serialization: playlist_io.cpp (lossy / lossless paths are separate methods).
• Adding a new reserved playlist (e.g. "Recently Played"): pick a reserved-kind string, add the auto-create logic to PlaylistManager::ensureReservedPlaylists(), gate context-menu Delete to skip it.