mirror of
https://github.com/nomadkaraoke/karaoke-gen.git
synced 2026-11-20 13:07:57 +09:00
docs: catalog API, community detection, and autocomplete (#452)
## Summary - Documentation for the song lookup autocomplete and community version detection feature shipped in PR #451 ## Changes - **docs/README.md**: Added feature status rows (song lookup autocomplete, community version detection) and recent changes entry - **docs/API.md**: New "Catalog (Song Lookup)" section documenting all 3 endpoints (`/api/catalog/artists`, `/api/catalog/tracks`, `/api/catalog/community-check`) with request/response examples - **docs/ARCHITECTURE.md**: Added karaoke-decide and KaraokeNerds to external services table, added `catalog_proxy_service.py` and `karaokenerds_service.py` to service modules table - **docs/LESSONS-LEARNED.md**: Added "Autocomplete UX: Less Is More" pattern (single autocomplete that overwrites both fields > dual autocompletes) ## Test plan - Docs-only change, no code modifications @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
1 parent
186b3dd7a9
commit
e788187351
4 files changed
+96
No files matched your search
+85
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user