fosfeno/README.md

<div align="center">
  <img src="docs/assets/banner.svg" alt="FOSFENO" width="900">
</div>

# FOSFENO

<div align="center">
  <img src="docs/assets/milkdrop.jpg" alt="Visuales audio-reactivas" width="600">
</div>

**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.71/
   │     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.
- [Solución de problemas](docs/problemas.md) — qué hacer cuando algo falla.

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:

<div align="center">
  <img src="docs/assets/hydra.png" alt="Hydra" width="940">
</div>

## 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

<div align="center">
  <img src="docs/assets/raspberry-pi-5.jpg" alt="Raspberry Pi 5" width="460">
</div>

## Instalación

En Raspberry Pi OS Bookworm (64 bits, con escritorio):

```bash
git clone <URL-de-tu-gitlab>/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:

<div align="center">
  <img src="docs/assets/panel.png" alt="Panel de control de FOSFENO" width="940">
</div>

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**: activar la cámara, elegir un clip de vídeo, modo de
  mezcla y efectos de color (tono, saturación, colorama, posterizado,
  pixelado, caleidoscopio, feedback, invertir…).

FOSFENO en acción — vídeo corto de demostración:

<div align="center">
  <video src="docs/assets/demo.mp4" controls width="940"></video>
</div>

Si el reproductor no se ve, descarga el vídeo: [demo.mp4](docs/assets/demo.mp4)

### Modo Mezclador (cámara + vídeo)

Copia tus clips en `data/videos/` (formatos `.mp4`, `.webm`, `.mov`…) y
aparecerán en el panel. El mezclador genera código Hydra por debajo a partir
de los controles, así que mezcla en tiempo real la webcam, los clips y los
efectos de color — el equivalente a Resolume, pero corriendo en la propia Pi.

## 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/                  Escenario en Chromium (todos los motores web)
├── docs/                       Documentación completa
├── 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.*