# 🎵 Rolling Stone's Top 500 Albums

A beautiful, interactive web application showcasing Rolling Stone's greatest albums of all time with visual comparisons between the 2020 and 2023 rankings. Features a comprehensive theme system, Wikipedia integration, and modern responsive design.

![Top 500 Albums](https://img.shields.io/badge/Albums-500-brightgreen)
![Data Complete](https://img.shields.io/badge/Data-100%25%20Complete-success)
![Cover Art](https://img.shields.io/badge/Cover%20Art-500%20Albums-blue)
![Themes](https://img.shields.io/badge/Themes-8-purple)
![Wikipedia](https://img.shields.io/badge/Wikipedia-Integrated-orange)
![Spotify](https://img.shields.io/badge/Spotify-Integrated-1db954)

## ✨ Features

### Core Functionality
- **Interactive Album Cards**: Browse all 500 albums with high-quality cover art
- **Ranking Comparisons**: See how albums moved between 2020 and 2023 rankings
- **Complete Metadata**: Full album information including artist, year, label, and descriptions
- **Wikipedia Integration**: Direct links to Wikipedia pages for each album
- **Spotify Integration**: Listen to albums directly on Spotify with one click
- **Sequential Navigation**: Next button on each album for easy browsing
- **Search & Filter**: Easy navigation with search, status filters, and sorting options

### Modern UI/UX
- **8 Beautiful Themes**: Gruvbox (default), Basic Blue, Dark, Gruvbox Dark, Dracula, Nord, Solarized, Arc
- **Theme Persistence**: Your preferred theme is saved automatically
- **Responsive Design**: Optimized layout for desktop, tablet, and mobile devices
- **Clean SVG Icons**: Modern iconography throughout the interface
- **Jump-to-Rank**: Quick navigation to any album by rank
- **Shareable URLs**: Bookmark and share specific albums or filtered views

## 🚀 Live Demo

Open `index.html` in your browser to explore the collection, or serve it locally:

```bash
python -m http.server 8000
# Then visit http://localhost:8000
```

## 📊 Data Sources

- **2020 Rankings**: Rolling Stone's original 500 Greatest Albums list
- **2023 Rankings**: Updated rankings from Rolling Stone's revised list
- **Album Information**: Comprehensive metadata including release info and descriptions
- **Cover Art**: High-quality album artwork sourced from iTunes API

## 🎨 What's Included

### Core Files
- `index.html` - Main web application
- `styles.css` - Beautiful, responsive styling
- `script.js` - Interactive functionality
- `favicon.svg` - Custom music note favicon

### Data Files
- `top_500_albums_2023.csv` - Complete dataset with 100% metadata coverage
- `rolling_stone_top_500_albums_2020.csv` - Original 2020 rankings
- `wikipedia_top_500_albums.csv` - Wikipedia sourced data for comparison
- `wikipedia_urls_mapping.json` - Accurate Wikipedia URL mappings for all albums
- `spotify_urls_mapping.json` - Spotify album URL mappings for streaming integration

### Assets
- `covers/` - 500 high-quality album cover images (rank_XXX_Artist_Album.jpg)

### Utilities
- `scripts/` - Python scripts for data processing and maintenance

## 🛠️ Scripts

The repository includes various Python utilities for data management:

| Script | Purpose |
|--------|---------|
| `compare_top500_albums.py` | Generate the main comparison dataset |
| `merge_descriptions.py` | Merge album descriptions from multiple sources |
| `download_all_covers.py` | Download album artwork from iTunes API (500/500 success) |
| `add_missing_info.py` | Add metadata for albums missing information |
| `fill_missing_from_wikipedia.py` | Research and add Wikipedia-sourced descriptions |
| `extract_wikipedia_urls.py` | Extract accurate Wikipedia URLs for album pages |
| `extract_spotify_urls.py` | Extract Spotify URLs using the Spotify Web API |

## 📈 Data Quality

- **500/500 albums** with complete ranking information
- **500/500 albums** with cover art (downloaded via iTunes API)
- **500/500 albums** with metadata (artist, album, year, label)
- **500/500 albums** with descriptions (mix of original Rolling Stone content and researched additions)
- **496/500 albums** with accurate Wikipedia page links (99.2% coverage)
- **500+ albums** with Spotify streaming links (100% coverage with search fallback)

## 🎯 Key Insights

### Notable Changes (2020 → 2023)
- **Biggest Climber**: Lauryn Hill's "The Miseducation of Lauryn Hill" (#10 in 2023, previously much lower)
- **New Entries**: Recent albums like Beyoncé's "Renaissance" and Bad Bunny's "Un Verano Sin Ti"
- **Genre Diversity**: Increased representation of hip-hop, R&B, and global music

### Statistics  
- **New Albums in 2023**: 192 albums (38.4% of the list)
- **Improved Rankings**: 164 albums moved up
- **Dropped Rankings**: 113 albums moved down or were removed
- **Most Represented Artist**: The Beatles (multiple albums in top rankings)
- **Decades Covered**: 1950s through 2020s
- **Genres**: Rock, Hip-Hop, R&B, Soul, Punk, Electronic, Country, Jazz, and more

## 🔧 Technical Details

### Frontend
- **Vanilla JavaScript** for maximum compatibility and performance
- **CSS Custom Properties** for dynamic theming system
- **CSS Grid & Flexbox** for responsive layouts
- **SVG Icons** for crisp, scalable interface elements
- **LocalStorage API** for theme persistence
- **Progressive Enhancement** for accessibility

### Data Processing
- **Python 3** scripts for data manipulation
- **CSV format** for easy data management
- **iTunes API** integration for cover art (100% success rate)
- **Spotify Web API** integration for streaming links
- **Wikipedia scraping** for accurate page URLs
- **Fuzzy string matching** for data correlation
- **JSON mapping files** for efficient lookups

## 📝 Development

### Running Locally
1. Clone the repository
2. Serve with a local HTTP server (required for CSV loading):
   ```bash
   python -m http.server 8000
   # Then visit http://localhost:8000
   ```
3. For development, any local server will work

### Theme Development
The application uses CSS custom properties for theming:
- 8 built-in themes with consistent color schemes
- Easy to add new themes by extending the CSS variables
- Theme selection persists across browser sessions

### Adding New Data
1. Update the CSV files with new information
2. Run appropriate scripts from the `scripts/` folder
3. Regenerate cover art if needed using `download_all_covers.py`
4. Update Wikipedia mappings with `extract_wikipedia_urls.py`
5. Update Spotify mappings with `extract_spotify_urls.py`

### Contributing
- All album descriptions marked "(by Claude)" were AI-generated based on historical research
- Original Rolling Stone descriptions preserved where available
- Cover art sourced from iTunes API with proper attribution
- Wikipedia links extracted via automated scraping for accuracy

## 📜 License

This project is for educational and research purposes. Album artwork and descriptions are used under fair use for educational commentary and criticism.

- **Rolling Stone rankings**: © Rolling Stone Magazine
- **Album artwork**: © Respective record labels and artists
- **Code and compilation**: Open source

## 🙏 Acknowledgments

- **Rolling Stone Magazine** for the original rankings and descriptions
- **iTunes API** for high-quality album artwork
- **Spotify** for streaming integration and album availability
- **Wikipedia contributors** for additional album research and accurate page URLs
- **Claude AI** for data processing assistance and missing descriptions

---

*Explore the greatest albums of all time with beautiful themes, comprehensive data, seamless Wikipedia integration, and instant Spotify streaming. Discover how musical tastes and recognition have evolved between 2020 and 2023.*

🎧 **[Start Exploring →](index.html)** | 🎨 **Try Different Themes** | 🔗 **Share Your Favorites**