🎵 Song2Meaning

A simple web application that uses Gemini AI with grounding search to analyze songs and reveal their themes, cultural context, and hidden meanings. Features Spotify integration for music previews while you explore the deeper meanings behind your favorite tracks.

✨ Features

• 🤖 AI-Powered Analysis: Uses Gemini AI with grounding search for accurate, contextual song analysis
• 🔗 Share Analysis: Generate shareable links for song analyses with SEO-optimized pages
• 💾 Smart Caching: Database-backed analysis caching to reduce LLM calls and improve performance
• 🎵 Enhanced Spotify Integration:
  • Smart Search: Search naturally with any keywords (e.g., "Bohemian Rhapsody", "Taylor Swift")
  • Multiple Results: Browse up to 15 search results with album art and metadata
  • Track Selection: Click any track to automatically start analysis
  • 30-second Previews: Play music previews directly in search results
  • Auto-Analysis: Selected tracks trigger immediate meaning analysis
  • Fallback Support: Graceful handling when previews aren't available
• 🎨 Neobrutalism Design: Bold, modern interface inspired by contemporary design trends
• ⚙️ Secure API: Server-side API routes keep your API keys safe from client exposure
• ⚡ Rate Limited: 5 analysis per IP per day to prevent abuse
• 📱 Responsive: Works perfectly on desktop and mobile devices
• 🚀 Fast: Optimized with caching and performance monitoring
• 🛡️ Secure: Input validation, sanitization, and security monitoring

🚀 Live Demo

Visit the live application: song2meaning.vercel.app

🏗️ Tech Stack

• Frontend: Next.js 15, React 19, TypeScript
• Styling: Tailwind CSS 4 with custom neobrutalism design
• AI: Google Gemini AI with grounding search
• Database: Supabase for analysis caching and sharing
• Music: Spotify Web API integration for track search and previews
• Deployment: Vercel
• Security: Server-side API routes, rate limiting, input validation

📌 Prerequisites

• Node.js 18+
• Gemini AI API key (Get one here)
• Spotify Developer Account (Create one here)
• Supabase account for database (Create one here)

🆕 What's New

🎵 Enhanced Spotify Search (Latest Update)

• Smart Search Interface: Natural language search - no more "Artist - Song" format required
• Multiple Results Display: Browse up to 15 tracks with rich metadata and album artwork
• Instant Previews: Play 30-second previews directly from search results
• One-Click Analysis: Select any track to automatically trigger meaning analysis
• Debounced Search: Real-time search with 300ms debouncing for optimal performance
• Visual Track Cards: Album art, artist info, duration, and popularity indicators
• Keyboard Navigation: Full keyboard support with escape to close results
• Mobile Optimized: Touch-friendly interface that works perfectly on all devices

🔗 Share Analysis Feature

• Shareable Links: Every song analysis now generates a unique shareable URL
• SEO Optimized: Share pages include proper metadata for social media previews
• Copy to Clipboard: One-click sharing with automatic clipboard copying
• Persistent Storage: Shared analyses are stored in Supabase for permanent access
• Access Tracking: Monitor how many times your shared analysis has been viewed

💾 Smart Caching System

• Database-Backed Caching: All analyses are stored in Supabase to prevent duplicate LLM calls
• Intelligent Matching: Normalized search keys ensure variations of the same song are matched
• Performance Boost: Cached results load instantly, saving API costs and improving UX
• Cache Statistics: Track cache hits and performance metrics
• Automatic Updates: Access counts and timestamps are automatically maintained

🔧 API Setup

Gemini AI API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the generated API key

Spotify API Credentials

Song2Meaning uses the Client Credentials Flow for Spotify integration, which is perfect for server-side applications that don't require user login.

Step 1: Create a Spotify App

1. Go to the Spotify Developer Dashboard
2. Log in with your Spotify account (create one if needed)
3. Click "Create app"
4. Fill in the app details:
   • App name: Song2Meaning (or your preferred name)
   • App description: AI-powered song analysis with music previews
   • Website: Your domain (e.g., https://yourdomain.com) or http://localhost:3000 for development
   • Redirect URI: http://localhost:3000/callback (for development)
   • API/SDKs: Check "Web API"
5. Accept the terms and click "Save"

Step 2: Get Your Credentials

1. In your newly created app dashboard, you'll see:
   • Client ID: A public identifier for your app
   • Client Secret: A private key (keep this secure!)
2. Click "Show client secret" to reveal it
3. Copy both values - you'll need them for your environment variables

Step 3: Configure App Settings (Optional)

For production deployment, update your app settings:

1. Go to "Settings" in your Spotify app dashboard
2. Update "Redirect URIs" to include your production domain
3. Add your production website URL

🔒 Security Note: The Client Secret should never be exposed in client-side code. Song2Meaning handles this securely by using server-side API routes.

Why Client Credentials Flow?

• ✅ No user login required - Perfect for public song analysis
• ✅ Server-side security - Client secret stays on your server
• ✅ Simple setup - No complex OAuth flows
• ✅ Rate limit friendly - Suitable for application-level requests

🛠️ Installation

1. Clone the repository

   git clone https://github.com/4regab/song2meaning.git
   cd song2meaning

2. Install dependencies

   npm install

3. Set up Supabase database

   • Create a new project at supabase.com
   • Go to SQL Editor in your Supabase dashboard
   • Copy and paste the contents of supabase/schema.sql
   • Run the SQL to create the database schema

4. Set up environment variables

   cp .env.local.example .env.local

   Edit .env.local and add your API keys:

   # Gemini AI API Configuration
   GEMINI_API_KEY=your_gemini_api_key_here
   
   # Spotify API Configuration
   SPOTIFY_CLIENT_ID=your_spotify_client_id_here
   SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here
   
   # Supabase Configuration
   NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   
   # Base URL for share links (optional, defaults to localhost:3000)
   NEXT_PUBLIC_BASE_URL=https://yourdomain.com

5. Run the development server

   npm run dev

6. Open your browser Navigate to http://localhost:3000

🚀 Deployment

Deploy to Vercel (Recommended)

1. Push to GitHub

   git add .
   git commit -m "Initial commit"
   git push origin main

2. Deploy to Vercel

   • Go to vercel.com
   • Import your GitHub repository
   • Add environment variable: GEMINI_API_KEY
   • Deploy!

3. Environment Variables In your Vercel project settings, add:

   • GEMINI_API_KEY: Your Gemini AI API key
   • SPOTIFY_CLIENT_ID: Your Spotify Client ID
   • SPOTIFY_CLIENT_SECRET: Your Spotify Client Secret
   • NEXT_PUBLIC_SUPABASE_URL: Your Supabase project URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY: Your Supabase anonymous key
   • SUPABASE_SERVICE_ROLE_KEY: Your Supabase service role key
   • NEXT_PUBLIC_BASE_URL: Your production domain (e.g., https://yourdomain.vercel.app)

🎯 Usage

Enhanced Search Experience

1. Search naturally - Type any song-related keywords:

   • "Bohemian Rhapsody"
   • "Taylor Swift Shake It Off"
   • "Beatles Yesterday"
   • "Nirvana Smells Like Teen Spirit"

2. Browse results - See up to 15 tracks with:

   • Album artwork and metadata
   • Artist names and album information
   • Track duration and popularity scores
   • Preview availability indicators (green dot)

3. Preview tracks - Click the play button on album art to hear 30-second previews

4. Select your song - Click any track card to automatically start analysis

5. View comprehensive analysis with detailed sections:

   • 📖 Overview: Summary of the song's meaning and key themes
   • 🔍 Deep Dive: Detailed lyrical analysis and interpretation
   • 💭 Cultural Context: Historical and cultural background
   • 🎵 Spotify Player: Continue listening while reading the analysis

6. Share your analysis using the share button to copy a permanent link

7. Enjoy instant results for previously analyzed songs thanks to smart caching

🔧 Troubleshooting

Spotify Integration Issues

No music previews showing up?

• Verify your SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET are correctly set
• Check that your Spotify app is properly configured in the Developer Dashboard
• Note: Not all tracks have preview URLs available from Spotify

"Spotify API error" messages?

• Ensure your Spotify app has "Web API" enabled
• Check that your Client Secret hasn't been regenerated (this would invalidate the old one)
• Verify your environment variables are properly loaded

Rate limiting from Spotify?

• The Client Credentials flow has generous rate limits for most use cases
• If you hit limits, the app will gracefully continue without previews

General Issues

"Service configuration error"?

• Check that all required environment variables are set
• Restart your development server after changing .env.local
• Verify your API keys are valid and haven't expired

Analysis not working?

• Ensure your GEMINI_API_KEY is valid
• Check the Gemini API status
• Verify you haven't exceeded your Gemini API quota

🔧 API Endpoints

• POST /api/analyze - Analyze a song's meaning and themes (with caching and sharing)
• GET /share/[shareId] - View shared song analysis with SEO metadata
• GET /api/health - System health check
• GET /api/stats - Performance statistics (includes cache metrics)
• GET /api/rate-limit - Rate limit status
• POST /api/validate - Input validation
• GET /api/spotify/search - Search for single Spotify track (legacy)
• GET /api/spotify/search-multiple - New: Search for multiple Spotify tracks with metadata
• GET /api/spotify/preview - Get track preview URLs

🛡️ Security Features

• Server-side API: API key never exposed to client
• Rate Limiting: 5 requests per IP per day
• Input Validation: Strict format validation and sanitization
• Error Handling: Comprehensive error management with fallbacks
• Security Monitoring: Request logging and anomaly detection

📊 Performance

• Database Caching: Persistent Supabase caching eliminates duplicate LLM calls
• Smart Cache Matching: Normalized search keys for intelligent song matching
• Request Deduplication: Prevents duplicate API calls in real-time
• Performance Monitoring: Real-time metrics and cache statistics
• Optimized Prompts: Efficient AI interactions
• Instant Results: Cached analyses load immediately, improving user experience

🎨 Design

The application features a neobrutalism design with:

• Bold black borders and shadows
• High contrast colors
• Chunky, interactive buttons
• Clean typography (Inter + JetBrains Mono)
• Responsive layout

🤝 Contributing

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

For issues or questions, visit: GitHub Issues

📝 License

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

🙏 Acknowledgments

• Google Gemini AI for powerful language processing
• Supabase for database and backend services
• Spotify Web API for music integration and previews
• Vercel for seamless deployment
• Next.js for the amazing React framework
• Tailwind CSS for utility-first styling

📞 Support

If you have any questions or issues:

1. Check the Issues page
2. Create a new issue if needed
3. Review the troubleshooting section above
4. Check the Spotify Developer Documentation for API-related issues

---

Made with ❤️ and AI - Discover the stories behind your favorite songs!