musica-ia/QUICK_START.md

MusiaIA - Quick Start Guide

Overview

MusiaIA is an AI-powered music generator that creates Ableton Live projects (.als files) from natural language descriptions.

Quick Test (Current Setup)

1. Start the Backend Server

cd /home/ren/musia/src/backend
python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

2. Test the API

# Health check
curl http://localhost:8000/health

# Chat with AI
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test-user", "message": "Create a house track"}'

# Generate project
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test-user", "requirements": "Create a techno track at 130 BPM"}'

# List projects
curl http://localhost:8000/api/projects/test-user

# Download project (replace PROJECT_ID with actual ID)
curl -o project.als http://localhost:8000/api/download/PROJECT_ID

3. Start the Frontend (Development)

cd /home/ren/musia/frontend
npm install
npm run dev

4. Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Example Commands

Generate Different Music Styles

House Track:

{
  "user_id": "your-name",
  "requirements": "Create an energetic house track at 124 BPM in A minor with a deep bassline"
}

Techno Track:

{
  "user_id": "your-name",
  "requirements": "Create a dark techno track at 130 BPM in D minor"
}

Hip-Hop Beat:

{
  "user_id": "your-name",
  "requirements": "Create a chill hip-hop beat at 95 BPM with swing"
}

System Architecture

┌─────────────────┐
│   Frontend      │
│  (React/TS)     │
└────────┬────────┘
         │
         │ HTTP/WebSocket
         ▼
┌─────────────────┐
│   Backend API   │
│   (FastAPI)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Clients    │
│  GLM4.6 +       │
│  Minimax M2     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  ALS Generator  │
│  (Creates .als) │
└─────────────────┘

Features

✅ Chat Interface - Natural language interaction ✅ Project Generation - Creates complete Ableton Live projects ✅ Multiple Genres - House, Techno, Hip-Hop, Pop, Trance, Dubstep ✅ BPM Detection - Automatically detects tempo from text ✅ Key Detection - Recognizes musical keys (C, Am, F, etc.) ✅ Mock Mode - Works without API keys (currently enabled) ✅ Download - Download generated ALS files ✅ Project History - View and manage all projects

File Structure

/home/ren/musia/
├── frontend/              # React frontend
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── services/      # API services
│   │   └── App.tsx        # Main app
│   └── dist/              # Built frontend
├── src/
│   ├── backend/
│   │   ├── ai/            # AI client integrations
│   │   ├── als/           # ALS generator/parser
│   │   └── api/           # FastAPI endpoints
│   └── shared/            # Shared utilities
├── output/
│   ├── als/               # Generated ALS files
│   └── projects/          # Project metadata
├── .env                   # Configuration
├── TESTING_REPORT.md      # Detailed test results
└── README.md              # Full documentation

API Endpoints

Endpoint	Method	Description
/health	GET	Server health check
/api/chat	POST	Chat with AI
/api/generate	POST	Generate music project
/api/projects/{user_id}	GET	List user projects
/api/download/{project_id}	GET	Download project
/api/projects/{project_id}	DELETE	Delete project

Current Status

Working

• ✅ Complete frontend (React + TypeScript + Tailwind)
• ✅ Full backend API (FastAPI)
• ✅ ALS file generation (valid Ableton Live projects)
• ✅ Mock AI responses (for testing)
• ✅ Project management (create, list, download, delete)
• ✅ WebSocket support for real-time chat

API Status

• GLM4.6: ❌ Insufficient balance (requires recharge)
• Minimax M2: ❌ Endpoint not found (404)
• Mock Mode: ✅ ACTIVE - Full functionality available

Next Steps (To Enable Production)

1. Recharge GLM4.6 Credits

   • Visit Z.AI platform
   • Add credits to account: 6fef8efda3d24eb9ad3d718daf1ae9a1.RcFc7QPe5uZLr2mS

2. Fix Minimax Endpoint

   • Verify correct API endpoint for Minimax M2
   • Update MINIMAX_BASE_URL in .env

3. Disable Mock Mode

   • Set MOCK_MODE=false in .env
   • Restart backend server

4. Production Deployment

   • Configure production database (PostgreSQL)
   • Set up SSL certificates
   • Deploy with Docker or cloud provider

Support

For detailed testing results, see: TESTING_REPORT.md For full documentation, see: README.md

License

Private repository - All rights reserved