diff --git a/docs/API.md b/docs/API.md index 807ea844..5a582c96 100644 --- a/docs/API.md +++ b/docs/API.md @@ -324,6 +324,91 @@ Content-Type: application/json **Note**: For normal jobs, instrumental selection is now part of the combined review flow (see `/api/review/{job_id}/complete` above). +### Catalog (Song Lookup) + +Proxies to karaoke-decide's MusicBrainz + Spotify catalog for autocomplete, and scrapes karaokenerds.com for community karaoke version detection. All endpoints require authentication and are rate-limited (20 requests/minute per user). Results are cached in-memory (5 min for catalog, 1 hour for community checks). + +#### Search Artists + +```http +GET /api/catalog/artists?q=queen&limit=10 +``` + +Response: +```json +[ + { + "name": "Queen", + "mbid": "0383dadf-...", + "disambiguation": null, + "artist_type": "Group", + "spotify_id": "1dfeR4HaWDbWqFHLkxsg1d", + "popularity": 85, + "genres": ["rock"], + "tags": ["classic rock"] + } +] +``` + +#### Search Tracks + +```http +GET /api/catalog/tracks?q=bohemian&artist=queen&limit=10 +``` + +Response: +```json +[ + { + "track_name": "Bohemian Rhapsody - Remastered 2011", + "artist_name": "Queen", + "track_id": "4u7EnebtmKWzUH433cf5Qv", + "artist_id": "1dfeR4HaWDbWqFHLkxsg1d", + "popularity": 81, + "duration_ms": 354320, + "explicit": false + } +] +``` + +The `artist` query parameter is optional but recommended — filters results by artist for more relevant suggestions. + +#### Check Community Versions + +```http +POST /api/catalog/community-check +Content-Type: application/json + +{ + "artist": "Queen", + "title": "Bohemian Rhapsody" +} +``` + +Response: +```json +{ + "has_community": true, + "songs": [ + { + "title": "Bohemian Rhapsody", + "artist": "Queen", + "community_tracks": [ + { + "brand_name": "ObsKure Karaoke", + "brand_code": "OBSK", + "youtube_url": "https://www.youtube.com/watch?v=...", + "is_community": true + } + ] + } + ], + "best_youtube_url": "https://www.youtube.com/watch?v=..." +} +``` + +When `has_community` is true, the frontend shows a dismissible green banner suggesting the user check existing versions before creating a new one. + ### Audio Search #### Search for Audio diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7248f4a4..ec9567e8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -168,6 +168,8 @@ LyricsTranscriber LyricsTranscriber | YouTube API | Video upload | Optional | | SendGrid | Email notifications | Optional | | Cloud Tasks | Delayed task scheduling (idle reminders) | Optional | +| karaoke-decide | Song catalog (MusicBrainz + Spotify) for autocomplete | Optional | +| KaraokeNerds | Community karaoke version detection | Optional | *Flacfetch runs on a dedicated GCE VM with YouTube cookies and tracker access. Without it, YouTube downloads will fail due to bot detection on Cloud Run IPs. @@ -233,6 +235,8 @@ The Video Worker uses an orchestrator pattern to ensure all features work regard | `template_service.py` | GCS-backed email templates | | `job_notification_service.py` | Email orchestration (completion, reminders) | | `audio_transcoding_service.py` | Transcode FLAC → OGG Opus for review UI playback | +| `catalog_proxy_service.py` | Proxy to karaoke-decide catalog API (artist/track search) | +| `karaokenerds_service.py` | Scrape karaokenerds.com for community karaoke versions | ## Audio Source Download Flow diff --git a/docs/LESSONS-LEARNED.md b/docs/LESSONS-LEARNED.md index 72ed9bb9..39d63dd9 100644 --- a/docs/LESSONS-LEARNED.md +++ b/docs/LESSONS-LEARNED.md @@ -14,6 +14,9 @@ For UI that renders differently based on data (e.g., audio search result tiers), ### Filename Matching Normalization When comparing filenames to search titles, treat underscores/hyphens/dots as word separators BEFORE stripping non-alphanumeric chars. Also require a minimum substring length (3 chars) to prevent false matches like filename "K" matching title "KoREH". For non-Latin scripts (Hebrew, etc.), return an indeterminate result rather than a false match or false mismatch. +### Autocomplete UX: Less Is More (Mar 2026) +When adding autocomplete to a multi-field form (artist + title), a single autocomplete on the **primary search field** (title) that overwrites both fields on selection is better than separate autocompletes on each field. Two autocompletes feel "janky" — they compete for attention, spam the backend with double the requests, and confuse users about which one to interact with first. Instead: plain text input for the first field (artist), autocomplete on the second field (title) that only activates when the first field is filled, and selection overwrites both fields with canonical values. + --- ## Architecture Decisions diff --git a/docs/README.md b/docs/README.md index d6795c3c..74893a76 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,6 +31,8 @@ | E2E happy path test | Working (~20-25 min full pipeline) | | **White-label B2B portals** | Working (Vocal Star first tenant) | | **Private (non-published) tracks** | Working | +| **Song lookup autocomplete** | Working (via karaoke-decide catalog) | +| **Community version detection** | Working (via karaokenerds.com) | ## Known Issues @@ -42,6 +44,8 @@ ## Recent Changes +- **Song Lookup Autocomplete & Community Version Detection** (2026-03-03): Added song catalog integration to the job creation flow. Two features: (1) **Track autocomplete** on the title field provides canonical artist/title names from MusicBrainz + Spotify data via the karaoke-decide catalog API, improving text consistency for YouTube releases. Autocomplete activates when the artist field has a value; selecting a suggestion overwrites both artist and title with canonical names. (2) **Community version detection** checks karaokenerds.com for existing high-quality karaoke versions — if found, a dismissible green banner suggests the user check those versions first before spending credits. New backend: 3 endpoints (`/api/catalog/artists`, `/api/catalog/tracks`, `/api/catalog/community-check`) with per-user rate limiting (20 req/min) and in-memory TTL caching. New services: `catalog_proxy_service.py` (proxies to karaoke-decide), `karaokenerds_service.py` (scrapes karaokenerds.com). New frontend components: `AutocompleteInput` (reusable), `CommunityVersionBanner`. See [API.md](API.md#catalog-song-lookup). + - **Feedback-for-Credits** (2026-03-01): Added a feedback-for-credits mechanism available to all users (replaces the old beta-only feedback flow). Users who complete 2+ karaoke videos can submit product feedback (star ratings + text) to earn 2 free credits (total possible free credits: 4 — 2 welcome + 2 feedback). New endpoints: `GET /api/users/feedback/eligibility`, `POST /api/users/feedback`. The `/api/users/me` response includes `feedback_eligible: bool` so the frontend can show/hide prompts without an extra API call. Frontend shows a dismissible banner on the dashboard and a "Earn 2 Free Credits" menu item in the user dropdown when eligible. Feedback stored in `user_feedback` Firestore collection with duplicate prevention via `has_submitted_feedback` flag on user model. Welcome email updated with credit-focused messaging and feedback teaser. See [API.md](API.md#user-feedback-for-credits). - **Remove Beta Program from Homepage** (2026-03-01): Removed beta enrollment from landing page and replaced with prominent "2 Free Credits" messaging. Beta enrollment endpoint preserved for backward compatibility but no longer actively promoted. See PR #430.