Statly 🎵

An open-source alternative to stats.fm - A music statistics platform for Spotify users. Track your listening habits, discover your top tracks and artists, and analyze your music preferences over time.

Features

• 🎧 Top Tracks & Artists - View your most played music across different time periods (4 weeks, 6 months, all time)
• 📊 Listening Statistics - Detailed analytics of your music consumption with interactive charts
• � Data Visualization - Beautiful charts showing listening trends, genre distribution, and activity patterns
• �🕒 Recently Played - Track your recent listening history with daily activity graphs
• 🎨 Modern UI - Clean, responsive design built with Tailwind CSS
• 🔒 Privacy First - Your data stays yours, fully transparent and open-source
• 📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile

Tech Stack

• Framework: Next.js 14 (App Router)
• Authentication: NextAuth.js with Spotify OAuth
• Database: PostgreSQL with Prisma ORM
• Styling: Tailwind CSS
• Data Fetching: SWR for efficient caching
• API: Spotify Web API
• TypeScript: Full type safety

Prerequisites

• Node.js 18+ and npm
• PostgreSQL database
• Spotify Developer Account

Getting Started

1. Clone the repository

git clone https://github.com/yourusername/statly.git
cd statly

2. Install dependencies

npm install

3. Set up Spotify Developer Account

1. Go to Spotify Developer Dashboard
2. Create a new application
3. Add http://localhost:3000/api/auth/callback/spotify to Redirect URIs
4. Copy your Client ID and Client Secret

4. Configure environment variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

Edit .env:

DATABASE_URL="postgresql://user:password@localhost:5432/statly"

NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key-here"

SPOTIFY_CLIENT_ID="your-spotify-client-id"
SPOTIFY_CLIENT_SECRET="your-spotify-client-secret"

Generate a secure NEXTAUTH_SECRET:

openssl rand -base64 32

5. Set up the database

npx prisma generate
npx prisma db push

6. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

Project Structure

statly/
├── prisma/
│   └── schema.prisma          # Database schema
├── src/
│   ├── app/
│   │   ├── api/               # API routes
│   │   │   ├── auth/          # NextAuth configuration
│   │   │   └── spotify/       # Spotify API endpoints
│   │   ├── dashboard/         # Dashboard page
│   │   ├── top-tracks/        # Top tracks page
│   │   ├── top-artists/       # Top artists page
│   │   ├── recent/            # Recent tracks page
│   │   ├── layout.tsx         # Root layout
│   │   └── page.tsx           # Landing page
│   ├── components/            # React components
│   │   ├── Navigation.tsx
│   │   ├── TrackCard.tsx
│   │   ├── ArtistCard.tsx
│   │   └── ...
│   ├── lib/                   # Utilities
│   │   ├── prisma.ts          # Prisma client
│   │   └── spotify.ts         # Spotify API service
│   ├── types/                 # TypeScript types
│   └── styles/                # Global styles
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── next.config.mjs

Features in Detail

Dashboard

• Overview of your music statistics with key metrics
• Interactive charts showing top tracks ranking
• Genre distribution pie chart
• 7-day listening activity timeline
• Quick access to top tracks and artists
• Recent listening activity

Top Tracks

• View your most played songs
• Interactive bar chart showing track rankings
• Filter by time range (short, medium, long term)
• See album artwork and artist info

Top Artists

• Discover your favorite artists
• Genre distribution visualization
• View artist images and genres
• Filter by different time periods

Recently Played

• Track your listening history
• Daily listening activity chart
• See when each track was played
• Complete track and artist information

Deployment

Deploy to Vercel

1. Push your code to GitHub
2. Import your repository on Vercel
3. Add environment variables in Vercel dashboard
4. Deploy

Database Setup

For production, use a managed PostgreSQL service:

• Vercel Postgres
• Railway
• Supabase
• Neon

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Roadmap

• Data visualization with charts (listening trends over time)
• Genre breakdown and analysis
• Playlist generation based on top tracks
• Export statistics and reports
• Social features (share your stats)
• Mobile app (React Native)
• Support for other music platforms (Apple Music, etc.)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by stats.fm
• Built with Next.js
• Powered by Spotify Web API

Support

If you like this project, please give it a ⭐️ on GitHub!

For questions or issues, please open an issue on GitHub.