vynl/DESIGN.md

Vynl - AI Music Discovery

Tagline

"Dig deeper. Discover more."

What It Does

Import your playlists from any streaming platform, drop in a song or artist, and Vynl's AI finds music you'll love - from underground gems to hidden tracks from artists you already know. It tells you why you'll like it, not just what to listen to.

Target Audience

• Music lovers who feel stuck in algorithm bubbles
• People who use multiple streaming platforms
• Playlist curators
• Anyone who misses the feeling of discovering new music

Core Features

Free Tier

• Import 1 playlist (up to 50 songs)
• Search by artist or song
• 10 AI recommendations per day
• Basic "similar to" recommendations
• Export recommendations as text list

Pro Tier ($4.99/month)

• Unlimited playlist imports from all platforms
• Unlimited AI recommendations
• Deep analysis: mood, tempo, era, production style, lyrical themes
• "Go deeper" mode - find underground/indie artists in the same space
• "Time machine" - find music from a specific era that matches your taste
• "Mood shift" - "I like this but want something darker/faster/mellower"
• Export playlists directly back to Spotify/Apple Music/YouTube Music/Tidal
• Recommendation history and saved discoveries
• "Why you'll like this" AI explanations
• Cross-platform playlist sync

Platform Support

Import From

• Spotify (API - OAuth)
• Apple Music (MusicKit API)
• YouTube Music (ytmusicapi)
• Tidal (API)
• Last.fm (scrobble history)
• Manual entry (paste song/artist name)
• CSV/text file upload

Export To

• Spotify (create playlist via API)
• Apple Music (create playlist via MusicKit)
• YouTube Music (create playlist via API)
• Tidal (create playlist via API)
• CSV/shareable link

Tech Stack

Backend

• Python 3.12+ / FastAPI
• PostgreSQL (users, playlists, recommendations, history)
• Redis (caching, rate limiting, session)
• Celery (async playlist analysis, background jobs)

Frontend

• React 19 + TypeScript + Vite
• Tailwind CSS
• Mobile: React Native or PWA (progressive web app)

AI/ML

• Claude API for intelligent recommendations with explanations
• Spotify Audio Features API (tempo, energy, danceability, valence, acousticness)
• MusicBrainz API (artist relationships, genres, tags)
• Last.fm API (similar artists, tags, listener stats)
• Audio embeddings for sonic similarity (optional - Essentia/Librosa)

Infrastructure

• Azure App Service or self-hosted (like BillWise)
• Stripe for payments
• OAuth 2.0 for all streaming platform connections

AI Recommendation Engine

How It Works

User imports playlist or enters song/artist
         │
         ▼
Gather metadata from all sources:
  - Spotify: audio features (tempo, key, energy, mood)
  - MusicBrainz: genres, relationships, tags
  - Last.fm: similar artists, listener overlap
  - Lyrics analysis (optional)
         │
         ▼
Build "taste profile":
  - Genre distribution
  - Mood/energy preferences
  - Era preferences
  - Production style (acoustic vs electronic, raw vs polished)
  - Lyrical themes
         │
         ▼
Claude AI analyzes profile + user request:
  "Based on your love of [specific patterns], here are artists
   you likely haven't heard that share [specific qualities]"
         │
         ▼
Filter and rank recommendations:
  - Exclude what user already has
  - Prioritize lesser-known artists (discovery factor)
  - Include preview links
  - Generate "why you'll like this" for each

Example Prompts to Claude

• "My playlist is 60% indie rock, 20% shoegaze, 20% post-punk. Find me 10 artists I probably haven't heard."
• "I love the production style of Tame Impala but want something with female vocals and darker lyrics."
• "Find songs from the 80s that match the energy of my playlist but aren't the obvious hits."

Data Model

Users

• id, email, name, plan (free/pro), created_at
• connected_platforms (spotify_token, apple_token, etc.)

Playlists

• id, user_id, platform_source, name, track_count, imported_at
• taste_profile (JSON - computed analysis)

Tracks

• id, title, artist, album, isrc
• spotify_id, apple_id, youtube_id, tidal_id
• audio_features (tempo, energy, key, etc.)
• genres, tags, mood

Recommendations

• id, user_id, source_playlist_id, recommended_track_id
• reason (AI explanation), score, created_at
• user_feedback (liked/disliked/saved)

Discovery Sessions

• id, user_id, query, mode (similar/deeper/mood/era)
• results, created_at

Monetization

Free

• Limited to 10 recommendations/day
• 1 playlist import
• No export to streaming platforms
• Ads (tasteful, music-related)

Pro ($4.99/month or $39.99/year)

• Unlimited everything
• All export features
• Priority AI processing
• No ads

Potential Revenue Streams

• Affiliate links to streaming platforms
• Artist promotion (paid placement in "sponsored discovery")
• API access for other apps
• Data insights for labels (anonymized trends)

Competitive Landscape

Product	What It Does	Vynl Advantage
Spotify Discover Weekly	Algorithm-based weekly playlist	Only works within Spotify, no cross-platform
Last.fm	Scrobble tracking + similar artists	No AI explanations, stale recommendations
EveryNoise	Genre exploration map	Academic, not personalized
Maroofy	Song similarity search	Single song only, no playlist analysis
Chosic	Spotify playlist analyzer	Spotify only, basic recommendations
Discoverify	Spotify discovery tool	Spotify only

Vynl's edge: Cross-platform + AI that explains WHY + deep/underground discovery + mood/era controls

MVP (v1.0) Scope

Must Have

• User auth (email + OAuth)
• Spotify playlist import
• Manual song/artist search
• AI recommendations (Claude API)
• "Why you'll like this" explanations
• Basic taste profile display
• Save/bookmark recommendations
• Responsive web app

Nice to Have (v1.1)

• Apple Music import/export
• YouTube Music import/export
• Export playlist to Spotify
• "Go deeper" underground mode
• Mood shift controls

Future (v2.0)

• Tidal, Last.fm, Deezer support
• Mobile app (React Native)
• Social features (share discoveries, follow curators)
• "Listening rooms" - real-time shared discovery sessions
• Artist dashboard (see who's discovering your music)

Brand Identity

• Name: Vynl
• Vibe: Warm, analog nostalgia meets modern AI
• Colors: Deep purple/violet (#7C3AED) + warm cream (#FFF7ED) + charcoal (#1C1917)
• Font: Something with character - not sterile tech (Inter for body, custom display font)
• Logo: Stylized vinyl record with AI circuit pattern in the grooves
• Voice: Music-nerd friendly, never pretentious, excited about discovery