[FEATURE] Play History & Singer Memory

[safepay]

Status: Capturing requirements from PR #746, PR #790, and issues #213, #90, #209

What is this?

Play History is a KJ (Karaoke Jockey) management tool. It gives the host a record of what happened during a karaoke event: who sang, what they sang, and when. This is admin-only.

Current Situation

Several PRs and issues have proposed overlapping solutions for tracking karaoke activity:

• PR feat: add play history database and History UI #746 (@mave007) — Full play history system: SQLite database for plays, sessions, users, and aliases, with History/Rankings/Performers pages and admin management. Closed because it introduced a standalone database rather than building on the existing song database.
• PR Feat: add KJ auto-complete singer memory and 1-click queue bypass #790 (@poeticize) — Client-side KJ singer memory using localStorage: auto-complete for repeat singers and 1-click re-queue of past tracks. Works without backend changes but limited to a single browser/device.
• Feature request: generate playlist of all played songs in one sitting #213 — Generate a playlist/log of all played songs in one sitting (per-day export).
• Singer / Song Play history #90 — Singer/song play history with configurable retention and running totals per singer.
• User Song History #209 — User-facing song history: let a named singer see what they sang in past sessions and re-queue from that list.

Feature comparison across requests

Feature	#746 (PR)	#790 (PR)	#213	#90	#209	v1 Plan
Server-side play recording	✅		✅	✅	✅	✅
Sessions (named time brackets)	✅		✅		✅	✅
History page (play log + filters)	✅		✅	✅	✅	✅
KJ singer auto-complete (admin)		✅				✅
Rankings (top songs/performers)	✅			✅		✅
CSV/playlist export			✅			✅
Performers page	✅					Deferred
Performer aliases / merging	✅					Deferred
1-click re-queue from history		✅			✅	Deferred
User-facing "my past songs"					✅	Deferred
Configurable retention / auto-purge				✅		Deferred

Proposed Approach

Build on the existing KaraokeDatabase and songs table with a phased approach. The entire feature is admin-only.

v1 PR — Core play history

Delivers the features requested across the most sources:

• sessions and plays tables added to the existing SQLite database via versioned schema migration, with FK to songs
• Sessions — KJ explicitly starts and stops named sessions ("Friday Night Karaoke", "Mike's Birthday") from the admin History page. Plays are only recorded while a session is active.
• Automatic play recording — PlayHistoryManager listens to playback events and records plays with performer name, song, and timestamps
• History page (admin-only) — paginated play log with session filtering, delete controls
• Rankings page (admin-only) — top songs, top performers, busiest sessions
• KJ singer auto-complete (admin-only) — when the KJ queues a song on behalf of a singer, past performer names are suggested via a <datalist>. Regular users continue to use their cookie-stored name.
• CSV export — download a session's play log as a CSV file (satisfies Feature request: generate playlist of all played songs in one sitting #213)

Deferred to follow-up PRs

These features can be added without schema changes since the v1 schema supports them:

• Performers page — dedicated page for browsing performers and their play history
• Performer aliases / merging — performer_aliases table, merge UI, normalized lookups
• 1-click re-queue — re-add a past song to the queue from history
• User-facing "my past songs" — let singers browse their own history (partially covered by filtering the history page by performer)
• Configurable retention / auto-purge — automatic cleanup of old play data

Initial plan

play-history-v1-plan-2026-03-05.md