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