fosfeno/README.md

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/ tiene la guía completa:

• Requisitos y hardware — qué Raspberry, qué micrófono USB y qué cámara usar para que se reconozcan solos.
• Instalación — qué descarga y compila el instalador.
• Conectarse al panel — el código QR, fosfeno.local y el router.
• Uso del panel — cómo se maneja y qué hace cada motor.
• Solución de problemas — 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):

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:

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.

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, 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.