🎵 Freedoom Music Player

A modern, clean web application that plays MP3 files stored in Google Drive with an intelligent ranking system based on play counts.

✨ Features

• 🔐 Google OAuth Login - Secure authentication using Google Identity Services
• 📁 Google Drive Integration - Fetch and play MP3 files directly from your Drive folder
• 🎵 Smart Ranking Algorithm - Songs are ranked by play count (lower = higher priority)
• ⭐ Favorites System - Mark songs as favorites and filter by them
• 🎲 Random Play - Play random songs prioritizing low-rank (less played) songs
• 💾 Persistent Storage - Play counts and favorites saved in browser local storage
• 🎨 Modern Dark UI - Spotify-inspired clean, responsive design
• 📱 Mobile Responsive - Works seamlessly on desktop and mobile devices

🎯 How Ranking Works

1. New songs start with play_count = 0 (highest priority)
2. When a song is played for >30 seconds, its play_count is incremented
3. Lower play_count = higher priority in rankings
4. Random play always picks from the lowest-rank songs first
5. Favorites can override sorting but still update rank when played

📋 Prerequisites

Before you begin, ensure you have:

1. A Google Cloud Project (create one at Google Cloud Console)
2. Enabled APIs:
   • Google Identity Services (OAuth)
   • Google Drive API
3. OAuth 2.0 Credentials:
   • Client ID (Web application type)
   • Authorized redirect URIs configured
4. A Google Drive folder containing MP3 files

🚀 Setup Instructions

Step 1: Google Cloud Configuration

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Click "Create Project" and give it a name

2. Enable Required APIs:

   • Navigate to "APIs & Services" > "Library"
   • Enable Google Identity Services
   • Enable Google Drive API

3. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Web application" as the application type
   • Add your Authorized redirect URIs:
     • For local development: http://localhost:5173 (or your Vite port)
     • For production: Your deployment URL (e.g., https://yourusername.github.io)
   • Copy your Client ID (you'll need this in Step 3)

Step 2: Prepare Your Google Drive Folder

1. Create a folder in Google Drive
2. Upload your MP3 files to this folder
3. Important: The folder should contain only MP3 files (or the app will filter them)
4. Get your Folder ID from the folder URL:
   • Open the folder in Google Drive
   • The URL looks like: https://drive.google.com/drive/folders/FOLDER_ID_HERE
   • Copy the FOLDER_ID_HERE part

Step 3: Clone and Install

# Clone the repository
git clone <your-repo-url>
cd Freedoom

# Install dependencies
npm install

Step 4: Configure Environment Variables

Create a .env file in the root directory:

VITE_GOOGLE_CLIENT_ID=your_client_id_here
VITE_DRIVE_FOLDER_ID=your_folder_id_here

Note: If you don't set these, you can enter them manually in the app UI.

Step 5: Run the Application

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

The app will be available at http://localhost:5173 (or the port shown in your terminal).

📦 Deployment

GitHub Pages

1. Update vite.config.js base path:

   base: '/your-repo-name/'

2. Build the project:

   npm run build

3. Deploy the dist folder to GitHub Pages

Netlify

1. Connect your repository to Netlify
2. Set build command: npm run build
3. Set publish directory: dist
4. Add environment variables in Netlify dashboard:
   • VITE_GOOGLE_CLIENT_ID
   • VITE_DRIVE_FOLDER_ID

Vercel

1. Import your repository to Vercel
2. Add environment variables in project settings
3. Deploy

Render

1. Sign in to Render with your GitHub account
2. Create a new Static Site
3. Connect your repository: AsimMahata/Freedoom
4. Configure:
   • Build Command: npm install && npm run build
   • Publish Directory: dist
5. Add environment variables:
   • VITE_GOOGLE_CLIENT_ID
   • VITE_DRIVE_FOLDER_ID
6. Important: Add your Render URL to Google OAuth authorized redirect URIs
7. Deploy

See DEPLOYMENT.md for detailed Render deployment instructions.

🔧 Configuration

Without Environment Variables

If you don't set environment variables, you can:

• Enter your Client ID on the login screen
• Enter your Folder ID after logging in

Both values are saved in browser local storage for convenience.

📁 Project Structure

Freedoom/
├── src/
│   ├── components/
│   │   ├── Login.jsx          # Login component with OAuth
│   │   ├── MusicPlayer.jsx    # Main player component
│   │   ├── AudioControls.jsx  # Audio playback controls
│   │   └── SongList.jsx       # Song list display
│   ├── utils/
│   │   ├── googleAuth.js      # Google OAuth utilities
│   │   ├── driveApi.js        # Google Drive API integration
│   │   ├── storage.js         # Local storage utilities
│   │   └── ranking.js         # Ranking algorithm
│   ├── App.jsx                # Main app component
│   ├── main.jsx               # React entry point
│   └── index.css              # Global styles
├── index.html
├── vite.config.js
├── package.json
└── README.md

🎮 Usage

1. Login: Click "Sign in with Google" and authorize the app
2. Enter Folder ID: If not set in env, enter your Google Drive folder ID
3. Play Music: Click the play button on any song
4. Navigate: Use previous/next buttons or click songs directly
5. Favorites: Click the star icon to favorite/unfavorite songs
6. Filter: Toggle "Show Favorites" to see only favorited songs
7. Random Play: Click "Play Random" to play a random low-rank song

🔒 Security Notes

• The app uses read-only Google Drive API access
• OAuth tokens are stored in browser local storage (not recommended for production apps with sensitive data)
• For production, consider implementing a backend to handle OAuth securely
• Make sure your OAuth redirect URIs match your deployment URL exactly

🐛 Troubleshooting

Issue: "Login failed"

• Check that your Client ID is correct
• Ensure redirect URIs are properly configured in Google Cloud Console
• Make sure Google Identity Services API is enabled

Issue: "Failed to load songs"

• Verify your Folder ID is correct
• Ensure the folder contains MP3 files
• Check that Google Drive API is enabled
• Make sure you have read access to the folder

Issue: "Error playing audio"

• The file might not be accessible with the current token
• Try refreshing the page and logging in again
• Ensure the MP3 file format is valid

📝 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

🙏 Acknowledgments

• Google Identity Services for OAuth
• Google Drive API for file access
• React and Vite for the amazing development experience

---

Made with ❤️ for music lovers