FOSFENO/README.md

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.XX/
   │     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.
• El Mezclador VJ — las mezclas: las dos capas, visuales de fondo, modos de mezcla y efectos.
• Projection mapping — deformar las visuales para encajarlas en superficies físicas (malla, máscaras) desde el panel.
• Solución de problemas — qué hacer cuando algo falla.
• Seguridad — el panel está abierto a la red local por defecto; cómo cerrarlo con una clave si pinchas fuera de casa.
• Arquitectura — 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.

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

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

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.

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