Vynl - Personal Spotify Analytics

A Spotify analytics dashboard built to explore listening data, visualisation, and personal music stats.

Features

• Detailed Analytics: Track listening time, top artists, albums, and tracks
• Monthly Stats: Visualize your music journey over months
• Weekly Recaps: Get personalized weekly summaries of your listening habits
• Full History Import: Import your complete Spotify listening history
• Auto-Refresh: Set custom times for automatic stats updates
• Dark/Light Mode: Beautiful theme support with vintage vinyl aesthetic
• Vynl Print: Generate shareable summaries of your music taste

Tech Stack

• Framework: Next.js 16 with App Router
• Database: Supabase (PostgreSQL)
• Authentication: Supabase Auth
• Styling: Tailwind CSS v4 + shadcn/ui
• Charts: Recharts
• API: Spotify Web API

Quick Start

Prerequisites

• Node.js 18+ and pnpm (or npm if ya nasty)
• Supabase account (free tier works)
• Spotify Developer account

Installation

1. Clone the repository

   git clone https://github.com/codingboyblah/vynl.git
   cd vynl

2. Install dependencies

   pnpm install

3. Set up Supabase

   • Create a new project on Supabase
   • Go to the SQL Editor in your Supabase dashboard
   • Run the complete setup script: scripts/COMPLETE_DATABASE_SETUP.sql
   • This creates all tables, policies, functions, and indexes

4. Set up Spotify App

   • Go to Spotify Developer Dashboard
   • Create a new app
   • Add redirect URI: http://localhost:3000/api/spotify/callback
   • Copy your Client ID and Client Secret
   • Important: If your app is in Development Mode, add users to the User Management list or request Extended Quota Mode

5. Configure environment variables

   • Copy .env.example to .env.local
   • Fill in all required values:

     # Spotify
     SPOTIFY_CLIENT_ID=your_spotify_client_id
     SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
     NEXT_PUBLIC_SPOTIFY_CLIENT_ID=your_spotify_client_id
     
     # Supabase
     NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
     NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
     SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
     
     # Site URL
     NEXT_PUBLIC_SITE_URL=http://localhost:3000

6. Run the development server

   pnpm dev

7. Open your browser

   • Navigate to http://localhost:3000
   • Click "Open vynl" and connect your Spotify account

Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import the project in Vercel
3. Add all environment variables from .env.example
4. Update Spotify redirect URI to: https://yourdomain.com/api/spotify/callback
5. Deploy!

Other Platforms

Vynl works on any platform that supports Next.js:

• Netlify
• Railway
• Render
• Cloudflare Pages
• Self-hosted with Docker

How It Works

1. Connect Spotify: Authenticate with your Spotify account
2. Automatic Tracking: Vynl fetches your recently played tracks daily
3. Import History: Optionally import your complete Spotify listening history
4. View Stats: Explore your listening patterns, top artists, albums, and tracks
5. Weekly Recaps: Get personalized weekly summaries
6. Customize: Set your refresh time and preferences

Spotify Developer Mode Limitations

If your Spotify app is in Development Mode (default), only users added to the User Management list can connect. To allow anyone to use your app:

1. Go to Spotify Developer Dashboard
2. Select your app
3. Go to Settings → User Management
4. Add specific users, OR
5. Request Extended Quota Mode for public access

FAQ

Q: How often does Vynl update my stats?
A: By default, stats refresh daily. You can manually refresh or set a custom time.

Q: Can I import my full Spotify history?
A: Yes! Request your data from Spotify (takes up to 30 days), then import it in Settings. UPDATE: A new update has broken this feature. please someone pr a fix. thanks.

Q: Is my data private?
A: Yes. Your data is stored in your own supabase database. No one else can access it.

Q: Does this work with Spotify Free?
A: Yes! vynl works with both free and premium Spotify accounts.

Q: How much does it cost?
A: vynl is completely free. Supabase and Spotify APIs are free for personal use.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - feel free to use for personal projects or modify as needed.

Support

For issues or questions:

• Open a GitHub issue
• Check existing documentation
• Review closed issues for solutions

---

Built for music lovers who want to understand their listening habits better