# 🎵 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)

## ✨ 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
- **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

### 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 |

## 📈 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)

## 🎯 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)
- **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`

### 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
- **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, and seamless Wikipedia integration. Discover how musical tastes and recognition have evolved between 2020 and 2023.*

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