QUICK_START.md

🚀 Melodix - Inicio Rápido de Servicios

📋 Scripts Disponibles

Opción 1: Batch (Recomendado para Windows)

start_services.bat

Características:

• ✅ Verifica Redis automáticamente
• ✅ Inicia API FastAPI
• ✅ Inicia Worker Celery
• ✅ Opción para túnel Cloudflare
• ✅ Muestra IPs de acceso
• ✅ Detección de errores

Comandos:

start_services.bat          # Iniciar todo
start_services.bat stop     # Detener servicios
start_services.bat help     # Ayuda

---

Opción 2: PowerShell

.\start_services.ps1

Nota: Si tienes problemas de ejecución, ejecuta:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

Opción 3: Manual (3 terminales)

Terminal 1 - API:

cd c:\mfmm
venv_musical\Scripts\activate
uvicorn main:app --host 0.0.0.0 --port 8000

Terminal 2 - Worker:

cd c:\mfmm
venv_musical\Scripts\activate
celery -A tasks worker --loglevel=info -P solo

Terminal 3 - Túnel (opcional):

cd c:\mfmm
venv_musical\Scripts\activate
python start_tunnel.py

---

✅ Requisitos Previos

1. Redis

Verificar:

redis-cli ping
# Debe responder: PONG

Iniciar:

redis-server

O como servicio Windows:

net start Redis

---

2. Entorno Virtual

Crear (si no existe):

python -m venv venv_musical

Activar:

venv_musical\Scripts\activate

Instalar dependencias:

pip install -r requirements.txt

---

3. FFmpeg (Recomendado)

Verificar:

ffmpeg -version

Instalar (Chocolatey):

choco install ffmpeg

O descargar desde: https://ffmpeg.org/download.html

---

🔧 Solución de Problemas

"Redis no está corriendo"

# Verificar si el servicio existe
sc query Redis

# Iniciar servicio
net start Redis

# O ejecutar directamente
redis-server

---

"Puerto 8000 ya está en uso"

# Ver qué está usando el puerto
netstat -ano | findstr :8000

# Matar el proceso (reemplaza PID con el número real)
taskkill /F /PID <PID>

---

"FFmpeg no encontrado"

Algunas funciones de audio requieren FFmpeg. Si no lo necesitas inmediatamente, puedes ignorar esta advertencia y la app funcionará parcialmente.

---

"La API no responde"

1. Verifica que Redis esté corriendo
2. Revisa los logs en logs\api.log
3. Prueba acceder manualmente: http://localhost:8000/health

---

📱 Acceso desde Android

Red Local

1. Asegúrate que ambos dispositivos están en la misma red WiFi

2. Usa la IP que muestra el script:

   http://192.168.1.X:8000
   

3. Permite el puerto en el firewall:

   netsh advfirewall firewall add rule name="Melodix API" dir=in action=allow protocol=TCP localport=8000
   

---

Cloudflare Tunnel (Acceso Remoto)

1. Inicia el túnel cuando el script lo pregunte

2. La URL se guarda en tunnel_url.txt

3. Usa esa URL desde cualquier lugar del mundo

---

📊 URLs de Acceso

Servicio	URL
API Local	http://localhost:8000
API Red Local	http://192.168.1.X:8000
Swagger Docs	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
Health Check	http://localhost:8000/health
Cloudflare Tunnel	Ver tunnel_url.txt

---

🛑 Detener Servicios

Método 1: Script

start_services.bat stop

Método 2: Manual

Cierra las 3 ventanas de consola abiertas

Método 3: Forzado

taskkill /F /FI "WINDOWTITLE eq API Melodix*"
taskkill /F /FI "WINDOWTITLE eq Worker Celery*"
taskkill /F /FI "WINDOWTITLE eq Tunel Cloudflare*"

---

📝 Logs

Los logs se guardan en:

c:\mfmm\logs\
├── api.log         # Logs de la API FastAPI
├── celery.log      # Logs del worker Celery
└── melodix.log     # Logs generales de la app

Ver logs en tiempo real:

# PowerShell
Get-Content logs\melodix.log -Wait -Tail 50

# CMD
type logs\melodix.log

---

🎯 Flujo Típico de Uso

# 1. Iniciar Redis (si no está corriendo como servicio)
redis-server

# 2. Iniciar todos los servicios
start_services.bat

# 3. Esperar a que las 3 ventanas se abran

# 4. Probar la API
curl http://localhost:8000/health

# 5. Abrir Swagger para explorar
http://localhost:8000/docs

# 6. Conectar app Android (misma red)
# URL: http://192.168.1.X:8000

# 7. Al terminar, cerrar ventanas o usar:
start_services.bat stop

---

💡 Tips

• Inicio automático de Redis: Configura el servicio de Redis para que inicie con Windows
• Acceso rápido: Agrega start_services.bat a tus accesos directos
• Monitoreo: Revisa logs\melodix.log para ver actividad detallada
• Testing: Usa Swagger UI (/docs) para probar endpoints manualmente

---

¡Listo! Tu servidor Melodix está operativo 🎵