Setup
To use AI features, you need a free Google Gemini API key.Getting an API key
- Visit Google AI Studio
- Sign in with your Google account
- Click “Get API Key”
- Create a new API key
- Copy the key
Adding to Izzy
- Open Settings in Izzy (⚙️ icon)
- Find the Gemini API Key field
- Paste your API key
- The AI features activate immediately
The Gemini API is free for personal use with generous rate limits. Your API key is stored securely in macOS Keychain.
AI-powered search
Find music using natural language instead of exact song titles.How it works
- Click the AI Search button (✨) in the search bar
- Describe the music you want in plain English
- Gemini analyzes your query and finds matching songs
- Results appear across all categories (songs, albums, artists, playlists)
Example queries
Mood-based
“upbeat workout music”“relaxing jazz for studying”“sad songs for rainy days”
Activity-based
“music for morning meditation”“high-energy dance tracks”“focus music for programming”
Genre & style
”80s synthwave vibes”“acoustic indie folk”“melodic techno sets”
Vibe description
“dreamy atmospheric soundscapes”“aggressive metal riffs”“smooth R&B grooves”
Search features
- Natural language - Describe music how you’d tell a friend
- Context understanding - Gemini interprets mood, genre, and activity
- Multi-service - Works with YouTube Music, Tidal, and JioSaavn
- Intelligent results - Returns songs matching your vibe, not just keywords
For You recommendations
Get fresh, personalized song recommendations based on your listening history.How it works
The “For You” section on the Home tab uses advanced AI to understand your music taste:- Analyzes your recently played songs
- Identifies patterns in genre, mood, tempo, and style
- Generates recommendations using Gemini AI
- Filters out songs you’ve already heard
- Delivers fresh tracks you’ll love
Features
- Smart recommendations
- Always fresh
- Ultra-fast
Intelligent matchingGemini AI analyzes:
- Music genres you prefer
- Mood and tempo patterns
- Artist styles you enjoy
- Time of day listening habits
- Similar but new artists
- Adjacent genres you might like
- Deep cuts from known artists
- Emerging tracks in your taste profile
AI badge
The “For You” section displays an ✨ AI badge to indicate that recommendations are powered by Gemini AI.Refreshing recommendations
Click the refresh button in the “For You” section to get completely new recommendations instantly:- New analysis of recent listening
- Different recommendations each time
- Updated based on latest played tracks
- 2-4 second refresh time
Recommendations improve over time as you listen to more music. The more you use Izzy, the better the AI understands your taste.
Privacy & data
Your privacy is protected when using AI features.What’s sent to Gemini
- Song metadata - Titles, artists, genres from recently played tracks
- Search queries - Your natural language search terms
- Context - General listening patterns (mood, genre preferences)
What’s NOT sent
- Personal information - No names, emails, or identifying data
- Listening timestamps - When you played songs is private
- Playback data - Full play counts and detailed history stay local
- Favorites & playlists - Your collections remain on your Mac
Data storage
All listening history and favorites are stored locally:Your API key is stored securely in macOS Keychain and never leaves your Mac. Izzy communicates directly with Google’s Gemini API - no third-party servers involved.
Troubleshooting
AI features not working
Verify API key
Verify API key
- Open Settings
- Check that your Gemini API key is entered correctly
- Ensure there are no extra spaces or characters
- Try regenerating the key in Google AI Studio
Check API quota
Check API quota
- Visit Google AI Studio
- Check your API usage and quota
- Free tier has generous limits but can be exceeded
- Wait for quota reset or upgrade to paid tier
Build listening history
Build listening history
AI recommendations need data to work:
- Play at least 10-20 songs first
- Listen across different genres
- Give the AI time to learn your taste
- Check “Recently Played” to see tracked songs
Check Console logs
Check Console logs
- Open Console.app (in Applications/Utilities)
- Filter for “Izzy”
- Look for Gemini API errors
- Common issues:
- Invalid API key
- Network connectivity
- Rate limiting
No AI badge showing
If the ✨ AI badge doesn’t appear in the “For You” section:- Verify your API key is entered in Settings
- Restart Izzy to refresh the UI
- Play some songs to build listening history
- Check that you’re viewing the Home tab
Recommendations aren’t relevant
If recommendations don’t match your taste:- Play more variety - Listen to different genres to help AI understand your range
- Use AI search - Search for specific vibes to train the AI better
- Refresh multiple times - Each refresh uses different analysis
- Check recently played - Ensure your listening history is accurate
Best practices
For better AI search results
- Be specific - “melancholic piano ballads” > “sad music”
- Combine attributes - “upbeat indie rock for running” gives better results
- Use comparisons - “music like Tame Impala but more electronic”
- Describe feelings - “music that makes you feel nostalgic”
For better recommendations
- Diversify listening - Play different genres and artists
- Regular usage - Listen daily to build comprehensive history
- Refresh often - Get new recommendations to explore different angles
- Favorite good matches - Helps AI learn what you truly enjoy
Technical details
API integration
- Model - Google Gemini 1.5 Flash (fast, efficient)
- Rate limits - Respects Google’s API quotas
- Timeout - 30 second timeout for AI requests
- Retry logic - Automatic retry on temporary failures
Performance
- Parallel calls - Multiple AI requests run simultaneously
- Caching - Recent AI responses cached for 10 minutes
- Background processing - AI analysis doesn’t block UI
- Efficient prompts - Optimized to minimize token usage