FOSFENO/docs/problemas.md

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, pulsa «Buscar dispositivos», abre el desplegable, elige la entrada correcta y pulsa «Aplicar entrada». Ya no hace falta reiniciar para que aparezcan entradas nuevas.

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.

Si al arrancar sale el aviso «Sin entrada de audio», las visuales siguen funcionando pero no reaccionan a la música: conecta un micrófono (o elige «Audio del navegador») y pulsa «Buscar dispositivos» y «Aplicar entrada».

El audio del navegador (Spotify, YouTube) no mueve las visuales

La fuente «Audio del navegador» captura lo que suena en el propio equipo usando el «monitor» de PulseAudio/PipeWire. Chromium no deja elegir ese monitor directamente, así que FOSFENO mueve la captura por su cuenta con pactl. Eso vale para todos los motores, projectM incluido (projectM captura siempre la entrada por defecto y FOSFENO recoloca su stream al lanzarlo).

Si no reacciona:

• Pon algo a sonar primero y pulsa «Aplicar entrada».
• Si cambias de salida (conectas o quitas unos cascos bluetooth, cambias a HDMI...), la captura se queda en la salida antigua: pulsa «Aplicar entrada» otra vez para que se recoloque en la nueva.
• Lee el aviso del panel: si dice que no pudo mover la captura o averiguar la salida por defecto, revisa el audio del sistema con pactl info y pactl list sources short en una terminal.
• Al volver a «Micrófono (sala)», FOSFENO devuelve la captura a la entrada por defecto. Si notas que sigue «escuchando» la música del equipo, pulsa «Aplicar entrada» de nuevo.

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.

Si la conectas con el sistema ya arrancado, pulsa «Buscar dispositivos» en el panel para que aparezca en la lista. Cuando la cámara falla, el panel lo dice con un aviso (y el motivo: no conectada, ocupada por otro programa...); para reintentar, apaga y enciende la casilla «Cámara». Si aun así no responde, pruébala en otro puerto USB o con otro cable.

Al salir del Mezclador la cámara se apaga (se le va el LED); se vuelve a encender sola al entrar de nuevo.

El Mezclador se queda en negro

Mira el aviso del panel, que dice exactamente qué falta:

• «La cámara está apagada»: activa la casilla «Cámara».
• «No hay vídeo elegido»: selecciona un clip en la lista.
• «No hay vídeos»: copia archivos a data/videos y pulsa el botón de actualizar la lista.
• «No se pudo cargar el vídeo»: el archivo está dañado o el códec no está soportado. Convierte el clip a .mp4 (H.264) o .webm y vuelve a elegirlo en la lista para reintentar.

En el modo «mezcla» hacen falta las dos fuentes (cámara y vídeo); si solo hay una, la otra mitad de la mezcla se ve negra.

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.

Si projectM se ve pero no reacciona a la música: projectM escucha siempre la entrada por defecto del sistema. Con la fuente «Audio del navegador» activa, FOSFENO mueve su captura al monitor de la salida al lanzarlo; si acabas de cambiar de salida o de fuente, pulsa «Aplicar entrada» en el panel.

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.