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>

docs/README.md

@@ -0,0 +1,28 @@
+# Documentación de FOSFENO
+
+Esta carpeta reúne todo lo necesario para montar, instalar y usar FOSFENO sin
+tener que adivinar nada. Está pensada para leerse en orden la primera vez y
+para consultarse a saltos después.
+
+- [Requisitos y hardware](requisitos.md)
+  Qué Raspberry Pi necesitas, qué cable va al proyector y, sobre todo, qué
+  micrófonos USB y qué cámaras funcionan sin instalar drivers.
+
+- [Instalación](instalacion.md)
+  Cómo se instala paso a paso y, con detalle, qué descarga y compila el
+  script de instalación en tu Raspberry.
+
+- [Conectarse al panel](conexion.md)
+  Cómo encuentra el usuario el panel de control: el código QR del proyector,
+  la dirección `fosfeno.local` y qué hacer con el router.
+
+- [Uso del panel](uso.md)
+  Cómo se maneja desde el móvil, qué hace cada motor de visuales y cómo se
+  configura cada opción.
+
+- [Solución de problemas](problemas.md)
+  Qué hacer cuando algo no arranca, no se ve o no suena. Incluye cómo leer
+  los mensajes de error que aparecen en el propio panel.
+
+Si solo quieres empezar rápido, el archivo `README.md` de la raíz del
+proyecto tiene la versión resumida.

docs/assets/README.md

@@ -0,0 +1,16 @@
+# Imágenes del proyecto
+
+Aquí va el material gráfico del repositorio.
+
+- `banner.svg` — cabecera del README. Imagen original, vectorial.
+
+Cuando tengas FOSFENO montado, lo ideal es añadir aquí **fotos reales** de tu
+equipo y **capturas** de las visuales funcionando. Son más auténticas que
+cualquier imagen de catálogo y no tienen problemas de licencia. Sugerencias:
+
+- Una foto de la Raspberry Pi conectada al proyector.
+- Una foto de la proyección en marcha durante un evento.
+- Capturas de los distintos motores (Butterchurn, Hydra, Shaders, Mezclador).
+
+Guárdalas en esta carpeta y enlázalas desde el `README.md` o desde la
+documentación de `docs/`.

docs/assets/banner.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="300" viewBox="0 0 960 300">
+  <defs>
+    <filter id="glow" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="7" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <linearGradient id="bars" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#b4ff00"/>
+      <stop offset="1" stop-color="#ff7a00"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="960" height="300" fill="#060a06"/>
+
+  <!-- Ecualizador: barras reactivas al audio -->
+  <g fill="url(#bars)" opacity="0.55">
+    <rect x="8"   y="270" width="24" height="30"/>
+    <rect x="48"  y="252" width="24" height="48"/>
+    <rect x="88"  y="232" width="24" height="68"/>
+    <rect x="128" y="258" width="24" height="42"/>
+    <rect x="168" y="278" width="24" height="22"/>
+    <rect x="208" y="245" width="24" height="55"/>
+    <rect x="248" y="218" width="24" height="82"/>
+    <rect x="288" y="264" width="24" height="36"/>
+    <rect x="328" y="272" width="24" height="28"/>
+    <rect x="368" y="238" width="24" height="62"/>
+    <rect x="408" y="254" width="24" height="46"/>
+    <rect x="448" y="228" width="24" height="72"/>
+    <rect x="488" y="266" width="24" height="34"/>
+    <rect x="528" y="248" width="24" height="52"/>
+    <rect x="568" y="276" width="24" height="24"/>
+    <rect x="608" y="234" width="24" height="66"/>
+    <rect x="648" y="260" width="24" height="40"/>
+    <rect x="688" y="242" width="24" height="58"/>
+    <rect x="728" y="268" width="24" height="32"/>
+    <rect x="768" y="222" width="24" height="78"/>
+    <rect x="808" y="262" width="24" height="38"/>
+    <rect x="848" y="254" width="24" height="46"/>
+    <rect x="888" y="236" width="24" height="64"/>
+    <rect x="928" y="274" width="24" height="26"/>
+  </g>
+
+  <text x="480" y="138" text-anchor="middle" font-family="Arial, Helvetica, sans-serif"
+        font-size="86" font-weight="800" letter-spacing="16"
+        fill="#b4ff00" filter="url(#glow)">FOSFENO</text>
+
+  <text x="480" y="182" text-anchor="middle" font-family="monospace"
+        font-size="19" letter-spacing="2" fill="#cfe8ad">motor de visuales audio-reactivas para raspberry pi</text>
+
+  <line x1="350" y1="204" x2="610" y2="204" stroke="#ff7a00" stroke-width="3"/>
+</svg>

docs/conexion.md

@@ -0,0 +1,89 @@
+# Conectarse al panel
+
+Esta es la parte donde, sin cuidado, la gente se atasca: la Raspberry funciona,
+las visuales salen por el proyector, pero el usuario no sabe en qué dirección
+está el panel de control. FOSFENO está pensado para que ese paso no exista
+como problema.
+
+## La idea: encender y ver
+
+Cuando la Raspberry arranca, antes de ponerse a dibujar visuales, el proyector
+muestra una pantalla de conexión durante unos segundos. En esa pantalla salen
+tres cosas:
+
+- Un código QR grande.
+- La dirección del panel.
+- Un recordatorio de que el móvil tiene que estar en la misma red.
+
+Esa misma pantalla vuelve a aparecer siempre que apagas las visuales desde el
+panel. Así, si en mitad de un evento alguien necesita la dirección, basta con
+darle a apagar y la tiene delante en el proyector.
+
+## Tres formas de entrar, de la más fácil a la menos
+
+**Escanear el código QR.** Abre la cámara del móvil, apúntala al QR que sale en
+el proyector y toca el aviso que aparece. Se abre el panel. No hay que escribir
+nada. Es la forma recomendada.
+
+**Escribir el nombre.** En el navegador del móvil, escribe:
+
+```
+http://fosfeno.local/
+```
+
+Esta dirección no cambia nunca, da igual el día o la red. El instalador le pone
+a la Raspberry el nombre de red `fosfeno`, y `fosfeno.local` es la forma
+estándar de localizar un equipo por su nombre en la red local.
+
+**Escribir la dirección IP.** Es la que aparece en la pantalla de conexión del
+proyector, algo como `http://192.168.1.71/`. Funciona siempre, pero la IP puede
+cambiar de un día para otro, así que es la opción de reserva.
+
+## El móvil tiene que estar en la misma red
+
+El panel es una página local: vive dentro de la Raspberry, no en internet. Para
+abrirla, el móvil y la Raspberry tienen que estar conectados a la misma red:
+el mismo router, ya sea por WiFi o por cable.
+
+No funciona si el móvil está con datos móviles, ni si está en una red WiFi
+distinta (por ejemplo, una red de invitados separada).
+
+## Sobre `fosfeno.local`
+
+El nombre `.local` funciona gracias a un sistema llamado mDNS, que ya viene
+activado en Raspberry Pi OS. Lo entienden los iPhone, los Android modernos,
+Windows y Mac sin instalar nada.
+
+Si en algún móvil viejo `fosfeno.local` no abre, no pasa nada: usa el código QR
+o la dirección IP, que aparecen igualmente en el proyector.
+
+Puedes cambiar ese nombre. Edita `config.json`, el apartado `network.hostname`,
+y vuelve a ejecutar `bash install.sh`. El panel quedará entonces en
+`http://el-nombre-que-pongas.local/`.
+
+## Sobre el router
+
+No hace falta tocar nada en el router. FOSFENO no abre puertos hacia internet
+ni necesita configuración especial. Solo usa la red local.
+
+Un único ajuste es recomendable, aunque opcional: entrar en el router y
+reservarle a la Raspberry siempre la misma IP (lo que se suele llamar reserva
+DHCP o IP fija). Así la dirección IP no cambia nunca. De todas formas, como el
+nombre `fosfeno.local` ya es fijo, puedes saltarte esto sin problema.
+
+Para un evento, el cable de red entre la Raspberry y el router es más fiable
+que el WiFi.
+
+## Si no consigues conectar
+
+Repasa estas cosas, en orden:
+
+- El móvil está en la misma red WiFi que la Raspberry, no en datos móviles.
+- Has escrito `http://` delante, y la barra `/` al final.
+- Prueba las tres vías: primero el QR, si no el nombre, si no la IP.
+- Mira la pantalla de conexión del proyector: la dirección que sale ahí es la
+  buena en este momento.
+
+Si el proyector no muestra ni siquiera la pantalla de conexión, el problema no
+es de red sino de arranque; en ese caso mira la guía de
+[solución de problemas](problemas.md).

docs/instalacion.md

@@ -0,0 +1,121 @@
+# Instalación
+
+La instalación es un único comando. Aun así, conviene saber qué hace por
+dentro, porque descarga y compila bastantes cosas y el proceso tarda.
+
+## Antes de empezar
+
+Necesitas Raspberry Pi OS Bookworm de 64 bits con el escritorio instalado, no
+la versión Lite. FOSFENO muestra las visuales dentro de una ventana de
+Chromium a pantalla completa, así que hace falta entorno gráfico.
+
+Conviene tener la Raspberry conectada a internet por cable durante la
+instalación. Se descargan paquetes del sistema, librerías y el código fuente
+de projectM.
+
+## El comando
+
+```
+git clone <URL-de-tu-gitlab>/fosfeno.git
+cd fosfeno
+bash install.sh
+```
+
+El instalador va informando de cada paso con una marca delante:
+
+- `[ OK ]` el paso terminó bien.
+- `[ !! ]` hubo un aviso. No es grave, pero conviene leerlo.
+- `[ XX ]` hubo un fallo que detiene la instalación.
+
+Al final resume cuántos avisos hubo. Si todo sale con `[ OK ]`, la
+instalación está limpia.
+
+## Qué se instala automáticamente
+
+El script trabaja en nueve fases. Esto es lo que hace cada una.
+
+**Comprobación del sistema.** Detecta si la placa es una Pi 4 o una Pi 5, mira
+la versión del sistema operativo y la arquitectura. Si algo no encaja avisa,
+pero te deja seguir.
+
+**Paquetes del sistema.** Instala con apt lo que hace falta para que todo lo
+demás funcione:
+
+- Python 3 y su gestor de entornos virtuales.
+- Chromium, el navegador donde se dibujan las visuales.
+- Node.js y npm, para descargar las librerías de visuales.
+- Git, CMake y las herramientas de compilación, necesarias para projectM.
+- Las librerías de desarrollo de SDL2, OpenGL ES y POCO, que projectM usa al
+  compilar.
+- Las utilidades de PulseAudio, para detectar el micrófono.
+- v4l-utils, para reconocer la cámara USB.
+- xdotool y unclutter, para el control de projectM y para esconder el ratón.
+
+**Verificación de versiones.** Comprueba que Python, Node, npm y CMake
+cumplen una versión mínima. Si alguna se queda corta lo dice claramente.
+Cuando es CMake quien no llega, salta la compilación de projectM en lugar de
+fallar entera.
+
+**Entorno de Python.** Crea un entorno virtual aislado e instala Flask y
+Flask-SocketIO, que son el servidor web del proyecto. Después comprueba que
+esas librerías se importan de verdad.
+
+**Librerías de visuales.** Con npm descarga Butterchurn y sus presets, Hydra,
+el cliente de Socket.IO y CodeMirror, que es el editor de código del panel.
+Copia los archivos que se usan a una carpeta `web/lib` y verifica uno por uno
+que cada copia existe y no está vacía.
+
+**projectM.** Compila projectM desde su código fuente. Esto es lo que más
+tarda, entre diez y veinte minutos en una Raspberry. Si la compilación falla,
+el instalador lo avisa y sigue adelante: FOSFENO funciona igual con los otros
+cuatro motores. Puedes saltarte este paso desde el principio con
+`bash install.sh --no-projectm`.
+
+**Recursos.** Descarga un paquete de presets para projectM y crea la carpeta
+`data/videos`, donde copiarás tus clips para el modo Mezclador.
+
+**Arranque automático.** Configura la Raspberry para que, al encender el
+escritorio, lance FOSFENO sola. También da permiso para reiniciar y apagar la
+placa desde el panel sin pedir contraseña.
+
+**Puerto 80.** Da permiso a Python para usar el puerto 80, que es lo que
+permite abrir el panel en `http://la-ip-de-tu-pi/` sin escribir ningún número
+de puerto detrás.
+
+## Después de instalar
+
+Falta un ajuste que el script no puede hacer por ti. Hay que decirle a la
+Raspberry que arranque sola en el escritorio:
+
+```
+sudo raspi-config
+```
+
+Dentro, ve a `System Options`, luego `Boot / Auto Login`, y elige
+`Desktop Autologin`. Sal y reinicia:
+
+```
+sudo reboot
+```
+
+Al volver, la Raspberry arranca directa en modo kiosko mostrando las
+visuales. El panel queda disponible en `http://la-ip-de-tu-pi/`.
+
+## Comprobar el sistema sin reinstalar
+
+Si quieres revisar que todo sigue en su sitio, o diagnosticar un problema, hay
+un modo que solo comprueba y no toca nada:
+
+```
+bash install.sh --check
+```
+
+Lista las versiones de las herramientas y dice si projectM y Chromium están
+presentes.
+
+## Volver a ejecutar el instalador
+
+El script se puede ejecutar las veces que quieras. No repite el trabajo ya
+hecho: no vuelve a compilar projectM si ya está, ni vuelve a descargar los
+presets si ya están. Es seguro relanzarlo si una instalación se cortó a
+medias.

docs/problemas.md

@@ -0,0 +1,117 @@
+# Solución de problemas
+
+FOSFENO intenta no quedarse callado cuando algo va mal. La mayoría de fallos
+salen como aviso en la parte de arriba del panel. Aun así, aquí tienes los
+casos más habituales y cómo resolverlos.
+
+## El panel no carga
+
+Comprueba que el móvil y la Raspberry están en la misma red. Prueba a entrar
+con la IP exacta de la Raspberry. Si configuraste el puerto 8080, recuerda
+escribir `:8080` detrás de la dirección.
+
+Si la IP responde pero la página no aparece, puede que el servidor no haya
+arrancado. Conéctate a la Raspberry y míralo a mano:
+
+```
+cd ~/fosfeno
+.venv/bin/python3 backend/server.py
+```
+
+Los mensajes que imprime ahí, los que empiezan por `[FOSFENO]`, dicen qué
+está pasando.
+
+## No se ven visuales en el proyector
+
+Mira si el proyector tiene señal. Si está en negro pero el panel funciona,
+revisa que las visuales estén encendidas con el botón de encendido.
+
+Si la pantalla está en negro y en el panel no hay forma de que aparezca nada,
+Chromium puede no haberse abierto. El servidor lo reabre solo cada pocos
+segundos, así que espera un poco. Si no, reinicia la Raspberry desde el panel
+o desde la consola.
+
+## No hay sonido o el BPM marca cero
+
+El BPM en cero quiere decir que FOSFENO no está recibiendo audio, o que el
+audio es demasiado flojo.
+
+Comprueba que el micrófono USB está conectado. En el apartado Audio del panel,
+abre el desplegable y elige a mano la entrada correcta. Si tu micrófono no
+aparece, conéctalo y reinicia la Raspberry, porque la lista se hace al
+arrancar.
+
+Si el audio entra pero el BPM no se estabiliza, sube la sensibilidad. El
+detector de ritmo necesita música con un pulso claro; con música muy suave o
+sin percusión puede no encontrar el tempo, y a veces marca el doble o la
+mitad del valor real.
+
+## La cámara no funciona en el Mezclador
+
+Tiene que ser una webcam USB que cumpla el estándar UVC. El módulo de cámara
+con cable plano de la Raspberry no sirve en esta versión.
+
+Conecta la cámara antes de encender la Raspberry. Si la conectas con el
+sistema ya arrancado, reinicia. Si en el panel sale un aviso de que la cámara
+no responde, es que el sistema no la ve; pruébala en otro puerto USB o con
+otro cable.
+
+## projectM no está disponible
+
+Si al elegir projectM sale un aviso de que no está instalado, es que su
+compilación falló o se saltó durante la instalación. No es grave: los otros
+cuatro motores funcionan igual.
+
+Para intentar compilarlo de nuevo:
+
+```
+cd ~/fosfeno
+bash scripts/build-projectm.sh
+```
+
+Ese script avisa en qué paso falla. Lo más habitual es que falte alguna
+librería de desarrollo; vuelve a lanzar `bash install.sh` para reinstalar las
+dependencias del sistema.
+
+## Las visuales van a tirones
+
+Suele ser calor. Una Raspberry sin disipador, después de un rato con visuales,
+se calienta y baja su velocidad para protegerse. Ponle disipador o ventilador.
+
+También ayuda usar motores más ligeros. Butterchurn e Hydra van más sueltos
+que los shaders pesados o que el mezclador de vídeo. En el Mezclador, usa
+clips de vídeo en 720p o menos.
+
+## Un shader o un código de Hydra da error
+
+Cuando un shader no compila, o un código de Hydra falla, sale un aviso en el
+panel diciéndolo. La descripción detallada del error aparece en la consola del
+navegador de la Raspberry, no en el panel, porque suele ser un mensaje
+técnico largo.
+
+Revisa el código. Si lo pegaste de fuera, comprueba que es código de Hydra y
+no de otra herramienta, y que está completo.
+
+## Revisar el estado del sistema
+
+Para comprobar de una vez si las herramientas están bien instaladas:
+
+```
+cd ~/fosfeno
+bash install.sh --check
+```
+
+No instala nada. Solo informa de las versiones y de si projectM y Chromium
+están presentes.
+
+## Empezar de cero
+
+Si quieres quitar FOSFENO sin borrar el código:
+
+```
+cd ~/fosfeno
+bash uninstall.sh
+```
+
+Eso quita el arranque automático y los permisos, y cierra los procesos. El
+código sigue en su carpeta por si quieres volver a instalarlo.

docs/requisitos.md

@@ -0,0 +1,97 @@
+# Requisitos y hardware
+
+FOSFENO funciona en una Raspberry Pi conectada a un proyector. La Raspberry
+escucha el sonido de la sala a través de un micrófono USB y dibuja visuales
+que reaccionan a la música. Todo se gobierna desde el móvil con un navegador.
+
+## Raspberry Pi
+
+Sirve una Raspberry Pi 4 o una Raspberry Pi 5. La Pi 5 va más holgada con los
+shaders y el mezclador de vídeo, así que es la recomendada si vas a usar esos
+modos a menudo. La Pi 4 cumple de sobra para Butterchurn e Hydra.
+
+Necesitas además:
+
+- La fuente de alimentación oficial. Los visuales exigen GPU y CPU; con
+  cargadores genéricos la Pi puede reiniciarse sola.
+- Una tarjeta microSD de 32 GB o más, o mejor un SSD por USB en la Pi 5.
+- Disipador o ventilador. Mantener visuales en bucle calienta la placa, y si
+  se calienta de más reduce su velocidad y las visuales van a tirones.
+- Sistema operativo Raspberry Pi OS Bookworm de 64 bits, con escritorio.
+
+## Conexión con el proyector
+
+La Pi 4 y la Pi 5 llevan salida micro-HDMI, no HDMI normal. Necesitas un cable
+micro-HDMI a HDMI, o un adaptador. Cualquier proyector con entrada HDMI vale.
+La resolución la ajusta el sistema; si el proyector es de 1280x720 las
+visuales irán más finas que a 1080p.
+
+## Red
+
+El panel de control se abre desde el móvil, así que el móvil y la Raspberry
+tienen que estar en la misma red. El cable Ethernet es más estable que el
+WiFi para un evento, pero las dos opciones funcionan. Conviene fijar la IP de
+la Raspberry en el router para que no cambie entre un día y otro.
+
+## Micrófono USB y audio
+
+La Raspberry Pi no tiene entrada de audio. El conector jack de la placa es
+solo salida. Para que FOSFENO oiga la música hay que añadir una entrada por
+USB.
+
+Funcionan sin instalar nada los dispositivos que cumplen el estándar USB
+Audio Class. En la práctica eso es casi todo lo que se vende hoy:
+
+- Tarjetas de sonido USB. Son adaptadores pequeños con un USB por un lado y
+  conectores jack por el otro. Las que traen entrada de micrófono o entrada
+  de línea sirven para enchufar el sonido desde una mesa de mezclas o desde
+  un móvil. Dan la señal más limpia.
+- Micrófonos USB. Los micrófonos de condensador tipo podcast (Fifine, Samson,
+  Blue Snowball y similares) se conectan directos y captan el sonido de la
+  sala. Es la opción más cómoda si no quieres tirar cables.
+- Interfaces de audio USB y auriculares USB con micro. También valen mientras
+  sean USB Audio Class, que es lo normal.
+
+Evita los micrófonos Bluetooth. Tienen retardo y FOSFENO no los selecciona de
+forma automática. Evita también cualquier aparato que pida un driver del
+fabricante; con audio es raro, pero los hay.
+
+FOSFENO elige la entrada automáticamente al arrancar. Busca entre las fuentes
+de audio del sistema la primera cuyo nombre contenga la palabra `usb`. Si tu
+dispositivo no se llama así, puedes cambiar esa palabra clave en `config.json`,
+en el apartado `audio.matchSource`. Desde el panel también puedes elegir a
+mano cualquier entrada detectada.
+
+Recomendación práctica: para un evento con mesa de DJ, una tarjeta USB con
+entrada de línea conectada por jack a la salida de la mesa. Para algo casero o
+una fiesta, un micrófono USB que recoja el ambiente.
+
+## Cámara USB
+
+La cámara solo hace falta para el modo Mezclador. FOSFENO está preparado para
+cámaras web USB.
+
+Funcionan sin drivers las cámaras que cumplen el estándar USB Video Class,
+conocido como UVC. Prácticamente todas las cámaras web USB modernas lo
+cumplen: las de Logitech, las genéricas, las de portátil externas. Conéctala
+antes de encender la Raspberry y el sistema la reconoce sola. El navegador la
+ve a través de V4L2, el subsistema de vídeo de Linux.
+
+Esta versión de FOSFENO no usa el módulo de cámara oficial de la Raspberry, el
+que va con cable plano al conector CSI. En Raspberry Pi OS Bookworm ese módulo
+funciona a través de libcamera y no aparece como cámara estándar para el
+navegador sin pasos extra. Si quieres cámara, usa una webcam USB UVC.
+
+Recomendación práctica: cualquier webcam USB de 720p sirve. No hace falta
+nada caro. Si la cámara permite varias resoluciones, el navegador elige una
+compatible automáticamente.
+
+## Resumen de la lista de la compra
+
+- Raspberry Pi 4 o 5 con su fuente oficial.
+- microSD de 32 GB o SSD USB.
+- Disipador o ventilador.
+- Cable micro-HDMI a HDMI.
+- Micrófono USB o tarjeta de sonido USB con entrada.
+- Webcam USB UVC, solo si vas a usar el modo Mezclador.
+- Cable de red, o WiFi.

docs/uso.md

@@ -0,0 +1,103 @@
+# Uso del panel
+
+Cuando la Raspberry arranca, las visuales salen solas por el proyector. Todo
+lo demás se controla desde el panel.
+
+## Entrar en el panel
+
+Al arrancar, el proyector muestra una pantalla con un código QR y la dirección
+del panel. Escanea el QR con la cámara del móvil y el panel se abre solo. Si
+prefieres escribirla, la dirección es `http://fosfeno.local/`.
+
+El móvil tiene que estar en la misma red que la Raspberry. La explicación
+completa, con las tres formas de conectar y los detalles del router, está en
+[Conectarse al panel](conexion.md).
+
+Arriba a la derecha del panel hay un punto. Verde quiere decir que está
+conectado con la Raspberry. Rojo quiere decir que se ha perdido la conexión.
+
+## Avisos y errores
+
+Justo debajo de la cabecera aparecen los avisos. Si algo va mal (la cámara no
+responde, un shader tiene un error de código, projectM no está instalado), el
+mensaje sale ahí en lugar de quedarse el sistema callado. Los avisos
+informativos desaparecen solos. Los errores se quedan hasta que los cierras,
+para que no se te escapen.
+
+## Encendido
+
+El botón grande de encendido pone las visuales en marcha o las apaga. Apagar
+deja el proyector en negro sin tener que apagar la Raspberry.
+
+## Los cinco motores
+
+Se eligen con los botones redondos. Solo uno está activo a la vez.
+
+**projectM.** El visualizador clásico de MilkDrop, compilado en la propia
+Raspberry. Reacciona al audio por sí solo y va rotando entre miles de
+presets. Es un programa nativo, así que cuando lo eliges su ventana se pone
+por encima de las demás visuales.
+
+**Butterchurn.** Es MilkDrop reescrito para el navegador. Tiene los mismos
+miles de presets. Puedes elegir un preset concreto, dejar que cambie solo cada
+ciertos segundos, o que cambie sincronizado con el ritmo de la música.
+
+**Hydra.** Visuales generados por código. Trae un editor integrado donde
+puedes escribir o pegar código de Hydra y ejecutarlo al momento. Incluye una
+librería de fragmentos listos para usar; eliges uno y se carga en el editor.
+
+**Shaders.** Shaders GLSL, el tipo de visual de Shadertoy. También trae editor
+de código. Los shaders reciben información del audio y del ritmo, así que se
+mueven con la música.
+
+**Mezclador.** El modo de vídeo. Mezcla la imagen de una webcam USB con clips
+de vídeo y efectos de color. Es lo más parecido a un programa de VJ como
+Resolume, pero funcionando dentro de la Raspberry.
+
+## Audio y BPM
+
+La tarjeta de audio se elige en el apartado Audio del panel. Por defecto
+FOSFENO coge el micrófono USB automáticamente, pero si tienes varias entradas
+puedes cambiarla ahí.
+
+Justo al lado se ve el BPM detectado. FOSFENO analiza el sonido y estima a
+cuántos pulsos por minuto va la música. Ese valor lo usan los motores para
+sincronizarse: los shaders, Hydra y el cambio de preset de Butterchurn al
+compás. El BPM tarda unos segundos en estabilizarse y funciona mejor con
+música de pulso marcado.
+
+La sensibilidad ajusta cuánto reaccionan las visuales al volumen. Si la sala
+suena floja, súbela. Si todo se ve saturado, bájala.
+
+## El editor de código
+
+En Hydra y en Shaders aparece un editor. Funciona igual en los dos:
+
+- El desplegable de la librería carga un ejemplo. Al elegirlo, el código entra
+  en el editor y se ejecuta al momento.
+- Puedes modificar ese código o pegar uno tuyo. El botón Ejecutar lanza lo que
+  haya en el editor.
+- El botón Limpiar vacía el editor.
+
+En Hydra el código es JavaScript de Hydra y tienes disponibles `time`, los
+valores de audio `a.fft[0]` a `a.fft[4]` y la variable `bpm`. En Shaders el
+código es GLSL y tienes los uniforms `u_time`, `u_bass`, `u_mid`, `u_treble`,
+`u_bpm`, `u_beat` y la textura `u_fft`.
+
+## El modo Mezclador
+
+Primero copia tus clips de vídeo en la carpeta `data/videos` del proyecto.
+Aparecen solos en el desplegable de vídeo del panel. Para que vayan finos en
+la Raspberry conviene que sean clips cortos, en 720p o menos y en H.264.
+
+En el panel eliges la fuente: solo la cámara, solo el vídeo, o la mezcla de
+las dos. Debajo tienes el modo de mezcla y una fila de controles de color:
+tono, saturación, contraste, brillo, colorama, posterizado, pixelado,
+caleidoscopio, rotación y feedback. La casilla de pulso al ritmo hace que la
+imagen lata con los graves.
+
+## Apagar y reiniciar
+
+Abajo del todo están los botones para reiniciar y apagar la Raspberry. Piden
+confirmación. Apagar desde aquí es la forma correcta de apagar la placa al
+terminar, mejor que cortar la corriente.