musica-ia/README.md

# MusiaIA - AI Music Generator

Generador de música por IA que crea proyectos compatibles con Ableton Live (.als) mediante un chatbot conversacional.

## 🎯 Características Principales

- ✅ **Generación de archivos ALS**: Crea proyectos válidos para Ableton Live programáticamente
- ✅ **Chat IA**: Conversa con GLM4.6 y Minimax M2 para entender tus ideas musicales
- ✅ **Análisis inteligente**: Extrae BPM, tonalidad, estilo y mood de tu mensaje
- ✅ **Samples automáticos**: Selecciona samples apropiados para cada género
- ✅ **Múltiples géneros**: House, Techno, Hip-Hop, Pop y más
- ✅ **Estructura profesional**: Tracks, clips, routing y efectos

## 🏗️ Arquitectura

```
📁 MusiaIA
├── 🎼 als/                     # Archivos ALS de ejemplo
├── 🎵 source/                  # Biblioteca de samples
│   ├── kicks/
│   ├── snares/
│   ├── bass/
│   └── ...
├── ⚙️ src/backend/             # Backend Python
│   ├── ai/                     # Clientes de IA
│   ├── als/                    # Generador ALS
│   ├── api/                    # Endpoints REST
│   └── core/                   # Lógica principal
├── 💻 src/dashboard/           # Frontend React
├── 📊 output/                  # Proyectos generados
└── 📚 docs/                    # Documentación
```

## 🚀 Inicio Rápido

### 1. Configurar API Keys

Edita el archivo `.env` y agrega tus API keys reales:

```bash
# GLM4.6 API (para generación estructurada)
GLM46_API_KEY=tu_api_key_aqui

# Minimax M2 (para conversación)
ANTHROPIC_AUTH_TOKEN=tu_auth_token_aqui
```

### 2. Instalar Dependencias

```bash
pip install -r requirements.txt
```

### 3. Generar un Proyecto de Ejemplo

```python
from src.backend.als.example_usage import create_house_project

# Genera un track de house automáticamente
als_path = create_house_project()
print(f"✅ Proyecto creado: {als_path}")
```

### 4. Abrir en Ableton Live

¡Abre el archivo `.als` generado directamente en Ableton Live 11+!

## 🎵 Ejemplo de Uso

### Chat de Generación

```python
from src.backend.ai.example_ai import test_orchestrator

# Genera un proyecto desde un mensaje
await test_orchestrator()
# Input: "Create an uplifting house track with piano"
# Output: Configuración completa de Ableton Live
```

### API Directa

```python
from src.backend.ai.ai_clients import AIOrchestrator
from src.backend.als.als_generator import ALSGenerator

# 1. Analizar mensaje
orchestrator = AIOrchestrator()
config = await orchestrator.generate_music_project(
    "energetic techno track at 130 BPM"
)

# 2. Generar ALS
generator = ALSGenerator()
als_path = generator.generate_project(config)

# 3. ¡Listo para Ableton!
print(f"Proyecto: {als_path}")
```

## 📦 Estructura de un Proyecto ALS

```json
{
    "name": "AI House Track",
    "bpm": 124,
    "key": "Am",
    "tracks": [
        {
            "type": "AudioTrack",
            "name": "Drums",
            "samples": [
                "kicks/kick_001.wav",
                "snares/snare_001.wav"
            ],
            "color": 35
        },
        {
            "type": "MidiTrack",
            "name": "Bass",
            "midi": {
                "notes": [45, 47, 52, 50]
            },
            "color": 12
        }
    ]
}
```

## 🔧 Componentes Principales

### ALS Generator (`src/backend/als/als_generator.py`)

Genera archivos Ableton Live Set (.als) desde configuraciones:

- ✅ Parsea y crea XML válido
- ✅ Comprime con gzip
- ✅ Crea estructura de carpetas
- ✅ Referencias a samples correctas

### AI Clients (`src/backend/ai/ai_clients.py`)

Clientes para APIs de IA:

- **GLM4.6**: Análisis musical y generación estructurada
- **Minimax M2**: Conversación y chat
- **Orchestrator**: Selecciona el mejor modelo para cada tarea

### ALS Parser (`src/backend/als/als_parser.py`)

Lee y analiza archivos ALS existentes:

- ✅ Extrae información de tracks
- ✅ Lista samples usados
- ✅ Valida integridad de archivos

## 🎼 Géneros Soportados

| Género  | BPM Típico | Tracks Característicos      |
|---------|------------|----------------------------|
| House   | 120-130    | Kick, Bass, Leads, FX      |
| Techno  | 125-135    | Kick, Hat, Acid Bass       |
| Hip-Hop | 80-100     | Kick, Snare, Bass, Vox     |
| Pop     | 100-130    | Drums, Bass, Keys, Vox     |
| Trance  | 130-150    | Kick, Bass, Pads, Leads    |

## 📊 Estados del Proyecto

- ✅ **Completado**: Generador ALS (100% funcional)
- ✅ **Completado**: Parser ALS (100% funcional)
- ✅ **Completado**: Clientes AI (listo para API keys)
- 🔄 **En progreso**: Dashboard web
- 📋 **Pendiente**: Base de datos
- 📋 **Pendiente**: Sistema de samples
- 📋 **Pendiente**: API REST
- 📋 **Pendiente**: Tests completos

## 🔑 API Keys Necesarias

### GLM4.6
- Endpoint: `https://api.z.ai/api/paas/v4`
- Modelo: `glm-4.6`
- Headers: `Authorization: Bearer TU_API_KEY`

### Minimax M2
- Endpoint: `https://api.minimax.io/anthropic`
- Modelo: `MiniMax-M2`
- Headers:
  - `Authorization: Bearer TU_AUTH_TOKEN`
  - `anthropic-version: 2023-06-01`

## 🧪 Testing

```bash
# Probar generador ALS
python3 src/backend/als/example_usage.py

# Probar parser ALS
python3 src/backend/als/test_parser.py

# Probar clientes AI (requiere API keys configuradas)
python3 src/backend/ai/example_ai.py
```

## 📁 Archivos de Ejemplo

Explora la carpeta `output/als/` para ver proyectos generados:

```
output/als/
├── AI House Track_73011964/
│   └── Ableton Live Project/
│       └── AI House Track Project/
│           └── AI House Track.als          # ¡Abre en Ableton!
├── AI Techno Track_54b0d430/
└── AI Hip-Hop Beat_159ae17f/
```

## 🛠️ Desarrollo

### Estructura de Código

```python
# src/backend/als/als_generator.py
class ALSGenerator:
    def generate_project(config: Dict) -> str:
        """Crea proyecto ALS completo"""
        # 1. Crear estructura
        # 2. Generar XML
        # 3. Comprimir
        # 4. Retornar path

# src/backend/ai/ai_clients.py
class AIOrchestrator:
    async def generate_music_project(message: str) -> Dict:
        """Genera configuración desde chat"""
        # 1. Analizar con GLM4.6
        # 2. Estructurar config
        # 3. Retornar configuración
```

### Agregar Nuevo Género

1. Actualizar `ai_clients.py` - mapeo de géneros
2. Agregar samples en `source/{genre}/`
3. Crear template en `example_usage.py`

## 📚 Documentación Adicional

- [`docs/arquitectura.md`](docs/arquitectura.md) - Arquitectura completa
- [`docs/generador_als.md`](docs/generador_als.md) - Detalles técnicos ALS
- [`docs/api_chatbot.md`](docs/api_chatbot.md) - API y chatbot

## 🎉 Logros Actuales

- ✅ **Parser/Generador ALS**: 100% funcional
- ✅ **Estructura XML**: Completa y válida
- ✅ **Compresión Gzip**: Funcionando
- ✅ **Múltiples géneros**: House, Techno, Hip-Hop
- ✅ **Clientes AI**: Integrados y listos
- 🔄 **Dashboard**: En desarrollo

## 🤝 Contribuir

1. Fork el repo
2. Crea branch: `git checkout -b feature/nueva-funcionalidad`
3. Commit: `git commit -m "Agregar nueva funcionalidad"`
4. Push: `git push origin feature/nueva-funcionalidad`
5. Abre un Pull Request

## 📝 Licencia

MIT License - libre para uso personal y comercial.

## 🙏 Créditos

Desarrollado con:
- Python 3.10+
- FastAPI
- GLM4.6 (Z.AI)
- Minimax M2
- Ableton Live

---

**MusiaIA** - *Donde la IA encuentra la música* 🎵🤖