## Summary - Remove the deprecated beta enrollment system (endpoints, models, email templates, admin UI, rate limits) — ~20 files cleaned - Remove legacy count-based YouTube upload tracking from rate_limit_service and dead blocklist methods - Add GCP Cloud Monitoring integration to cross-reference YouTube API quota usage with Firestore tracking - Add drift detection (alerts when GCP reported vs Firestore tracked differs >10%) - Display GCP quota data in admin rate-limits dashboard ## Changes ### Backend (15 files) - **Removed:** 5 beta endpoints, `BetaTesterStatus` enum, beta User fields, beta email templates, `validate_email_for_beta()`, deprecated YouTube/beta rate limit methods, dead blocklist CRUD methods - **Added:** `get_gcp_quota_usage()` to `YouTubeQuotaService` with Cloud Monitoring API query, 5-min cache, and drift detection - **Updated:** Rate limits API response model with GCP quota fields (`gcp_quota_available`, `gcp_quota_units_consumed`, `quota_drift`, `quota_drift_alert`) ### Frontend (11 files) - **Deleted:** `frontend/app/admin/beta/page.tsx` (entire beta admin page) - **Removed:** Beta sidebar nav, layout breadcrumb, admin stats card, beta types/API methods, legacy YouTube stats cards - **Added:** GCP Cloud Monitoring section in rate-limits page showing reported usage, delay, and drift alerts ### Tests (4 files) - Removed 8 obsolete tests for deprecated methods - Created `test_gcp_quota_monitor.py` with 10 tests covering GCP quota querying, caching, fallbacks, and drift detection - Updated mock data and assertions across test files ### Docs (3 files) - Removed beta endpoint docs from API.md, added GCP quota fields - Updated ARCHITECTURE.md with Cloud Monitoring integration - Removed beta program section from PRODUCT-VISION.md ## Test plan - [x] All 2265 backend tests pass (1 pre-existing failure unrelated) - [x] All 516 frontend Jest tests pass - [x] New GCP quota monitor tests cover success, caching, fallbacks, drift alerts - [ ] Verify admin rate-limits page no longer shows beta/legacy cards - [ ] Verify GCP quota section shows "unavailable" gracefully when monitoring data not yet populated @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
10 KiB
Product Vision
What is Nomad Karaoke?
Nomad Karaoke is a karaoke video generation platform that creates professional-quality karaoke videos from any song in under 10 minutes. Founded by Andrew Beveridge and based in South Carolina, it combines state-of-the-art AI for audio separation and lyrics synchronization with human review to produce accurate, polished results.
Mission: Make any song singable by automating the complex, time-consuming process of creating karaoke videos.
The Problem
Creating high-quality karaoke is surprisingly difficult:
-
Vocal Removal: Separating vocals from instrumentals without artifacts requires sophisticated AI models and significant compute power.
-
Lyrics Accuracy: Getting the right lyrics, with correct spelling, formatting, and line breaks, is error-prone when scraping from various sources.
-
Timestamp Synchronization: Aligning each word or syllable to the exact moment in the audio is the hardest part. No existing tool does this reliably for all songs.
-
Multiple Formats: Professional karaoke needs multiple output formats (MP4, MKV, CDG) at various resolutions, with proper encoding.
-
Distribution: Uploading to YouTube with proper metadata, sharing to cloud storage, and notifying users adds complexity.
Existing solutions either produce poor quality (DIY tools), cost too much time ($50-100/track from manual services), or don't exist at all for many songs.
Target Audiences
1. Individual Karaoke Enthusiasts
People who want custom karaoke for songs not available in commercial libraries - for home parties, personal practice, or sharing with friends.
2. Professional KJs and Venues
Karaoke DJs ("KJs") and bars who need to fulfill on-demand song requests. When a patron asks for a song that isn't in the library, generating it in under 10 minutes means it can be ready within 1-2 performances.
3. Commercial Karaoke Producers (B2B)
Companies that produce karaoke tracks at scale for distribution. They have their own instrumentals, branding, and distribution channels - they need automated generation infrastructure that can handle 5,000+ tracks with custom theming.
Technical Approach
The system uses a multi-stage pipeline:
Input (audio + metadata)
│
├──────────────────────────────────────┐
│ │
v v
┌───────────────────┐ ┌───────────────────┐
│ Audio Separation │ │ Lyrics Processing │
│ (Modal GPU) │ │ (AudioShake API) │
│ │ │ │
│ • Clean vocal │ │ • Fetch reference │
│ removal │ │ lyrics │
│ • Backing vocal │ │ • Transcribe with │
│ options │ │ timestamps │
└─────────┬─────────┘ │ • AI correction │
│ │ • HUMAN REVIEW │
│ └─────────┬─────────┘
│ │
└──────────────┬───────────────────┘
v
┌───────────────────┐
│ Video Generation │
│ • Title screen │
│ • Synced lyrics │
│ • End screen │
└─────────┬─────────┘
│
v
┌───────────────────┐
│ Output & Distro │
│ • Multiple formats│
│ • YouTube upload │
│ • Cloud storage │
└───────────────────┘
Why Human Review?
The hardest unsolved problem in karaoke generation is reliable lyrics transcription with accurate timestamps. Current approaches:
- Whisper (open source): Free, but inconsistent for sung audio. Works well ~60% of the time, poorly the rest.
- AudioShake (paid API): Proprietary lyrics transcription model specifically trained for music. Much more accurate/consistent than Whisper.
- Agentic AI Correction: LLM-based system that compares transcriptions against reference lyrics, fixing errors and improving sync. Costs tokens but catches many issues.
Even with the best AI, some songs have tricky timing, unusual pronunciations, or ambiguous lyrics. Human review catches these edge cases and ensures quality. The review UI lets users:
- Correct misspelled words
- Adjust word/line timing
- Fix line breaks and formatting
- Preview changes in real-time
Open Source Philosophy
All code is open source (MIT license) because:
- Community: Others can learn from, contribute to, and build upon the work
- Transparency: Users can see exactly how their data is processed
- Self-hosting option: Technical users can run their own instance
However, reliable fully-automated generation requires:
- AudioShake API: ~$0.50-1.00 per track for high-quality transcription
- LLM tokens: ~$0.50-1.00 for agentic correction workflow
- GPU compute: ~$0.20-0.50 for audio separation on Modal
- Infrastructure: Cloud Run, Firestore, GCS, etc.
Cost per track: ~$2-3 for fully-automated processing, making a paid service necessary to sustain development.
The open source CLI (karaoke-gen) works with local processing and free APIs for users willing to accept lower reliability and do more manual correction. The hosted service (gen.nomadkaraoke.com) provides the premium, reliable experience.
Business Model
Credit-Based Pricing
Users purchase credits to generate karaoke videos:
| Credits | Price | Per Track | Savings |
|---|---|---|---|
| 1 | $5 | $5.00 | - |
| 3 | $12 | $4.00 | 20% |
| 5 | $18 | $3.50 | 30% |
| 10 | $30 | $3.00 | 40% |
This is significantly cheaper than:
- Manual services: $10-50 per track
- Hiring a studio: $100+ per track
- DIY tools + your time: Hours of frustration
B2B / White-Label
Commercial producers pay for API access or custom integration to generate tracks at scale with their own branding, instrumentals, and distribution.
Current State (December 2025)
What Works
- Audio upload and separation (Modal API)
- Lyrics transcription (AudioShake API)
- Agentic AI correction (Gemini 3 Flash via Vertex AI)
- Human lyrics review (React UI)
- Preview video generation
- Instrumental selection (clean vs. with backing vocals)
- Multi-format encoding (4K, 720p, lossless, lossy)
- Token-based authentication
- Magic link authentication
- Payment flow (Stripe)
- YouTube upload integration
- Dropbox/Google Drive distribution
Known Limitations
- CDG format needs additional style configuration
- Very long audio (>10 min) may timeout
- Some edge cases in lyrics timing still need manual correction
Product Ecosystem
Active Products
- gen.nomadkaraoke.com - Web application for generating karaoke videos (includes landing page, pricing, and payment)
- karaoke-gen CLI - Local command-line tool for power users
- karaoke-gen-remote CLI - CLI that uses the cloud backend
- Nomad Karaoke YouTube Channel - Hosts generated videos for users
Future Products
-
KaraokeHunt (revival planned) - Song discovery app that analyzes streaming history to suggest songs you'd enjoy singing. Previously launched as a separate product; will be rebranded and integrated with the karaoke generator.
-
New nomadkaraoke.com Homepage - Replace the legacy static site with a modern landing page showcasing the generator (currently deployed from
nomadkaraoke/public-websiterepo).
Differentiators
vs. DIY Tools (Whisper + Demucs + manual editing)
- Quality: AudioShake's proprietary model beats open source transcription
- Speed: 10 minutes vs. hours of manual work
- Convenience: One-click generation with human review UI
vs. Manual Services ($10-50/track)
- Price: $3-5 per track
- Speed: Minutes instead of days
- Scale: Generate as many as you need, when you need them
vs. Other Automated Tools
- Accuracy: Human review catches AI errors
- Output quality: 4K video, multiple formats, proper encoding
- Distribution: YouTube upload, cloud storage, notifications built in
- Open source: Transparency and community contributions
Technical Stack
- Backend: FastAPI on Google Cloud Run
- Frontend: Next.js on Cloudflare Pages
- Database: Firestore
- Storage: Google Cloud Storage
- Secrets: Google Secret Manager
- Audio Separation: Modal (GPU compute)
- Lyrics Transcription: AudioShake API
- AI Correction: Vertex AI (Gemini 3 Flash)
- Payments: Stripe
- Email: SendGrid
- IaC: Pulumi
- CI/CD: GitHub Actions (self-hosted runner on GCP)
Roadmap
Near-term
- Public launch of gen.nomadkaraoke.com
- New marketing homepage at nomadkaraoke.com
- B2B API for commercial producer integration
- Bulk generation features for high-volume clients
Medium-term
- KaraokeHunt revival and integration
- Mobile-optimized experience
- Real-time generation status notifications
- Additional output format support
Long-term
- Karaoke Eternal integration (community request)
- On-premises deployment option for venues
- Live karaoke event features
Links
- Web App: https://gen.nomadkaraoke.com
- API: https://api.nomadkaraoke.com
- GitHub: https://github.com/nomadkaraoke/karaoke-gen
- YouTube Channel: https://www.youtube.com/@nomadkaraoke
- Updates Signup: https://nomadkaraoke.kit.com/
- Contact: https://cal.com/beveradb
About the Founder
Andrew Beveridge is a software engineer based in South Carolina who runs a weekly karaoke night and built Nomad Karaoke to solve his own problem: wanting to sing songs that don't exist as karaoke. What started as a personal tool evolved into a platform that can help anyone create professional karaoke for any song.