# FOSFENO
**Motor de visuales audio-reactivas para Raspberry Pi y para portátil Linux.**
Convierte una Raspberry Pi + un proyector + un micro USB en una estación de
VJ automática: escucha la música de la sala, detecta su BPM y proyecta
visuales que reaccionan al sonido. Todo se controla desde un panel web.
Funciona en dos escenarios: en una **Raspberry Pi** como aparato dedicado que
arranca solo, o en un **portátil Linux** que lanzas cuando quieras. El apartado
[En un portátil Linux](#en-un-portátil-linux) explica las diferencias.
```
[ Música en la sala ]
│ (micro USB)
▼
┌──────────────────┐ Wi-Fi / Ethernet
│ Raspberry Pi 5 │◀─────────────────────────── http://192.168.1.XX/
│ FOSFENO │ (panel en el móvil)
└────────┬─────────┘
│ micro-HDMI
▼
[ Proyector :: visuales ]
```
## Documentación
La carpeta [`docs/`](docs/) tiene la guía completa:
- [Requisitos y hardware](docs/requisitos.md) — qué Raspberry, qué micrófono
USB y qué cámara usar para que se reconozcan solos.
- [Instalación](docs/instalacion.md) — qué descarga y compila el instalador.
- [Conectarse al panel](docs/conexion.md) — el código QR, `fosfeno.local` y
el router.
- [Uso del panel](docs/uso.md) — cómo se maneja y qué hace cada motor.
- [El Mezclador VJ](docs/mezclador.md) — las mezclas: las dos capas, visuales
de fondo, modos de mezcla y efectos.
- [Projection mapping](docs/mapping.md) — deformar las visuales para encajarlas
en superficies físicas (malla, máscaras) desde el panel.
- [Solución de problemas](docs/problemas.md) — qué hacer cuando algo falla.
- [Seguridad](docs/seguridad.md) — el panel está abierto a la red local por
defecto; cómo cerrarlo con una clave si pinchas fuera de casa.
- [Arquitectura](docs/arquitectura.md) — para tocar el código: piezas, estado,
eventos y cómo añadir un motor.
El panel además lleva un botón de información en cada apartado: explica qué
es, qué necesita y cómo se configura, sin salir del propio panel.
## Motores de visuales
Los cinco se eligen y configuran desde el panel, en caliente:
| Motor | Qué es |
|----------------|------------------------------------------------------------|
| **projectM** | Visualizador MilkDrop nativo, compilado en la Pi |
| **Butterchurn**| MilkDrop en WebGL, miles de presets |
| **Hydra** | Código Hydra en vivo: editor + librería de fragmentos |
| **Shaders** | Shaders GLSL audio-reactivos (estilo Shadertoy), con editor|
| **Mezclador** | VJ tipo Resolume: cámara + clips de vídeo + efectos |
Visuales de ejemplo — el motor Hydra con su editor de código en vivo:
## Projection mapping por capas
Las visuales se pueden **deformar para encajarlas en superficies físicas** desde
el panel: malla deformable (curvas), varias zonas a la vez y máscaras para tapar
derrames, arrastrando con el ratón o el dedo.
Y cada zona es una **capa con su propio visual**: MilkDrop a la derecha, otro
preset distinto a la izquierda y un vídeo en el centro, a la vez.
| Fuente de una capa | Qué es |
|--------------------|--------|
| El motor de MOTORES | Lo que esté puesto en la otra pestaña del panel |
| Visuales MilkDrop propias | Un Butterchurn solo para esa capa, con su preset |
| Shader GLSL | Un shader de la librería, reactivo al audio |
| Clip o imagen | Un archivo de `data/videos`, en bucle |
| Cámara | La webcam |
| Negro | Tapa la zona |
Con opacidad y mezcla (normal o aditiva) por capa. Se guarda solo en
`data/mapping.json`. Guía: [docs/mapping.md](docs/mapping.md).
## Hardware necesario
- Raspberry Pi 5 o Pi 4 + fuente oficial + microSD/SSD
- Cable **micro-HDMI → HDMI** para el proyector
- **Micrófono USB** (la Pi no tiene entrada de audio propia)
- **Webcam USB** (opcional, para el modo Mezclador)
- Disipador o ventilador (las visuales tiran de GPU)
- Red por Ethernet o Wi-Fi
## Instalación
En Raspberry Pi OS Bookworm (64 bits, con escritorio):
```bash
git clone /fosfeno.git
cd fosfeno
bash install.sh
```
El instalador es robusto: detecta si es **Pi 4 o Pi 5**, comprueba el sistema
operativo, **verifica las versiones** de cada herramienta (Python, Node, npm,
CMake) y avisa con `[ OK ]` / `[ !! ]` / `[ XX ]` de cada paso.
```
bash install.sh # instala todo (incluido projectM)
bash install.sh --no-projectm # omite la compilación de projectM
bash install.sh --check # solo comprueba el sistema, no instala nada
```
Después, en la Raspberry, activa el arranque al escritorio:
```bash
sudo raspi-config # System Options → Boot/Auto Login → Desktop Autologin
sudo reboot
```
Al reiniciar, la Pi arranca sola en modo kiosko mostrando las visuales.
### En un portátil Linux
FOSFENO no necesita la Raspberry: corre igual en un portátil con Linux. El
instalador reconoce las familias más comunes —Debian/Ubuntu/Mint, Fedora,
Arch/Manjaro y openSUSE— e instala las dependencias con el gestor de cada
una (`apt`, `dnf`, `pacman` o `zypper`). El portátil ya trae micrófono y
cámara, y lo conectas al proyector por HDMI como cualquier otra cosa.
```
[ Música de la sala ]
│ (micrófono integrado, o USB)
▼
┌────────────────────────┐
│ Portátil Linux │── HDMI ──▶ [ Proyector :: visuales ]
│ ./fosfeno │
└───────────┬────────────┘
│
Panel: http://localhost:8080/
(o desde el móvil, en la misma red Wi-Fi)
```
Se instala una vez y se arranca a mano cuando lo necesites:
```bash
bash install.sh --laptop # instala, sin tocar el arranque del sistema
./fosfeno # arranca FOSFENO; Ctrl+C para cerrarlo
```
Diferencias con la Raspberry Pi:
| | Raspberry Pi | Portátil Linux |
|---|---|---|
| Arranque | Automático al encender | A mano, con `./fosfeno` |
| Modo kiosko | Sí: visuales a pantalla completa al arrancar | **No**: ventana normal que mueves al proyector |
| Puerto del panel | 80 — `http://fosfeno.local/` | 8080 — `http://localhost:8080/` |
| Micrófono y cámara | Por USB | Los integrados del portátil |
| Cambios en el sistema | Arranque automático y nombre de red | Ninguno |
La diferencia clave: en el portátil **no se usa el modo kiosko**. Las visuales
salen en una ventana de navegador normal que arrastras a la pantalla del
proyector y pones a pantalla completa con F11. Así FOSFENO no se apodera de tu
pantalla ni se mete en el arranque del sistema; lo abres y lo cierras tú.
Guía completa: [FOSFENO en un portátil](docs/portatil.md).
## Uso
- **Visuales** → salen automáticamente por el proyector (HDMI).
- **Panel de control** → al arrancar, el proyector muestra un **código QR** y
la dirección. Escanéalo con el móvil y el panel se abre. También se llega
escribiendo `http://fosfeno.local/`. El móvil debe estar en la misma red.
Ver [Conectarse al panel](docs/conexion.md).
Así se ve el panel de control:
El panel tiene dos pestañas, a la derecha del título: **MOTORES** (el directo)
y **MAPPING** (el montaje sobre la superficie física).
Desde el panel puedes:
- Encender/apagar las visuales y cambiar de motor.
- Elegir la **tarjeta de audio** y ver el **BPM detectado** en vivo.
- Ajustar la sensibilidad al audio.
- **Butterchurn**: presets, transición, cambio automático por segundos o
**sincronizado al compás**.
- **Hydra / Shaders**: editor de código integrado para **escribir o pegar**
tu propio código, más una **librería de fragmentos** lista para cargar.
- **Mezclador VJ**: elegir el fondo (cámara o visuales MilkDrop), el clip de
encima, el modo de mezcla y los efectos de color (tono, saturación,
colorama, posterizado, pixelado, caleidoscopio, feedback, invertir…).
- **Mapping**: encajar la imagen sobre la superficie física arrastrando los
puntos, con malla deformable y máscaras.
FOSFENO en acción — vídeo corto de demostración:
Si el reproductor no se ve, descarga el vídeo: [demo.mp4](docs/assets/demo.mp4)
### Modo Mezclador (cámara + vídeo + visuales de fondo)
El mezclador monta **dos capas**: un **fondo** —la webcam o las propias
**visuales MilkDrop**— y un **clip** encima (vídeo o imagen), combinados con el
modo de mezcla y los efectos de color. Con un clip de silueta sobre negro y el
modo *Recorte*, el personaje queda **delante de MilkDrop** latiendo con la
música.
Los clips se copian a `data/videos/` (`.mp4` H.264, `.webm`, imágenes) o se
suben desde el propio panel. Por debajo, el mezclador genera código Hydra a
partir de los controles: el equivalente a Resolume, corriendo en la propia Pi.
Guía completa: [El Mezclador VJ](docs/mezclador.md).
## Estructura
```
FOSFENO/
├── install.sh / uninstall.sh Instalador robusto y desinstalador
├── config.json Configuración (puerto, micro, valores por defecto)
├── backend/server.py Servidor: web + WebSocket + gestión de procesos
├── scripts/lib.sh Funciones de los scripts (logs, versiones)
├── web/panel/ Panel de control (móvil)
├── web/stage/stage.js Escenario en Chromium (todos los motores web)
├── web/stage/mapper.js Compositor de projection mapping (WebGL)
├── docs/ Documentación completa
├── docs/arquitectura.md Cómo está montado, para tocar el código
├── data/hydra-sketches.json Sketches de Hydra de fábrica
├── data/hydra-snippets.json Librería de fragmentos de Hydra para el editor
├── data/shaders.json Shaders GLSL (editables)
├── data/ayuda.json Textos de ayuda que muestra el panel
└── data/videos/ Tus clips de vídeo para el Mezclador
```
Cuando algo falla (un error de código, una cámara que no responde, projectM
sin instalar), FOSFENO no se queda callado: el aviso aparece en una banda en
la parte de arriba del panel, con el color según su gravedad.
## Detección de BPM
FOSFENO incluye un detector de ritmo propio (análisis de energía de graves
en tiempo real) que estima el BPM de la música ambiente. El BPM se muestra en
el panel y alimenta a todos los motores:
- **Shaders**: uniforms `u_bpm` y `u_beat` (fase 0..1 sincronizada al pulso).
- **Hydra**: actualiza la variable global `bpm` (la usan `.fast()`, etc.).
- **Butterchurn**: cambio de preset cada N compases.
## Configuración (`config.json`)
- `server.port` — puerto del panel. `80` permite `http://IP/` sin puerto;
si da problemas de permisos, cámbialo a `8080`.
- `audio.matchSource` — subcadena para localizar el micro USB (por defecto `usb`).
- `defaults` — motor, sensibilidad, sketch de Hydra y shader al arrancar.
## Notas
- **Pi 5 usa Wayland.** El cambio manual de preset en projectM solo funciona
en sesión X11; en Wayland projectM rota presets automáticamente. El resto
de motores no se ven afectados.
- Para el Mezclador, usa clips de vídeo ligeros (720p o menos, H.264).
- Los fragmentos de Hydra de `data/hydra-snippets.json` están adaptados de
ejemplos de la comunidad de Hydra
([hydra-synth/hydra](https://github.com/hydra-synth/hydra),
[zachkrall/hydra-examples](https://github.com/zachkrall/hydra-examples)).
- Uniforms de los shaders GLSL: `u_resolution`, `u_time`, `u_bass`, `u_mid`,
`u_treble`, `u_level`, `u_bpm`, `u_beat`, `u_fft`.
---
*Parte de COFRE/CODERS — creative coding audio-reactivo.*
