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 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/ 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, en la Raspberry, activa el arranque al escritorio:

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 Debian, Ubuntu o Mint. 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 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.

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.