OnyxMunk/MusicGen

## 🛠️ Setup Instructions

### Prerequisites

- Node.js 16+ and npm
- A Hugging Face account and API token ([get one here](https://huggingface.co/settings/tokens))

### Installation

1. **Clone the repository** (or use your existing project):

2. **Install frontend dependencies**:

3. **Install backend dependencies**:

4. **Configure environment variables**:

### Running the Application

You need to run **both** the frontend and backend servers:

#### Terminal 1: Frontend (Vite)

#### Terminal 2: Backend (Express)

Then open your browser and navigate to: **<http://localhost:5174>**

## 🎮 Usage Guide

### Generating Music

1. Click **"Create"** in the sidebar
2. Either:
   - Type a custom prompt describing your desired music, OR
   - Click one of the 8 vibe suggestion chips
3. (Optional) Toggle **Instrumental** or **Auto-Lyrics** settings
4. Click **"Generate"** and wait ~30-60 seconds
5. Your generated track appears below with:
   - Audio visualizer showing real-time waveform
   - Play & Log button (sends interaction to backend)
   - Download button for WAV file
   - Share button to copy URL with prompt

### Uploading Audio Samples

1. Scroll to the bottom of the **Create** view
2. Click **"Choose File"** in the **"Upload Your Own Sample"** section
3. Select an audio file (WAV, MP3, etc.)
4. Click **"Upload"**
5. Your file is sent to the backend (`server/uploads/`) for future model training

### Viewing Your Library

- Generated songs persist across page refreshes (stored in `localStorage`)
- Click **"Library"** in the sidebar to view playlists, liked songs, and albums
- All cards use glass-morphism styling for a premium feel

## 🧪 API Integration

### Hugging Face MusicGen

The app uses the **facebook/musicgen-medium** model via the Hugging Face Inference API:

- **Endpoint**: `https://api-inference.huggingface.co/models/facebook/musicgen-medium`
- **Method**: POST
- **Headers**: `Authorization: Bearer YOUR_TOKEN`
- **Payload**: `{ "inputs": "your prompt here" }`
- **Response**: Audio blob (WAV format)

See `src/utils/musicGen.js` for the implementation.

### Backend Endpoints

#### `POST /api/upload`

- **Purpose**: Accept user-uploaded audio files
- **Body**: `multipart/form-data` with `audio` field
- **Response**: `{ "message": "Upload successful", "filename": "..." }`

#### `POST /api/track`

- **Purpose**: Log user interactions (play, like, regenerate)
- **Body**: `{ "songId": "...", "action": "play", "timestamp": 1234567890 }`
- **Response**: `{ "status": "logged" }`

## 🎨 Design System

### Color Palette

- **Background**: Sharp black (`#0a0a0a`, `#141414`)
- **Accent**: Neon red (`#ff0055`, `#ff1744`)
- **Fire Gradient**: Orange to red (`#ff6b35` → `#ff0055`)
- **Text**: White with varying opacity

### Key CSS Variables

### Animations

- **Wildfire**: 20s infinite background animation
- **Progress**: Linear progress bar during generation
- **Hover**: Scale transforms and color transitions
- **Spin**: Loading spinner for async operations

## 🚀 Future Enhancements

### Roadmap

- [ ] Real model fine-tuning pipeline integration
- [ ] User authentication & cloud storage
- [ ] PWA capabilities (offline support, installable)
- [ ] Analytics dashboard for upload/play metrics
- [ ] Advanced audio processing (remix, extend, variations)
- [ ] Real-time collaborative generation
- [ ] Genre-specific model selection
- [ ] Lyric generation and display

### Model Improvement Strategy

The app is designed for **continuous learning**:

1. **Data Collection**: User uploads and interactions are logged
2. **Aggregation**: Backend stores audio files and usage metrics
3. **Fine-tuning**: Periodically retrain the model on collected data
4. **Deployment**: Update the inference endpoint with improved model

See the placeholder script at `scripts/fineTuneModel.js` for integration points.

## 📝 Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `VITE_HF_TOKEN` | Hugging Face API token | `hf_abcdef123456...` |

## 🤝 Contributing

This is a personal project, but contributions are welcome! Some areas that could use help:

- **Performance**: Optimize large audio file handling
- **UI/UX**: Additional visualizer modes (spectrum, bars, etc.)
- **Backend**: Switch from file storage to database (PostgreSQL, MongoDB)
- **Testing**: Unit tests for components and hooks
- **Documentation**: More detailed API docs and code comments

## 📄 License

This project is for educational and demonstration purposes.

## 🙏 Credits

- **MusicGen Model**: Meta AI / Hugging Face
- **UI Inspiration**: Modern cyberpunk and glassmorphism design trends
- **Framework**: React team, Vite team

---

**Built with 🔥 by the VibeBlast team**  
*"Wildfire aesthetics meet cutting-edge AI music generation"*

## 🚀 Deployment to Hugging Face Spaces

This project is configured for deployment to Hugging Face Spaces using Docker.

1. **Create a new Space**: Select "Docker" as the SDK.
2. **Repository**: Connect this repository or push code to the Space's repo.
3. **Environment Variables**: Go to "Settings" -> "Variables and secrets" and add:
   - `VITE_HF_TOKEN`: Your Hugging Face User Access Token (Secret).
4. **Port**: The Dockerfile automatically uses port `7860` as required by Spaces.

The Docker build process will:
- Build the React frontend
- Start the Express backend
- Serve the frontend via the backend on port 7860