🎵 Izzy Music Player

Izzy Banner

A beautiful, modern music player for macOS with YouTube Music, Tidal & JioSaavn integration

</div>

✨ Features

🎸 Triple Music Service Support

YouTube Music - Stream millions of songs from YouTube Music
Tidal - Hi-Res lossless audio (up to 24-bit/192kHz FLAC) via hifi-api
- 🏷️ Quality Badges - Visual Hi-Res, Lossless, and HQ indicators on every song
- ⚡ Optimized Performance - Smart caching and connection pooling for smooth playback
JioSaavn - Access India's largest music streaming platform
Seamless switching between services

🎯 Core Features

Global Hotkey - Quick access with Option + Space
Floating Window - Always-on-top interface for quick music control
Menu Bar Integration - Beautiful, redesigned menu bar player with album artwork
Smart Search - Real-time search with intelligent suggestions
AI-Powered Recommendations - Personalized "For You" section with AI-curated songs based on your listening history
Queue Management - Full control over your playback queue
Playlist Support - Create and manage custom playlists
Recently Played - Track your music history
Favorites - Save your favorite tracks for easy access
🆕 Song Downloads - Download songs in Hi-Res quality with embedded album art and metadata

🎨 Modern Design

Glassy UI - Beautiful glassmorphism design with blur effects
Album Artwork - High-quality album art display
Dark Mode - Elegant dark theme throughout
Smooth Animations - Polished transitions and interactions
Responsive Layout - Optimized for various screen sizes

🎛️ Playback Controls

Full Playback Control - Play, pause, next, previous
Centered Playback Layout - Beautifully balanced playback controls with perfectly centered buttons
Seek Support - Click or drag to seek through tracks
Media Key Integration - Native macOS media key support
Persistent State - Resume playback exactly where you left off
Volume Control - Fine-grained volume adjustment with hover indicator

🔍 Discovery

AI-Powered Search - Find music using natural language with Gemini AI
Intelligent "For You" Section - Get fresh, personalized recommendations on every refresh
- Uses Gemini AI to understand your music taste and mood
- Parallel API calls for ultra-fast refresh (2-4 seconds)
- Always provides new songs you haven't heard
- Filters out already played tracks automatically
Mood & Genre - Browse by mood and genre categories
Charts - Explore trending music
Song Suggestions - Discover similar tracks based on what you're listening to
Watch Playlist - Auto-generated radio playlists

📱 Additional Features

Lyrics Support - View synchronized lyrics for songs
Mini Player - Compact player window
Keyboard Shortcuts - Full keyboard navigation
Background Playback - Continues playing in background
Auto-Updates - Built-in update mechanism

💾 Download Feature (Tidal)

Hi-Res Priority - Downloads prefer Hi-Res Lossless > Hi-Res > Lossless > High quality
Album Art Embedding - FFmpeg automatically embeds cover art into downloaded files
Full Metadata - Title, artist, album embedded in each track
Download Location - Songs saved to ~/Downloads/Izzy Music/
macOS Notifications - Get notified when downloads complete
Available Everywhere - Download button on search results, favorites, queue, playlists, and more

🚀 Installation

Requirements

macOS 14.0 (Sonoma) or later
Python 3.13+ (for music service backend)
Internet connection

[!IMPORTANT] Python 3.13 or higher is strictly required. The app will not work with earlier Python versions (3.12, 3.11, etc.). Please ensure you have Python 3.13+ installed before running the app:
brew install python@3.13

Download

Download the latest release from the Releases page
Open the DMG file and drag Izzy to your Applications folder
Enter this command in terminal : xattr -rd com.apple.quarantine "/Applications/Izzy.app"
Launch Izzy from Applications

First Launch

On first launch, you may see a security prompt:

Go to System Settings > Privacy & Security
Click "Open Anyway" for Izzy
The app will launch and set up Python dependencies automatically

🛠️ Building from Source

Prerequisites

# Install Xcode (from App Store)
xcode-select --install

# Install Python 3.13+
brew install python@3.13

# Clone the repository
git clone https://github.com/ShubhamPP04/Izzy.git
cd Izzy

Setup

# Run the setup script to create Python virtual environment
chmod +x setup.sh
./setup.sh

# Install Python dependencies
pip install -r requirements.txt

Build

# Open the project in Xcode
open Izzy.xcodeproj

# Build and run from Xcode
# Or use command line:
xcodebuild -project Izzy.xcodeproj -scheme Izzy -configuration Release build

Create DMG

# Build a distributable DMG
chmod +x build_dmg.sh
./build_dmg.sh

📖 Usage

Global Hotkey

Press Option + Space anywhere on your Mac to open/close Izzy

Search for Music

Type in the search bar
Select a song, album, artist, or playlist
Click to play or add to queue

Switch Music Services

Open Settings (⚙️ icon)
Select YouTube Music, Tidal, or JioSaavn
Service will switch immediately

Create Playlists

Navigate to Library > Playlists
Click "Create Playlist"
Add songs by clicking the + button on any track

AI Search

Click the AI Search button (✨)
Describe the music you want in natural language
Example: "upbeat workout music" or "relaxing jazz for study"

AI-Powered Recommendations

Go to Settings and add your Gemini API key (get it free from Google AI Studio)
Visit the Home tab to see the "For You" section with the AI badge (✨)
The AI analyzes your recently played songs and suggests similar tracks based on genre, mood, and style
Tap the refresh button to get completely new recommendations instantly
Each refresh provides fresh songs you haven't heard before

🏗️ Project Structure

Izzy/
├── Izzy/                          # Main app source
│   ├── IzzyApp.swift             # App entry point
│   ├── Views/                    # SwiftUI views
│   │   ├── MenuBarView.swift    # Menu bar player UI
│   │   ├── ContentView.swift    # Main window
│   │   ├── SearchResultsView.swift
│   │   ├── PlaybackControlsView.swift
│   │   ├── QueueView.swift
│   │   ├── PlaylistView.swift
│   │   └── ...
│   ├── Managers/                 # Business logic
│   │   ├── PlaybackManager.swift
│   │   ├── MenuBarManager.swift
│   │   ├── MusicSearchManager.swift
│   │   ├── PlaylistManager.swift
│   │   └── ...
│   ├── Models/                   # Data models
│   │   ├── MusicModels.swift
│   │   ├── Playlist.swift
│   │   └── ...
│   ├── Services/                 # External integrations
│   │   ├── PythonServiceManager.swift
│   │   ├── GeminiService.swift
│   │   ├── DownloadManager.swift    # Song download service
│   │   └── UpdateManager.swift
│   └── ytmusic_service.py       # Python backend
├── build/                        # Build outputs
├── releases/                     # Release builds
└── requirements.txt             # Python dependencies

🔧 Technologies

Frontend (macOS App)

Swift 5.9+ - Modern Swift with async/await
SwiftUI - Declarative UI framework
Combine - Reactive programming
AVFoundation - Audio playback
AppKit - Native macOS integration

Backend (Python Service)

Python 3.13+ - Backend service
ytmusicapi - YouTube Music API
yt-dlp - Audio stream extraction
requests - HTTP client for JioSaavn & Tidal
aiohttp - Async HTTP (optional)
FFmpeg - Audio processing & metadata embedding (optional, for downloads)

External Services

YouTube Music - Music catalog and streaming
Tidal (via hifi-api) - Hi-Res lossless audio streaming
JioSaavn (via saavn.dev) - Indian music streaming
Google Gemini AI - Natural language music search

⚙️ Configuration

Settings Location

Settings are stored in:

~/Library/Containers/com.superman.Izzy/Data/Library/Application Support/

Customizable Settings

Music service (YouTube Music / Tidal / JioSaavn) - Now at the top for quick access
Gemini API Key - Enable AI-powered recommendations and search
Global hotkey - Customize your keyboard shortcut
Centered playback controls - Toggle button centering
Mini player preferences - Customize compact view
Menu bar player toggle - Show/hide menu bar integration
Update preferences - Auto-update settings

🐛 Troubleshooting

Python Service Issues

# Verify Python environment
cd /path/to/Izzy
source music_env/bin/activate
python --version

# Reinstall dependencies
pip install --upgrade -r requirements.txt

Audio Playback Issues

Check internet connection
Verify Python service is running (check Console.app logs)
Try switching music service
Restart the app

Menu Bar Player Not Showing

Open Settings
Tog

Izzy

Install / Use

README