TuneBridge

TuneBridge is a production-oriented foundation for an accountless playlist transfer application.

Implemented

• Next.js App Router application using TypeScript strict mode and Tailwind CSS.
• Zod models for platforms, playlists, tracks, matches, conversion jobs, OAuth state, API input, and consent.
• Modular MusicPlatformAdapter interface with non-implemented real provider adapters.
• Pure matching engine v2 with deterministic staged scoring: ISRC, normalized title/primary artist, title/artist-set overlap, title/artists/duration, album/release-year assistance, and configurable fuzzy fallback.
• Matching metrics for exact, high-confidence, low-confidence, unmatched, and user override rates.
• Secure URL platform detection with HTTPS, credential, host allowlist, and playlist-shape checks.
• API route foundations for detection, job creation/status, cancellation, OAuth start/callback, universal links, and consent.
• Supabase migration for anonymous sessions, conversion jobs, playlists, tracks, matches, OAuth states, provider tokens, universal links, analytics, consent, and rate limits.
• Mobile-first dark UI for required pages and result/status surfaces.
• Advertising and consent placeholders without loading real advertising scripts.
• Unit tests, React Testing Library tests, Playwright test, and GitHub Actions CI.
• Real Spotify source/destination adapter using the Spotify Web API for playlist import, catalogue search, playlist creation, token refresh, and batched track insertion.
• Spotify Authorization Code with PKCE endpoints, cryptographic state, short expiration, single-use validation, secure cookies, and encrypted refresh-token storage abstraction.
• Real YouTube destination adapter using the official YouTube Data API v3 for search, duration enrichment, playlist creation, and playlist item insertion.
• Google OAuth with PKCE, offline refresh-token handling, encrypted refresh-token storage abstraction, disconnect endpoint, quota estimates, and review data for low-confidence/unmatched tracks.
• Benchmark fixture set with 120 representative matching cases and false-positive guardrails for covers, karaoke, sped-up, slowed/reverb, and mismatched live/acoustic/instrumental variants.

Mock Functionality

• DemoAdapter is available only when NEXT_PUBLIC_DEMO_MODE_ENABLED=true.
• Demo data is visibly labelled and deterministic for local development and automated tests.
• Production environment validation rejects enabled demo mode.

Planned Functionality

• Review UI actions wired to persist accept/reject/search-alternative/skip decisions into durable Supabase storage.
• Apple Music, Deezer, and future Tidal adapters.
• Supabase persistence for all API workflows.
• Universal link creation after real destination links exist.
• Supabase-backed token storage replacing the current in-memory foundation stores.

External Setup Required

• Supabase project URL, publishable key, and server-only secret key.
• Spotify developer app credentials.
• Google OAuth credentials and YouTube Data API access.
• Apple Music credentials.
• Deezer credentials.
• Production token encryption key.
• Optional AdSense publisher and slot IDs.

Commands

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e

With real Spotify and Google/YouTube credentials, Spotify-to-YouTube conversion is implemented through official APIs. YouTube Music is treated as standard YouTube playlists containing music videos or official audio uploads. Apple Music and Deezer conversion is not implemented yet.