FOSFENO/docs/mezclador.md

# El Mezclador VJ (mezclas)

El **Mezclador** es el motor de vídeo de FOSFENO. No es un motor de visuales
generativas como los otros: es una **mesa de mezclas de dos capas** que combina
en directo una capa de fondo con un clip, y les aplica efectos de color.

Se elige con el botón redondo **Mezcla** del apartado *Motor de visuales*, en la
pestaña **MOTORES**.

## El modelo mental: siempre dos capas

Todo el mezclador se entiende con esta idea. Hay **dos capas y solo dos**, y
siempre son las mismas:

```
   ┌──────────────────────────────────────────────┐
   │  CAPA DE ENCIMA :: el CLIP                   │   un vídeo o una imagen
   │  (data/videos/…)                             │   de la galería
   ├──────────────────────────────────────────────┤
   │  CAPA DE ABAJO  :: el FONDO                  │   la cámara web
   │  (cámara  o  visuales Butter / MilkDrop)     │   o las visuales Butter
   └──────────────────────────────────────────────┘
                       ▼
             [ modo de mezcla ]  →  proyector
```

La tarjeta del panel está numerada en ese mismo orden, y ese orden es la
respuesta a casi cualquier duda:

| Paso | Qué decide |
|------|------------|
| **1 · Qué se ve** | si sale solo el fondo, solo el clip, o los dos |
| **2 · Fondo** | qué hay en la capa de abajo: **cámara** o **visuales Butter** |
| **3 · Clip** | qué vídeo o imagen va en la capa de encima |
| **4 · Cómo se juntan** | el modo de mezcla (solo aparece si se ven los dos) |

Debajo del paso 4 hay una **línea naranja de resumen** que dice, en una frase,
lo que va a salir por el proyector con los ajustes que tengas puestos. Si en
algún momento no sabes qué estás montando, esa línea lo dice.

<div align="center">
  <img src="assets/mezclador.png" alt="La tarjeta del Mezclador VJ" width="480">
</div>

## Poner visuales de fondo (MilkDrop detrás del vídeo)

Esto es lo que suele costar encontrar, así que va aparte. **Sí está integrado**
y funciona así:

1. Motor **Mezcla**.
2. Paso 2, desplegable **Fondo (capa de abajo)** → **Visuales Butter
   (MilkDrop)**.
3. La cámara se apaga sola (piloto incluido) y su sitio en la capa de abajo lo
   ocupan las visuales de MilkDrop.
4. Justo debajo aparece el **preset de MilkDrop** que hace de fondo, con
   **« Anterior / Siguiente »** y la casilla **Cambiar el fondo solo**.

Ese preset es **el mismo del motor Butter**: lo que elijas aquí queda elegido
también allí, y al revés. El cambio automático también es el mismo (los
segundos o los compases se ajustan en la tarjeta del motor Butter).

> **projectM no puede ir de fondo.** projectM es un programa nativo que corre
> en su propia ventana, fuera del navegador, así que el mezclador no puede
> leerlo como capa. El fondo de visuales es siempre Butterchurn — que es el
> mismo MilkDrop, con los mismos presets, dentro del navegador.

## Receta: un personaje recortado sobre las visuales

Es el uso estrella del mezclador y encadena todo lo anterior:

1. **1 · Qué se ve** → **Los dos**.
2. **2 · Fondo** → **Visuales Butter (MilkDrop)**, y elige ahí el preset.
3. **3 · Clip** → un clip de silueta sobre negro (los `_silueta-negro` que
   genera DETEKTION, el proyecto hermano de `VISUALES/`, o cualquier vídeo con
   fondo negro).
4. **4 · Cómo se juntan** → **Recorte (personaje delante)**.

El negro del clip se vuelve transparente y la figura queda **delante** de
MilkDrop, latiendo con la música. En este modo el primer deslizador deja de ser
la mezcla A/B y pasa a llamarse **Umbral del recorte**: súbelo si queda un halo
oscuro alrededor de la figura, bájalo si se está comiendo partes del personaje.

## Paso 1 · Qué se ve

- **Solo el fondo** — a pantalla completa. El clip no se usa.
- **Solo el clip** — a pantalla completa. El fondo no se usa (ni la cámara ni
  las visuales Butter: si eliges esto, el fondo queda atenuado en el panel).
- **Los dos** — se combinan según el paso 4.

Los controles que en ese momento no pintan nada **no desaparecen: se atenúan**,
para que se vea que existen sin que despisten.

## Paso 2 · Fondo (capa de abajo)

**Cámara.** Con la casilla *Cámara activada* y, si tienes más de una, el
desplegable para elegirla. Si la cámara falla, el aviso sale en la banda de
arriba del panel; para reintentar, apaga y enciende la casilla.

**Visuales Butter (MilkDrop).** Lo explicado más arriba. La cámara se libera de
verdad mientras tanto.

## Paso 3 · Clip (capa de encima)

Los clips salen de la carpeta `data/videos/`. Hay dos formas de meterlos:

- **Copiándolos a la carpeta** y pulsando **Actualizar lista**.
- **Con el botón Subir vídeo o imagen**, desde el móvil o el ordenador, sin
  tocar carpetas.

Formatos que van bien:

| Tipo | Formatos | Nota |
|------|----------|------|
| Vídeo | `.mp4` (H.264), `.webm` | En Raspberry, 720p o menos |
| Imagen | `.jpg`, `.png`, `.gif`, `.webp` | Se queda fija como capa |

Los vídeos se reproducen **en bucle y sin sonido** (FOSFENO escucha la música de
la sala, no la del clip).

## Paso 4 · Cómo se juntan

Solo aparece con **Los dos**.

| Modo | Qué hace |
|------|----------|
| **Recorte** | El negro del clip se vuelve transparente: la figura queda **delante** del fondo. El deslizador pasa a ser el umbral |
| **Fundido** | Disuelve una capa sobre la otra según el deslizador de mezcla |
| **Diferencia** | Resta las dos capas: contornos y colores invertidos donde coinciden |
| **Multiplicar** | Oscurece: solo sobrevive lo que es claro en las dos |
| **Sumar** | Aclara: suma la luz de las dos capas |
| **Capa** | Superpone el clip usando su canal alfa |

## Los efectos de color

Se aplican **al resultado ya mezclado**, en este orden (importa: el
caleidoscopio deforma antes de que el color entre en juego):

```
caleidoscopio → rotación → pixelado → tono → saturación → contraste →
brillo → colorama → posterizar → invertir → pulso al ritmo → feedback
```

- **Mezcla A/B** — cuánta capa de encima frente a la de abajo (o el umbral, en
  modo Recorte).
- **Tono / Saturación / Contraste / Brillo** — corrección de color de toda la
  vida.
- **Colorama** — recicla los colores; en valores altos psicodelia pura.
- **Posterizar** — reduce el número de colores por franjas.
- **Pixelado** — baja la resolución aparente en bloques.
- **Caleidoscopio** — repite la imagen en N sectores en espejo.
- **Rotación** — gira la imagen.
- **Feedback** — realimenta el fotograma anterior: estelas y túneles. Con
  valores altos la imagen tarda en limpiarse.
- **Invertir colores** — el negativo.
- **Pulso al ritmo** — la imagen late con los graves detectados (usa el mismo
  análisis de audio que alimenta el BPM).

## Por debajo

El mezclador **no es un motor aparte**: genera código [Hydra](https://hydra.ojack.xyz/)
a partir de los controles y lo ejecuta. La cámara entra como fuente `s0` (o el
lienzo de Butterchurn, si el fondo son visuales) y el clip como `s1`. Por eso
el mezclador y el motor Hydra comparten el mismo lienzo y nunca están activos a
la vez.

Como todo lo que corre en el navegador, la salida del mezclador **se puede
mapear**: ver [Projection mapping](mapping.md).

## Si algo no se ve

FOSFENO no se queda callado: el motivo sale en la banda de avisos, arriba del
panel.

| Aviso | Qué hacer |
|-------|-----------|
| «La cámara está apagada» | Marca *Cámara activada* en el paso 2 |
| «No hay vídeo elegido» | Elige uno en el paso 3 |
| «No hay vídeos» | Sube uno, o copia archivos a `data/videos` y pulsa *Actualizar lista* |
| «No se pudo activar la cámara» | Comprueba el cable, pulsa *Buscar dispositivos de nuevo* y apaga/enciende la casilla |
| «No se pudo cargar …» | El formato no lo traga el navegador: pásalo a `.mp4` (H.264) o `.webm` |

Más casos en [Solución de problemas](problemas.md).