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