🎵 Harmonize

Listen Together, Stay in Sync

Harmonize is a real-time audio synchronization platform that enables multiple users to join virtual listening rooms and experience shared audio playback without drift or delay. Create collaborative playlists, upload music, and enjoy perfectly synchronized playback with friends anywhere in the world.

✨ Features

• 🎼 Create Virtual Rooms: Start a listening session and share with friends via a simple link
• 🎧 Real-time Synchronization: Perfect audio sync across all connected devices using Firestore real-time updates
• 📤 Collaborative Playlists: Upload audio files and build shared playlists together
• 🎮 Host Controls: Room creator controls playback (play, pause, skip, volume)
• 👥 Live Participants: See who's listening in real-time
• 🎨 Beautiful UI: Modern, responsive design with gradient backgrounds and smooth animations
• 🔄 Auto-sync: Automatic synchronization when users join mid-playback

🛠️ Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Backend: Firebase (Firestore + Storage)
• Audio: Web Audio API
• Real-time: Firestore real-time listeners

📋 Prerequisites

• Node.js 18+
• npm or yarn
• Firebase project with Firestore and Storage enabled

🚀 Setup Instructions

1. Clone the Repository

cd harmonize
npm install

2. Firebase Configuration

a) Enable Firebase Services

1. Go to Firebase Console

2. Select your project: direct-byte-473415-t7

3. Enable Firestore Database:

   • Go to Firestore Database → Create Database
   • Start in production mode or test mode (for development)

4. Enable Storage:

   • Go to Storage → Get Started
   • Set up security rules (start in test mode for development)

5. Enable Web App:

   • Go to Project Settings → General
   • Under "Your apps", click the web icon </>
   • Register your app and copy the config

b) Configure Environment Variables

Update .env.local with your Firebase config values:

NEXT_PUBLIC_FIREBASE_API_KEY=your_actual_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=direct-byte-473415-t7.firebaseapp.com
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=direct-byte-473415-t7.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

To get these values:

1. Firebase Console → Project Settings (gear icon)
2. Scroll down to "Your apps"
3. Select your web app or create one
4. Copy the config values

c) Firestore Security Rules (Development)

For testing, use these permissive rules. Update for production!

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /rooms/{roomId} {
      allow read, write: if true;  // Change this for production!
    }
  }
}

d) Storage Security Rules (Development)

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /rooms/{roomId}/{allPaths=**} {
      allow read, write: if true;  // Change this for production!
    }
  }
}

3. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

📖 How to Use

Creating a Room

1. Open the app homepage
2. Click "Create Room"
3. Enter your name and room name
4. Click "Create" - you'll be redirected to the room

Joining a Room

1. Click "Join Room"
2. Enter your name and the room ID (shared by the host)
3. Click "Join"

Uploading Music

1. In the room, click "+ Upload" in the right panel
2. Enter song title and artist name
3. Select an audio file (MP3, WAV, etc.)
4. Click "Upload Song"
5. Wait for the upload to complete

Playing Music

• Host only can control playback
• Click any song in the playlist to play it
• Use play/pause, next/previous buttons
• Adjust volume with the slider
• All participants hear the same audio in perfect sync

Sharing Room

Click "Copy Room Link" button in the Room Info panel to share with friends.

🏗️ Project Structure

harmonize/
├── app/
│   ├── page.tsx              # Landing page (Create/Join Room)
│   ├── room/[roomId]/
│   │   └── page.tsx          # Room player page
│   └── layout.tsx
├── components/
│   ├── RoomInfo.tsx          # Room details & participants
│   ├── MusicPlayer.tsx       # Audio player with controls
│   └── Playlist.tsx          # Playlist & upload UI
├── hooks/
│   └── useRoom.ts            # Real-time room data hook
├── lib/
│   └── firebase.ts           # Firebase configuration
├── types/
│   └── index.ts              # TypeScript interfaces
└── .env.local                # Environment variables

🔄 How Synchronization Works

1. Firestore Real-time Listeners: Room state is stored in Firestore and synced to all clients via onSnapshot
2. Host Controls: Only the room creator can modify playback state
3. State Broadcasting: When host changes play/pause/seek/volume, it updates Firestore
4. Client Sync: All connected clients receive updates and adjust their local audio playback
5. Time Sync: Current playback time is periodically synced to keep all clients in unison

🎨 Customization

Change Color Scheme

Edit gradient colors in:

• app/page.tsx - Landing page gradients
• app/room/[roomId]/page.tsx - Room page background
• Component files for button and card styling

Adjust Sync Interval

In components/MusicPlayer.tsx, change the sync frequency:

// Currently syncs every 2 seconds
if (isHost && room.isPlaying && Math.floor(audio.currentTime) % 2 === 0) {
  updateRoom({ currentTime: audio.currentTime });
}

🐛 Troubleshooting

"Room not found" error

• Verify Firebase credentials in .env.local
• Check Firestore security rules allow read/write
• Ensure room ID is correct

Upload fails

• Check Storage is enabled in Firebase
• Verify Storage security rules
• Check file size limits (Firebase free tier: 1GB storage)

Audio doesn't play

• Check browser console for errors
• Ensure audio file format is supported (MP3, WAV, OGG)
• Verify file uploaded successfully to Firebase Storage

Sync issues

• Ensure all clients have stable internet
• Check Firestore read/write permissions
• Verify real-time listeners are working (check browser console)

📝 Firebase Database Structure

rooms/{roomId}
{
  name: string,
  createdBy: string,
  createdAt: number,
  isPlaying: boolean,
  currentSongIndex: number,
  currentTime: number,
  volume: number,
  participants: string[],
  playlist: [
    {
      id: string,
      title: string,
      artist: string,
      duration: number,
      url: string,
      uploadedBy: string,
      uploadedAt: number
    }
  ],
  lastUpdated: number
}

🔒 Production Security

Before deploying to production:

1. Firestore Rules: Implement proper authentication and validation
2. Storage Rules: Limit file sizes and types
3. Rate Limiting: Add rate limits for uploads
4. User Authentication: Implement Firebase Auth
5. Environment Variables: Use secure environment variable management

🚀 Deployment

Deploy to Vercel

npm install -g vercel
vercel

Add environment variables in Vercel dashboard.

Deploy to Other Platforms

Build the app:

npm run build
npm run start

📄 License

MIT License - Feel free to use this project for learning and development.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

⭐ Show Your Support

Give a ⭐️ if you like this project!

---

Built with ❤️ using Next.js and Firebase