How karaagexc/songless works
Songless is a browser-based music guessing game with Daily, Unlimited, and timed Blitz play. The player selects a mode and filters or imports a playlist; the game obtains a track through its catalog/API services, plays short listening windows, evaluates guesses, then records results and offers shareable output. The server also supports discovery, search, streaming, artwork, announcements, and a separately maintained shared catalog with refresh and classification. UI-to-API details are only partially sampled, so unsampled route wiring is shown only where README or sampled calls establish it.
Main entry points: App.tsx Game orchestration · musicApi.ts Music API client · catalogDailyRefresh.ts Daily catalog refresh · catalogStore.ts Catalog storage
Components 34
Game experience
- Game page
pages/index.tsx - Game orchestration
src/App.tsx - Game UI
src/components/BlitzSetupModal.tsx - Era and genre
src/components/DecadeGenreModal.tsx - Artist picker
src/components/ArtistPickerModal.tsx - Playlist import UI
src/components/PlaylistImportPanel.tsx - Results and stats UI
src/components/StatsModal.tsx - First-time guide
src/components/FirstTimeGuide.tsx
Browser services
- Music API client
src/services/musicApi.ts - Catalog queue
src/services/catalogQueue.ts - Audio playback
src/services/audioService.ts - Local stats and history
src/services/statsService.ts - Playlist sessions
src/services/playlistService.ts - PNG sharing
src/utils/shareSignal.ts - Song identity
src/utils/songIdentity.ts
API and providers
- Search route
pages/api/search.ts - Artwork route
pages/api/artwork.ts - Audio stream route
pages/api/stream.ts - Playlist route
pages/api/playlist.ts - Announcement route
pages/api/announcements.ts - Provider catalog
server/musicCatalog.ts - Spotify artwork
server/spotifyArtwork.ts - Refresh route
pages/api/catalog-refresh.ts
Shared catalog
- Catalog browse
server/catalogBrowse.ts - Catalog storage
server/catalogStore.ts - Catalog sources
server/catalogSources.ts - Catalog enrichment
server/catalogEnrichment.ts - Catalog reconciliation
server/catalogReconcile.ts - Daily catalog refresh
server/catalogDailyRefresh.ts - Catalog coverage
server/catalogCoverage.ts
Other components
- Player
- Supabase
- Spotify
- iTunes
Connections 42
- Player → Game page: opens
- Game page → Game orchestration: loads client-only
- Player → Game orchestration: plays and guesses
- Game orchestration → Catalog queue: requests candidate
- Game orchestration → Music API client: requests songs
- Music API client → Catalog browse: browses
- Game orchestration → Audio playback: controls playback
- Game orchestration → Local stats and history: records results
- Game orchestration → Playlist sessions: saves session
- Game orchestration → PNG sharing: creates share image
- Game orchestration → Game UI: renders
- Game orchestration → Era and genre: renders
- Game orchestration → Artist picker: renders
- Game orchestration → Playlist import UI: renders
- Game orchestration → Results and stats UI: renders
- Game orchestration → First-time guide: renders
- Game orchestration → Song identity: matches tracks
- Local stats and history → Song identity: canonicalizes
- Playlist sessions → Song identity: deduplicates tracks
- Music API client → Search route: requests search
- Search route → Provider catalog: calls search
- Provider catalog → iTunes: queries provider
- Playlist sessions → Playlist route: imports playlist
- Playlist route → Spotify: fetches playlist
- Music API client → Audio stream route: requests audio
- Audio playback → Audio stream route: loads preview
- Music API client → Artwork route: requests artwork
- Artwork route → Spotify artwork: resolves artwork
- Spotify artwork → Spotify: fetches artwork
- Game orchestration → Announcement route: checks updates
- Catalog queue → Catalog browse: selects catalog songs
- Catalog browse → Catalog storage: reads snapshot
- Refresh route → Daily catalog refresh: triggers refresh
- Daily catalog refresh → Catalog sources: imports sources
- Daily catalog refresh → Catalog enrichment: enriches metadata
- Daily catalog refresh → Catalog reconciliation: reconciles catalog
- Daily catalog refresh → Catalog storage: publishes snapshot
- Catalog sources → Spotify: discovers candidates
- Catalog enrichment → iTunes: resolves metadata
- Catalog storage → Supabase: persists catalog
- Catalog coverage → Catalog storage: analyzes snapshot
- Refresh route → Supabase: uses shared lease