How to Clone Shazam

Create a Shazam-style music recognition app called TuneTrace using Next.js (App Router), Tailwind, Prisma + SQLite. Recognition via the AudD API (or ACRCloud) called from a server route.

## What to build
A mobile-first PWA: a big listen button records mic audio in the browser, a server route forwards it to the recognition API, and the match is shown on a rich result card and saved to history. Plus weekly charts aggregated across users.

## Screens
- / (Recognize): dark fullscreen, giant circular pulse button with three states (idle / listening with animated ripples + countdown / matching shimmer); bottom tab bar (Tune, History, Charts, Profile)
- Result sheet: slides up over the home screen - album art hero with blurred backdrop, title, artist, album + year, streaming link buttons (Spotify / Apple Music / YouTube deep links from the API response), favorite heart, share via navigator.share, 'Try again'
- /history: day-grouped list with thumbnail, title, artist, time; client-side search filter; favorite toggle and delete per row; empty state with a nudge to tag a first song
- /charts: top-20 list for the current week with rank, movement arrow vs last week, art, title, artist, match count
- /profile: anonymous by default with local history; mock sign-in that adopts local history; stats (total tags, unique artists); clear-history button

## Audio capture (must actually work)
- Use navigator.mediaDevices.getUserMedia({ audio: true }) + MediaRecorder; record 8 seconds (audio/webm), stop tracks afterward to release the mic
- POST the blob to /api/recognize as multipart form data
- /api/recognize: forwards the file to the AudD API with process.env.AUDD_API_TOKEN (never expose it client-side); maps the response to { title, artist, album, releaseYear, artworkUrl, links { spotify, appleMusic, youtube } }; returns 404-style JSON on no match
- On success: create a Match row and upsert this week's ChartEntry (increment matchCount)
- Add a MOCK_RECOGNITION=true env mode that returns one of 10 canned tracks after a 2s delay, so the app fully demos without an API key

## Prisma schema
User (id, email unique nullable, displayName, createdAt), Match (id, userId nullable, clientId for anonymous devices, trackTitle, artist, album, releaseYear, artworkUrl, spotifyUrl, appleMusicUrl, youtubeUrl, isFavorite, recognizedAt), ChartEntry (id, weekStart, trackKey, trackTitle, artist, artworkUrl, matchCount, unique [weekStart, trackKey])

## Logic
- Anonymous users get a clientId in localStorage; their matches use it and merge into userId on sign-in
- Rate-limit /api/recognize to 5 requests/minute per clientId (in-memory map is fine here)
- Charts page computes ranks by sorting matchCount for the current weekStart and compares to the prior week for movement arrows
- No-match responses render the coaching card (closer to speaker, less talking) with a Retry button

## Style
Dark and electric: #0B1026 background with a radial violet glow, #7C5CFF primary, #2DD4BF success accent, #94A3B8 secondary text, rounded-2xl, Inter font. The listen button is the hero: 170px circle, gradient fill, animated ripple rings while recording (CSS keyframes), satisfying spring on the result sheet.

Seed: 12 history matches across 4 days for the demo client, 20 chart entries for this week and 15 for last week (so movement arrows render), 3 favorites. Make sure the mock mode is on by default.

Build a production-quality Shazam-style music recognition PWA. The recognition pipeline is third-party (ACRCloud or AudD) - your engineering problems are clean audio capture, a provider-agnostic backend, cost control and a delightful sub-10-second loop.

## Stack
- Next.js 14 App Router + TypeScript + Tailwind + shadcn/ui; Framer Motion for the listen-button and result-sheet animations
- PostgreSQL via Prisma; Supabase auth (anonymous session upgradeable to email/OAuth)
- Recognition behind an interface: RecognitionProvider { recognize(audio: Buffer, mime: string): Promise<MatchResult | null> } with ACRCloudProvider, AudDProvider and MockProvider implementations selected by env - the mock returns fixtures so CI and local dev never need keys

## Audio capture layer
- lib/audio/recorder.ts: wraps getUserMedia + MediaRecorder; records 8s (configurable), emits a level meter via AnalyserNode for the ripple animation amplitude, hard-stops and releases tracks on completion/unmount
- Handle the permission lifecycle explicitly: prompt-on-first-tap with a pre-permission explainer, denied state with browser-specific re-enable instructions, and an unsupported-browser fallback (file upload of a recording)
- Downsample/transcode client-side if needed; keep payloads under ~300KB

## API & cost control
- POST /api/recognize: validates size/mime with Zod, rate-limits per session (5/min, 50/day) with explicit 429 + Retry-After surfaced in the UI, calls the provider, normalizes to a canonical MatchResult (title, artist, album, year, artworkUrl, isrc, links), persists a Match row and chart aggregate in one transaction
- Cache provider responses by audio fingerprint hash for idempotent retries; log provider latency and no-match rate (these are your two product-health metrics)
- Recognition spend is your COGS: add a daily budget guard that flips the API to mock + 'try again later' messaging rather than overspending

## Schema
users, sessions (anonymous clientId → userId adoption on sign-in), matches (denormalized track fields + isrc + provider + confidence, indexed on (user_id, recognized_at desc)), chart_entries (week_start, track_key unique per week, match_count), recognition_logs (provider, latency_ms, outcome) for the metrics dashboard.

## Implementation order
1. Provider interface + mock + /api/recognize with tests (fixtures for match, no-match, provider timeout)
2. Recorder lib + the listen screen: idle/listening/matching/result/no-match states as an explicit state machine (XState or a typed reducer - no boolean soup)
3. Result sheet with streaming deep links and share card (OG image route per match for link previews)
4. History with day grouping, search, favorites; anonymous→account merge
5. Charts: weekly aggregate query, movement vs prior week, public SSR page (SEO: 'most identified songs this week')
6. Real provider integration (ACRCloud first - it adds humming search later), budget guard, metrics page
7. PWA polish: manifest, install prompt, offline history (matches cached in IndexedDB)

## Quality bar
- Tap-to-result under 10s p50 with the real provider; show elapsed time during matching after 4s ('still listening...')
- The mic is always released - assert no live tracks after every state transition (test with the permissions API)
- All four button states reachable and animated at 60fps; reduced-motion variant swaps ripples for a progress ring
- Zero provider keys in client bundles (verify with a build-output grep in CI)

Start with step 1; show me the RecognitionProvider interface, the normalized MatchResult type and the mock provider before continuing.

Design the complete UI for a Shazam-style music recognition app called TuneTrace. React + Tailwind + shadcn/ui + lucide-react. Aesthetic: night-club electric - deep navy #0B1026 background with radial glows, electric violet #7C5CFF primary, aqua #2DD4BF success accent, soft gray #94A3B8 secondary text, white headlines, rounded-2xl surfaces, Inter font. Mobile-first; the whole app should feel like it belongs at a concert.

## Screens

### 1. Recognize (home - the hero screen)
- Minimal chrome: wordmark top-left, history clock icon top-right
- Centered 170px circular button with a violet-to-blue gradient and an outer glow; label underneath: 'Tap to identify'
- Listening state: button scales up slightly, three concentric ripple rings animate outward continuously, label swaps to 'Listening...' with a seconds counter, a live waveform of 12 bouncing bars renders under the button
- Matching state: ripples stop, a shimmer sweep crosses the button, label 'Finding your song...'
- Bottom tab bar: Tune (bolt icon), History, Charts, Profile

### 2. Result sheet (slides up over home)
- Full-bleed album art top section with a blurred, darkened copy of the art as the sheet background
- Track title (bold, large), artist, album + year line in secondary gray
- Confidence/quality chip ('Strong match') in aqua
- Streaming buttons row: Spotify (filled pill, brand green), Apple Music (white pill), YouTube (outline) with logos
- Action row: heart (favorite, fills violet), share icon, 'Tag again' ghost button
- Drag handle on top; dismiss returns to the big button

### 3. No-match state
- Sad-but-friendly card on the home screen: broken-note illustration area, 'No match found', three coaching bullets (closer to the speaker, less background talk, try a longer chorus), large Retry button, small 'Save clip to try later' link

### 4. History
- Header with search input and a Favorites filter chip
- Day-grouped sections ('Today', 'Yesterday', dates); rows with 48px album art, title, artist, timestamp, and a chevron; swipe-left reveals Delete (red) and Favorite (violet) actions
- Tapping a row reopens its result sheet
- Empty state: ghost button illustration, 'Your music diary starts with one tap'

### 5. Charts
- Header: 'Most Tuned This Week' with a week-picker chevron
- Top 3 as podium cards with large art; positions 4–20 as ranked rows with movement arrows (aqua up, red down, violet NEW badge), title, artist, match count
- Share button that produces a story-format card preview (9:16, top-5 list on the gradient background)

### 6. Profile / settings
- Anonymous state: stats row (total tags, unique artists, day streak), sign-in card 'Keep your history forever' with email + Google buttons
- Signed-in: avatar, name, same stats, toggles (save location with tags, auto-open streaming app), privacy note card, Clear history (destructive style with confirm dialog)

Include the permission-prompt moment as a designed component: a small pre-dialog card explaining 'TuneTrace needs your mic for ~8 seconds to identify songs - clips are discarded after matching'. Fill all screens with realistic music content (varied genres, believable artists, album-art placeholders, plausible match counts). Fully responsive with the phone layout as the primary design.

Build a music recognition app (Shazam model) called TuneTrace: tap a button, identify the song playing, keep a history, and browse weekly charts. Recognition is done by a third-party API (AudD or ACRCloud) called from the backend - the app's job is the experience around it.

## Entities
- Match: user (nullable for anonymous), trackTitle, artist, album, releaseYear, artworkUrl, spotifyUrl, appleMusicUrl, youtubeUrl, confidence, isFavorite, recognizedAt
- ChartEntry: weekStart, trackKey (artist + title), trackTitle, artist, artworkUrl, matchCount - one row per track per week
- UserSettings: user, saveLocation (boolean), autoOpenStreaming (boolean)

## Roles
- Listener: identifies songs, browses history, favorites tracks, views charts; works anonymously, sign-in syncs history
- Admin: dashboard with recognitions per day, no-match rate, API usage count (cost control), and the ability to hide a chart entry

## Pages
1. Recognize (home): dark screen with one giant glowing circular button; tapping asks for microphone permission (with a one-line explainer first), records about 8 seconds, shows a pulsing 'Listening...' animation with ripple rings, then either the result or a friendly no-match card
2. Result: album art hero, track title, artist, album and year, buttons to open the song in Spotify, Apple Music and YouTube, favorite heart, share, and 'Tag again'
3. No match: 'No match found' with tips (move closer to the speaker, reduce talking) and a Retry button
4. History: the user's matches grouped by day, with search, favorite toggle and delete; tapping a row reopens its result view
5. Charts: top 20 most-identified tracks this week across all users, with rank movement arrows versus last week
6. Profile: stats (total tags, unique artists), sign-in to sync, privacy note ('audio clips are discarded after matching'), clear history
7. Admin: usage and cost dashboard

## Rules
- The recognition API key lives server-side only; the client sends audio to a backend function that calls the API and returns a normalized result
- Every successful match saves a Match row and increments the matching ChartEntry for the current week
- Limit each device to 5 recognition attempts per minute and 50 per day - recognition calls cost money; show a polite cooldown message when hit
- Anonymous histories live on the device and merge into the account at sign-in; history is private, charts are aggregate-only
- No-match results never look like errors: coach the user and offer retry
- Include a mock mode (no API key set) that returns one of 10 sample tracks after a 2-second delay so the whole app can be demoed

## Look & feel
Dark electric theme: deep navy #0B1026 background with a violet radial glow behind the button, electric violet #7C5CFF primary, aqua #2DD4BF success accents, gray #94A3B8 secondary text, large rounded cards, smooth pulse and slide-up animations. The tap-to-identify moment is the entire brand - make the button gorgeous.

Seed: 12 history matches spread over 4 days (3 favorited), 20 chart entries for this week and 15 for last week so movement arrows show, and mock mode enabled by default.