Milonga DJ Pro está diseñado ante todo para que un solo DJ pueda operarlo en tiempo real en el lugar sin confusión. La mayoría del software de DJ supone un DJ y un ingeniero de sonido por separado, por lo que muchas funciones no se pueden usar solo en la práctica. Esta app es lo contrario: está hecha para que una sola persona maneje toda una milonga.

- Funciona totalmente sin conexión (no requiere internet)
- Todos los datos quedan solo en tu propia PC
- Diseñado específicamente para Tango / Vals / Milonga / Cortina

▲ La app de un vistazo (izq.: Biblioteca / centro: Reproductor y Setlist / der.: Creador de tandas)

## 1. Inicio e instalación

- Versión MSIX: inicia "Milonga DJ Pro" desde el menú Inicio
- Versión archivo: doble clic en `index.html` (se abre en el navegador)

> ⚠ Si un cambio no aparece en la versión archivo, cierra el navegador por completo, vuelve a abrir `index.html` y pulsa `Ctrl + Shift + R` (recarga forzada).

## 2. Distribución de la pantalla

Área | Posición | Función
--- | --- | ---
Biblioteca | Izquierda | Todos los temas importados. Filtra por género / favoritos
Reproductor y Setlist | Centro | Reproducción, forma de onda, lista de candidatos, el setlist en vivo
Creador de tandas | Derecha | Creación manual/automática, sugerencias de temas similares, cortina

Barra superior: Modo evento, Temporizador, EQ, Ajustes, Ayuda, Candidatos, Imprimir, Añadir temas, cambio de idioma (JA/EN/ES).

## 3. Añadir temas a la biblioteca (3 formas)

1. Arrastrar y soltar / botón +: suelta archivos en el área "+ Drag & Drop" arriba a la izquierda, o usa "+ Añadir temas" arriba a la derecha. Admite múltiples archivos/carpetas.
2. 📁 Vigilancia de carpeta: indica una carpeta de música y se escanea automáticamente cada 30 s en busca de novedades (recursivo, se restaura al reiniciar).
3. 📋 Importar lista: importa iTunes / Rekordbox / M3U, con coincidencia y agrupación automática en tandas.

Al importar se extraen automáticamente orquesta, título, año, cantor y carátula de las etiquetas ID3. Incluso una biblioteca de 10.000 temas inicia al instante gracias a la decodificación diferida.

▲ Biblioteca (filtro de género, agrupado por orquesta, "+" para añadir a candidatos)

## 4. Crear tandas

### 4-1. Creación manual

1. Pulsa "+" en un tema de la biblioteca para añadirlo a la lista de candidatos (se muestra en el centro)
2. Cuando esté listo, pulsa "✦ Crear Tanda" (el género se detecta del primer tema)
3. Reordena, elimina o sustituye un solo tema dentro de una tanda

### 4-2. Generación automática (BD de orquestas)

Activa la base de datos de orquestas → genera tandas en lote por orquesta × género (género por defecto: solo Tango; configurable).

### 4-3. 📚 Colección de tandas (guardar y reutilizar)

Guarda tandas individuales, márcalas como favoritas y vuélvelas a llamar. Acumula tus tandas habituales para usarlas al instante durante el evento.

### 4-4. 🅰🅱🅲 Cambio rápido de setlist

Mantén tres ranuras de setlist (A / B / C) y cambia al instante según la sala.

▲ Pestaña manual, lista de candidatos, Crear Tanda

## 5. ✦ Sugerencias de temas similares (motor de recomendación)

El botón "✦ Temas similares" a la derecha abre una ventana emergente.

- Sugiere temas similares ordenados por puntaje, tomando el tema en reproducción/seleccionado como referencia
- Filtra por el desplegable de mood
- Cada fila tiene ▶ Reproducir / ✎ Editar / + Añadir a la lista de tanda
- Al añadir con "+" se marca ✓ (dorado) igual que en la biblioteca, y aparece en la lista de candidatos

▲ Ventana de temas similares (tema de referencia, filtro de mood, ▶✎+)

## 6. Etiquetas de mood y sincronización con Excel

Etiquetar los temas con mood primario/secundario, flujo e intensidad permite que el motor considere el arco emocional.

### Cómo etiquetar

- Individual: ✎ Editar un tema → fija mood primario / flujo / intensidad
- En lote: gestiona en Excel (.xlsx) / CSV e importa

### Sincronización con Excel (Excel = maestro)

1. ⬆ Exportar etiquetas: exporta las etiquetas actuales de la app a CSV (semilla para el Excel maestro)
2. Edita `primary_mood / flow_type / intensity / year / singer`, etc. en Excel
3. 🎭 Importar etiquetas (o 📋 Lista) para importar el `.xlsx`

Situación | Comportamiento
--- | ---
La celda de Excel tiene valor | Sobrescribe con ese valor (Excel manda)
La celda de Excel está vacía | Conserva el valor existente en la app (el trabajo manual nunca se borra)
Variaciones de orquesta/título | Absorbe `[Tango]`, mayúsculas y ancho completo/medio automáticamente

Tras importar, un informe de sincronización muestra: temas sincronizados / filas no coincidentes / temas aún sin etiquetar.

▲ Informe de sincronización de etiquetas (Excel = maestro)

## 7. Controles de reproducción

Función | Descripción
--- | ---
Básico | Clic en un tema → Espacio para reproducir/pausar
Modo AUTO | Avance automático tanda → cortina → siguiente tanda (OFF por defecto)
Crossfade automático | Fundido dentro de la tanda / hacia la cortina (Ajustes)
🎧 CUE de auriculares | Preescucha en una salida separada del máster
Puntos de cue A/B/C | Registra tres puntos de inicio dentro del tema
⏱ Recorte inicio/fin | Corta intro/outro para la reproducción
Tempo ±10% | Ajuste fino de velocidad (doble clic para volver a 100%)
🎵 Sound check de la siguiente tanda | Verifica el nivel de la próxima tanda durante la cortina
Normalización LUFS | Nivela de reediciones SP de los años 30 a grabaciones modernas + EQ por tema

▲ Reproductor (forma de onda, medidores L/R, CUE, AGC, tempo)

## 8. Cortina

Registra candidatos a cortina desde la biblioteca → se insertan automáticamente entre tandas. Opcionalmente, inserta una antes de una tanda al crearla.

## 9. Arco de energía / plan por eje temporal

Reordena automáticamente las tandas según cuatro curvas (ascendente / descendente / pico / valle). Introduce las horas de inicio, pico y fin y la intensidad objetivo se muestra en tiempo real respecto al reloj.

## 10. Durante y después del evento

- Modo evento: visualización optimizada para la operación en vivo
- 🎭 Pantalla: para el proyector del lugar (con fondo de carátula)
- Temporizador: gestión de tiempo transcurrido / restante
- Analítica del registro: tras el evento, BPM, tendencia de energía, ranking de uso de orquestas
- Guardar/cargar setlist: guarda como JSON para reutilizar; imprimible

## 11. Ajustes

Segundos de pausa entre tandas / tiempo de crossfade / fade-in / objetivo LUFS / género por defecto de autogeneración / salida de audio (máster = altavoces, cue = auriculares).

## 12. Atajos de teclado

> Desactivados mientras se escribe en un campo de texto. Haz clic fuera del campo primero.

Tecla | Acción
--- | ---
`Space` | Reproducir / Pausar
`→` | Siguiente tema (siguiente tanda si es el último de la tanda)
`←` | Dentro de 3 s = tema anterior / después de 3 s = volver al inicio

## 13. Datos y privacidad

- Temas, etiquetas y setlists se guardan solo en tu PC (base de datos del navegador)
- Sin transmisión externa · totalmente sin conexión
- Copia de seguridad: setlists como JSON, etiquetas mediante exportación CSV

## 14. Solución de problemas

Síntoma | Solución
--- | ---
Los cambios no se reflejan (versión archivo) | Cierra el navegador por completo → reábrelo → `Ctrl+Shift+R`
No aparecen temas similares | Reproduce/selecciona un tema para fijar una referencia. Más temas etiquetados = mejor precisión
"Sin tema coincidente" al importar etiquetas | Revisa la ortografía de orquesta/título (variaciones grandes no coinciden)
Volumen desigual | Activa la normalización LUFS (Ajustes); usa EQ por tema
Comprobar el próximo tema sin enviarlo a la sala | Usa 🎧 CUE (salida de auriculares)