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