Musical Bingo Creator 🎵 🎱
A desktop-first static SPA for creating, editing, printing, and hosting interactive Musical Bingo games.
Built with Vite, React, TypeScript, Tailwind CSS, @miquelt9/pc-ui, jsPDF, the YouTube IFrame API, and Deezer preview metadata.
Hosted serverless on GitHub Pages with zero backend dependencies and no Google account requirement.
✨ Features
- 🎧 Search or paste to build a deck:
- Search a song or artist with public catalog autocomplete (iTunes, then Deezer/MusicBrainz).
- Selecting a song searches YouTube with
Artist Title official audio.
- Paste a YouTube video or playlist URL if you already have the clip.
- Create provider-specific YouTube or Deezer decks. Deezer uses only the catalog’s short preview (normally 30 seconds), with no Deezer login.
- Paste a bulk song list (
Artist - Title, one per line) and match clips in the editor.
- Decks auto-save as you add songs from search.
- 🔍 Smart YouTube Matcher:
- YouTube search/metadata via the share Worker (curated Piped/Invidious backends server-side; narrow client fallback only if the Worker is down).
- Direct 1-click manual YouTube link or Video ID override with instant thumbnail validation.
- Cancellable batch auto-match and embed validation.
- Fix all songs for blocked videos — finds and replaces restricted clips from the deck or taskbar notice.
- Deezer tracks without a preview remain visible but cannot be added as playable tracks.
- 🛡️ Playability gating:
- Verifies YouTube embed permissions (via noembed.com) before hosting or printing cards.
- Surfaces blocked or unmatched tracks with a filterable list in the editor.
- ✂️ Interactive Track & Snippet Editor:
- Customizable start/end timestamps per track.
- Built-in singleton YouTube preview player with precision pause-at-end bounding.
- Hidden dual-slot HTML audio playback for Deezer previews, including pause/resume, chaining, and crossfade fallback.
- 🗄️ Local Persistence & Deck Portability:
- Save full decks in browser
localStorage.
- Export decks as portable
.json files.
- Import JSON decks with instant schema validation and pre-matched YouTube IDs.
- Share decks via an immutable short link (
#/share/abc123) or the native share sheet; JSON file export remains a fallback.
- Collaborate on playlists through a separate permanent link (
#/collab/<random-id>); anyone with the link can edit the playlist, check for updates, and safely merge changes.
- Shared decks retain their provider and can be converted into a new YouTube or Deezer copy with review for ambiguous matches.
- Dedicated Import page (
#/import) for .json files and Shared deck page (#/share/:id) for links.
- Built-in Deezer starter deck for testing without an external account; previews are matched automatically when the Worker is configured.
- Empty decks created by mistake are discarded automatically when you navigate away.
- 🖨️ Printable Bingo Cards & High-Resolution Vector PDF:
- Configurable 3×3 to 6×6 grids with adjustable bingo percent (how much of the deck appears on each card).
- Leftover squares become dark blocked tiles — no fixed center free space required.
- Clean browser print layout (
@media print).
- Every printed card includes a local verification QR in the top-right corner; the host can scan it to verify a horizontal line or Bingo without storing cards in Cloudflare KV.
- A compact card code is printed with the verification QR for camera-less host devices.
- Optional deck-sharing QR on each bingo card, with explanatory printed text; it is separate from verification.
- Printed cards explain that blank cells are ignored, lines are horizontal only, all filled cells count for Bingo, and only one line prize is awarded.
- Crisp vector PDF generator powered by
jsPDF for multi-card batch downloads.
- Export generated card sets as JSON for reuse.
- 🎙️ Interactive Host Game Dashboard:
- "Call Next Song" randomized non-repeating shuffle bag.
- Snippet playback controller (auto-pauses when clip ends).
- Inline video panel with optional draggable floating window.
- Crossfade overlap between songs, hide-answer mode (default), and auto-call-next chaining.
- Display mode (
#/deck/:id/display) — audience-facing progress view for a projector; syncs with the host via BroadcastChannel. Mirror the display window, not the full host UI.
- Answer reveal card with countdown/clip-finished trigger or manual toggle.
- Live searchable history log of called songs, local card verification by camera or card code, and celebratory Bingo confetti.
- Space toggles play/pause or calls the next song during a live game.
- Host session state persists in
sessionStorage across page refreshes.
- 🖥️ Classic desktop UI:
- Win9x-inspired shell via
@miquelt9/pc-ui with light, dark (Night Win9x), or system theme.
🚀 Setup & Development
1. Install Dependencies
npm install
@miquelt9/pc-ui is installed from GitHub and pinned to a full commit SHA in package.json because pc-ui has no tags or releases. To bump it, update that SHA in package.json and package-lock.json to the desired pc-ui commit and reinstall. To develop against a local checkout, clone pc-ui elsewhere and run npm link @miquelt9/pc-ui from this project after linking in pc-ui.
2. Create a deck
- Search a song or artist (autocomplete from iTunes/Deezer), pick the title, then choose the YouTube clip, or
- Paste a bulk song list (
Artist - Title, one per line), or
- Import a previously exported JSON deck / use the starter deck.
Then open Deck, trim clips if needed, resolve any blocked songs, print cards, and host the game.
3. Run Development Server
npm run dev
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
