FOSFENO: motor de visuales audio-reactivas para Raspberry Pi

Primera version. Cinco motores (projectM, Butterchurn, Hydra, Shaders GLSL y mezclador VJ con camara y video), panel de control web, deteccion de BPM propia, pantalla de conexion con codigo QR, instalador robusto para Raspberry Pi 4 y 5 y documentacion completa en docs/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 14:18:19 +02:00 · 2026-05-22 14:18:19 +02:00 · 30a09fdee6
commit 30a09fdee6
31 changed files with 3478 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,170 @@
+![FOSFENO](docs/assets/banner.svg)
+
+# FOSFENO
+
+**Motor de visuales audio-reactivas para Raspberry Pi.**
+Convierte una Raspberry Pi + un proyector + un micro USB en una estación de
+VJ automática: la Pi escucha la música de la sala, detecta su BPM y proyecta
+visuales que reaccionan al sonido. Todo se controla desde un panel web.
+
+```
+   [ 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        |
+
+## 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 <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:
+
+```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.
+
+## 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).
+
+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…).
+
+### 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.*