playlists

type Playlist struct {
	// HoldToken is internal runtime ownership for primary hold-mode playback.
	// It is not part of playlist persistence or API responses.
	HoldToken *tokens.Token
	// AllowedCommands is the bound carried by the script that opened this
	// playlist, and it travels to every item token. A playlist is an
	// indirection like a ZapLink: opening one must not let its items reach
	// commands the script that opened it could not run itself.
	AllowedCommands tokens.CommandPolicy
	ID              string
	// DeckID names the deck on this device the playlist was opened from. It
	// is set only by the deck loader, never from a served playlist, so it is
	// what ties an open playlist to its deck; the ID is whatever its source
	// chose to call it.
	DeckID string
	// ProfileID is the profile that loaded the playlist, "" for none. Its
	// memory of where the playlist is belongs to that profile until the
	// playlist closes, whoever is active by then.
	ProfileID string
	Name      string
	Slot      string
	Items     []PlaylistItem
	Index     int
	// Advance moves to the next item after this much playing time. Zero
	// means the playlist does not rotate on a timer.
	Advance time.Duration
	// Idle moves to the next item after this long with no user input, and
	// starts a loaded playlist the same way. Zero means it does not rotate on
	// idle. It is never set together with Advance.
	Idle time.Duration
	// Countdown is how long the notice before an automatic switch stays up.
	// CountdownSet distinguishes an explicit zero, which switches without a
	// notice, from no value, which uses DefaultCountdown.
	Countdown time.Duration
	// EngineFromIndex is the item the engine moved this update away from, so
	// the queue handler can drop a move the user has already overtaken.
	EngineFromIndex int `json:"-"`
	// StopSeq is the count of stops of the primary media when the update was
	// issued, valid when StopStamped is set. A stop after that cancels an
	// update that has not launched yet.
	StopSeq uint64 `json:"-"`
	// StopStamped says StopSeq was taken for this update.
	StopStamped bool `json:"-"`
	Playing     bool
	// Armed marks a loaded idle playlist that is waiting for the device to go
	// idle before it starts. Playing it, pausing it or stopping it disarms it.
	Armed bool
	// PausedByFailure marks a playlist that stopped because its current item
	// failed to launch, not because anyone paused it. Moving to another item
	// resumes such a playlist, where a paused one only moves its cursor.
	PausedByFailure bool `json:"-"`
	// Clear signals the queue handler to remove the active playlist for this slot.
	Clear bool
	// Loop and LoopOne control end-of-playlist behavior set at load time.
	// Loop wraps back to the start; LoopOne repeats the current track.
	Loop    bool
	LoopOne bool
	// ForceRelaunch bypasses playlistNeedsUpdate dedup so the same track can be
	// relaunched for LoopOne and single-item Loop.
	ForceRelaunch bool
	// FromPlaylistItem marks an update requested by a playlist item's own
	// run, such as a card that plays another playlist. It is part of that
	// item's launch rather than a second one competing with it.
	FromPlaylistItem bool `json:"-"`
	// EngineStarted marks an update the auto-advance engine queued on its own,
	// so the item it launches is known to be one nobody asked for. It is
	// part of that launch rather than of the playlist.
	EngineStarted bool `json:"-"`
	// Reconfigure applies only the rotation settings of this update — Advance,
	// Idle, Countdown and Armed — to the active playlist with the same ID,
	// keeping its position and playback and never launching anything.
	Reconfigure bool `json:"-"`
	// EngineFromArmed says the move was decided on a loaded playlist waiting
	// to start rather than a playing one.
	EngineFromArmed bool `json:"-"`
	// Refresh replaces the items and name of the active playlist with the
	// same ID in place, keeping its position and playback state and never
	// launching anything. It is ignored when no such playlist is active.
	Refresh bool
	// Unsafe is the playlist's effective trust. It is set either because the
	// items came from a source this device does not trust — a fetched
	// ZapLink, or a cached copy of somebody else's deck — or because the
	// script that opened it was already untrusted, which even the user's own
	// deck inherits. Every item token carries it, so commands that drive
	// input or run programs refuse, the same as the script that opened the
	// playlist.
	Unsafe       bool
	CountdownSet bool
	// Shuffled says the items were put in a random order when the playlist
	// loaded, so that order is part of where the playlist is.
	Shuffled bool
	// Ephemeral marks a playlist made up on the spot, such as a random
	// rotation, that has no identity to be remembered by.
	Ephemeral bool
	// Completed marks the Clear of a playlist that played to its natural
	// end, which starts it over the next time it loads.
	Completed bool `json:"-"`
}

type PlaylistController struct {
	Active     *Playlist
	Background *Playlist
	Current    *Playlist
	HoldToken  *tokens.Token
	Queue      chan<- *Playlist
	// LaunchResolved, when set, is told once the launcher of a launch is
	// known whether that launcher publishes the media itself later, outside
	// the launch call. Only the playlist worker sets it.
	LaunchResolved func(publishesLater bool)
}

type PlaylistItem struct {
	ZapScript string
	Name      string
}