README.md

metadata

title: MusicGen
emoji: 🎵
colorFrom: blue
colorTo: red
sdk: gradio
app_file: app.py
pinned: false

🎵 VibeBlast - AI Music Generator

A cutting-edge text-to-music generation application with a "uniquely uncommon wildfire but harnessed into sharp black modern" aesthetic. Built with React, Vite, and powered by Hugging Face's MusicGen AI model.

✨ Features

🎨 Core Functionality

• Text-to-Music Generation: Transform text prompts into audio using state-of-the-art AI
• Real-time Audio Visualizer: Watch your music come alive with dynamic waveform visualization
• Persistent Song Library: All generated tracks are saved locally and survive page refreshes
• 8 Pre-built Vibe Suggestions: Quick-start generation with curated prompts (Cyberpunk, Lo-Fi, Phonk, Synthwave, etc.)
• User Audio Uploads: Upload your own audio samples to help improve the AI
• Interaction Tracking: Play, like, and regenerate actions are logged for continuous learning

🎭 Design & UX

• Wildfire Theme: Animated wildfire background with sharp black modern aesthetic
• Glass-morphism UI: Premium translucent cards with backdrop blur effects
• Neon-red Accents: Eye-catching accent color throughout the interface
• Progress Indicators: Visual feedback during music generation
• Share Functionality: One-click sharing of prompts via URL
• Accessibility: ARIA labels, focus outlines, and keyboard navigation support

🚀 Technical Highlights

• React 18 with Hooks and Context API for state management
• Vite for lightning-fast development and optimized builds
• Web Audio API for real-time audio analysis and visualization
• Express.js Backend for file uploads and interaction logging
• localStorage for client-side persistence
• Responsive Design with mobile-first approach

📦 Project Structure

s```plaintext VibeBlastApp/ ├── src/ │ ├── components/ │ │ ├── AudioVisualizer.jsx # Real-time waveform visualizer │ │ ├── CreateView.jsx # Main music generation interface │ │ ├── Header.jsx # Top navigation bar │ │ ├── LibraryView.jsx # Rich library interface │ │ ├── OverlayWrapper.jsx # Wildfire background wrapper │ │ ├── Player.jsx # Audio playback controls │ │ ├── ProgressBar.jsx # Generation progress indicator │ │ ├── ShareButton.jsx # URL sharing functionality │ │ ├── Sidebar.jsx # Navigation sidebar │ │ ├── SongGrid.jsx # Song list display │ │ ├── UserUpload.jsx # Audio sample upload │ │ ├── VisualizerCard.jsx # Combined card with visualizer │ │ └── WildfireBackground.jsx # Animated wildfire effect │ ├── context/ │ │ └── GeneratedSongsContext.jsx # Global state for generated songs │ ├── hooks/ │ │ ├── useAudioAnalyser.js # Web Audio API hook │ │ └── useInteractionTracker.js # Interaction logging hook │ ├── utils/ │ │ └── musicGen.js # Hugging Face API integration │ ├── index.css # Global styles with wildfire theme │ ├── main.jsx # App entry point │ └── App.jsx # Main app component ├── server/ │ ├── index.js # Express backend server │ ├── package.json # Backend dependencies │ └── uploads/ # User-uploaded audio storage ├── public/ # Static assets ├── .env.example # Environment variable template ├── package.json # Frontend dependencies └── vite.config.js # Vite configuration

## 🛠️ 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):

   ```bash
   cd /path/to/VibeBlastApp

2. Install frontend dependencies:

   npm install
   

3. Install backend dependencies:

   cd server
   npm install
   cd ..
   

4. Configure environment variables:

   # Copy the example file
   cp .env.example .env
   
   # Edit .env and add your Hugging Face token:
   # VITE_HF_TOKEN=hf_YOUR_TOKEN_HERE
   

Running the Application

You need to run both the frontend and backend servers:

Terminal 1: Frontend (Vite)

npm run dev
# Runs on http://localhost:5174

Terminal 2: Backend (Express)

cd server
npm run dev
# Runs on http://localhost:4000

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

--color-black: #0a0a0a
--color-black-dark: #050505
--color-neon-red: #ff0055
--color-neon-orange: #ff6b35
--color-fire-start: #ff6b35
--color-fire-end: #ff0055

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