Shareable saved playlist restore and browser

[NickKhunapoj]

Summary

Adds a lightweight, durable saved-playlist system for music queues.

Users can save YouTube tracks from the active queue, browse saved playlists in their server, inspect details, load or delete playlists with confirmation popups, and restore a playlist through the existing music playback pipeline.

New features

Save active queue

• Added an icon-only 💾 Save button beside Refresh on the player’s second control row.

• Saves YouTube tracks in their intended playback order:

  1. Current track, when it is a YouTube track
  2. Pending crossfade track, when present
  3. Remaining queued YouTube tracks

• Excludes /music local attachment tracks, preventing unusable saved playlists.

• Rejects empty or local-only queues.

• Stores each track’s title, YouTube URL/query, and duration.

• Stores the current position only when the active track is saved.

• Sends the generated restore code privately to the user.

Saving the active music queue and receiving a restore code.

Guild-private, shareable restore codes

• Uses collision-safe xxxx-xxxx playlist codes.
• Codes expire 30 days after creation.
• Each playlist stores its originating Discord guild ID and creator ID.
• Codes are shareable with anyone in the same server.
• Codes cannot be listed, restored, loaded, or deleted from another server.
• A restore code is single-use: after confirmation, voice validation, and atomic consumption, it is removed from storage.

Legacy records created before guild scoping are hidden from lists. Using an old code directly claims that record for the guild where it is first restored, preserving recovery while enforcing guild isolation afterward.

Restore command

/music restore <code>

• Validates the code, guild scope, expiry, and stored playlist data.
• Shows a private confirmation popup before replacing the active queue.
• Confirmation buttons disable immediately after Load is pressed to prevent duplicate restore requests.
• Reuses the existing voice connection logic or joins the requesting user’s voice channel.
• Safely replaces the active queue and invalidates stale playback callbacks.
• Starts the first restored track automatically.
• Applies the saved first-track playback position through FFmpeg.
• Uses just-in-time yt-dlp hydration, so only the track about to play needs a fresh stream URL.

Restoring a playlist and automatically starting playback.

Public playlist browser

/music restore list

Displays a public, paginated browser for playlists saved in the current server.

Controls:

• Row 1: ◀️ Previous, ▶️ Next, 🔢 Jump to page, 🔄 Refresh
• Row 2: 📄 Details, ♻️ Load, 🗑️ Delete

Load and Delete accept a playlist number through a modal, then show a private confirmation popup. The confirmation can only be completed by the user who opened it.

Public browser for saved playlists in the current server.

Playlist details

Details are publicly visible within the current server and include:

• Playlist code
• Creator
• Creation and expiry timestamps
• Track count
• Ordered track list
• Direct ♻️ Load and 🗑️ Delete buttons

Paginated playlist details in restored playback order.

Modified behavior

• /music queue remains the active-queue viewer.
• Restore safely clears/replaces the current queue, history, pending crossfade state, and stale playback transitions.
• Playback-generation protection prevents callbacks from stopped audio from modifying the restored queue.
• Saved durations allow restored queues to display track lengths immediately.
• Restored playlists do not persist volume, loop mode, crossfade state, controller state, or resolved stream URLs.
• Large playlists remain lightweight: all track records are restored into the queue, but yt-dlp resolves tracks only as they are about to play.
• Save and restore operations include DEBUG diagnostics for counts, queue state, confirmation flow, and resume offsets. Codes, track titles, URLs, and user IDs are not logged. Enable with LOG_LEVEL=DEBUG.

Storage

Saved playlists are persisted at:

data/playlists/playlists.json

The directory is created automatically and is ignored by Git.

Each record stores:

• Restore code
• Guild ID
• Creator Discord ID
• Creation and expiry timestamps
• First-track resume position
• Ordered track title, YouTube query/URL, and duration

Save, browse, and restore flow

flowchart LR
    User["Discord user"] -->|💾 Save| Player["Music player state"]
    Player --> Snapshot["Current + crossfade-next + queue"]
    Snapshot --> Filter["Keep YouTube tracks only"]
    Filter --> Store["Guild-scoped JSON datastore"]
    Store --> Code["Private xxxx-xxxx code"]

    User -->|/music restore list| Browser["Public server playlist browser"]
    Browser -->|📄| Details["Playlist details"]
    Browser -->|♻️ or 🗑️| Number["Playlist number modal"]
    Details -->|♻️ or 🗑️| Confirm["Private confirmation popup"]
    Number --> Confirm

    User -->|/music restore code| Validate["Validate code and guild"]
    Validate --> Confirm
    Confirm -->|Load| Consume["Consume playlist atomically"]
    Consume --> Queue["Replace active queue"]
    Queue --> Playback["Existing playback pipeline"]
    Playback --> Voice["Voice channel audio"]

Loading

Restore lifecycle

flowchart TD
    A["Save YouTube queue"] --> B["Validate non-empty saved track list"]
    B --> C["Persist guild-scoped playlist JSON"]
    C --> D["Send restore code privately"]

    E["Open /music restore list"] --> F["Public paginated server list"]
    F --> G["Choose details, load, or delete by number"]
    G --> H["Private confirmation popup"]

    I["Run /music restore code"] --> J["Validate code, expiry, and guild"]
    J --> H
    H -->|Load| K["Validate voice channel and consume playlist"]
    K --> L["Replace queue and invalidate stale callbacks"]
    L --> M["Hydrate and start first track"]
    M --> N["Resume saved position when available"]

    H -->|Delete| O["Atomically delete playlist"]

Loading