Kometa playlists

Kometa Playlists

Own standalone playlist files.

Goal

• Produce valid-looking playlists: files.
• Keep playlist definitions separate from config.yml.
• Enforce the one-builder-per-playlist rule.

Output Contract

Always return:

1. YAML for a playlist file
2. 2-5 short bullets on libraries, sync behavior, and builder choice
3. Caveats for root playlist_files wiring and builder constraints

File Boundary

Belongs here:

• playlists:
• libraries
• sync_to_users
• exclude_users
• delete_playlist
• one builder per playlist entry
• playlist-local templates and external_templates

Does not belong here:

• root playlist_files: wiring from config.yml
• multiple builders combined in one playlist entry
• collections: bodies

Hard Rules

• playlists: appears once at top level
• libraries is required
• playlists are referenced from root playlist_files: in config.yml, not under a library
• each playlist entry can use only one builder because ordering is inherited from that builder

Decision Rules

Use this skill when:

• the user wants a chronological or curated playlist
• the user wants one playlist synced to one or many Plex users
• the user wants a playlist deleted or excluded for certain users

Do not use this skill when:

• the user wants multiple source lists combined into one result
• the user wants collection-like multi-builder aggregation
• the user only wants the built-in default playlist pack

If the user wants multiple sources combined:

• push to collections unless they agree to pick one builder source

User Sync Rules

• sync_to_users controls which users receive the playlist
• exclude_users removes users from the sync target set
• the server owner always sees defined playlists, so that does not need to be repeated
• delete_playlist: true is valid for cleanup workflows

Builder Rules

Good builder families for playlists include:

• Trakt list
• IMDb list
• MDBList list
• TMDb list

Rule:

• do not combine them in one playlist entry

Playlist Updates

Useful playlist-local presentation controls:

• summary
• trakt_description, tmdb_description, tvdb_description, letterboxd_description
• url_poster, file_poster, tmdb_list_poster, tvdb_list_poster
• url_background, file_background, tmdb_background, tvdb_background

Hard rule:

• do not suggest collection-only item updates in playlist files

Default Versus Custom Playlists

Use the defaults skill instead when:

• the user wants built-in universe/timeline playlists through default: playlist

Use this skill when:

• the user wants a custom playlists: file
• the user wants their own builder URL or own user sync behavior

Embedded Examples

Basic cross-library playlist

playlists:
  Marvel Cinematic Universe Chronological Order:
    sync_mode: sync
    libraries: Movies, TV Shows
    trakt_list: https://trakt.tv/users/donxy/lists/marvel-cinematic-universe
    summary: Marvel Cinematic Universe In Chronological Order

User sync and exclusions

playlists:
  Marvel Cinematic Universe Chronological Order:
    sync_mode: sync
    libraries: Movies, TV Shows
    sync_to_users: all
    exclude_users:
      - kids
    trakt_list: https://trakt.tv/users/donxy/lists/marvel-cinematic-universe?sort=rank,asc

Delete playlist

playlists:
  Old Shared Order:
    libraries: Movies
    sync_to_users: all
    delete_playlist: true

Playlist with presentation updates

playlists:
  Sci-Fi Night:
    libraries: Movies, TV Shows
    trakt_list: https://trakt.tv/users/example/lists/sci-fi-night
    summary: Prime-time science fiction picks across shared libraries
    url_poster: https://example.com/scifi-night.jpg

Local References

Read only what matches the request:

• references/cards/files--playlists.md
• references/cards/playlists--core.md
• references/cards/playlists--updates.md
• references/cards/config--playlists.md
• references/cards/templates--core.md

Use these tiny examples first:

• examples/gold/gold-cross-library-playlist.yml
• examples/gold/gold-playlist-user-sync.yml
• examples/gold/gold-playlist-summary-poster.yml
• examples/gold/gold-default-playlist-call.yml

Review Checklist

• is this a playlist file or just the playlist_files config wiring?
• is playlists: the top-level key?
• is there exactly one builder in each playlist entry?
• are libraries present and plausible?
• are user sync controls at the playlist level?

Stopping Condition

Finish when:

• the playlist file is valid-looking
• the one-builder rule is respected
• the user knows how it is referenced from config.yml