Solución de problemas y configuración de cámaras en Frigate

Configurar un sistema de videovigilancia con Frigate permite detectar personas, vehículos y otros objetos sin enviar las grabaciones a la nube. Sin embargo, durante la instalación es bastante habitual encontrarse con una cámara que no muestra imagen, un directo que se corta o mensajes indicando que FFmpeg no puede recibir fotogramas.

Estos fallos no suelen estar relacionados con la inteligencia artificial. En la mayoría de los casos, el origen está en una URL RTSP incorrecta, unas credenciales no válidas, un stream incompatible, un problema de red o un error dentro de la configuración de Frigate. La forma más rápida de solucionarlo es comprobar cada parte por separado: primero la cámara, después el stream, luego Frigate y, finalmente, servicios adicionales como go2rtc, MQTT o Home Assistant.

Comprueba primero la conexión de la cámara

Antes de modificar el archivo de configuración, comprueba que la cámara funciona de manera independiente. Frigate necesita acceder a un stream compatible, normalmente mediante RTSP, aunque algunos modelos utilizan otros formatos como HTTP-FLV.

Entra en la aplicación o en el panel de administración de la cámara y comprueba que el acceso local, RTSP u ONVIF esté activado. Algunos fabricantes también exigen crear una cuenta específica para aplicaciones externas, diferente de la utilizada para acceder a sus servicios en la nube.

También es recomendable asignar una IP fija a la cámara desde el router. Si su dirección cambia después de un reinicio, Frigate seguirá intentando conectarse a la IP anterior y el vídeo dejará de funcionar.

La dirección del stream suele tener una estructura parecida a esta:

rtsp://usuario:contraseñ[email protected]:554/ruta_del_stream

La ruta exacta depende del fabricante y del modelo. Para saber si es correcta, abre la URL desde VLC o ffplay. Si tampoco funciona en estos reproductores, todavía no merece la pena tocar Frigate: tendrás que revisar la IP, el puerto, las credenciales y la ruta proporcionada por la cámara.

Si la contraseña contiene caracteres como @, #, : o /, estos pueden romper la URL. En ese caso, utiliza variables de entorno compatibles con Frigate o codifica correctamente los caracteres especiales.

Añade la cámara desde el asistente de Frigate

En las versiones actuales, la forma recomendada de incorporar una cámara es utilizar el asistente incluido en la interfaz. Entra en Settings > Global configuration > Camera management y selecciona Add Camera.

El asistente permite introducir la IP y las credenciales, buscar perfiles mediante ONVIF o escribir manualmente la URL RTSP. Después prueba cada stream, muestra una captura y permite asignar sus funciones:

• detect: stream utilizado para detectar movimiento y objetos.
• record: stream cuyos segmentos se guardarán como grabaciones.
• audio: stream empleado para la detección de sonidos.

Lo habitual es usar el substream de menor resolución para detect y el stream principal para record. Así, Frigate analiza una imagen más ligera, pero conserva las grabaciones con la calidad original.

El asistente también detecta problemas habituales, como una resolución excesiva para la detección, la ausencia de un stream con el rol detect o un códec de audio incompatible.

Revisa la configuración YAML y los roles de cada stream

También puedes configurar las cámaras manualmente mediante YAML. Este formato utiliza la indentación para representar la estructura, por lo que no debes emplear tabuladores ni mezclar diferentes cantidades de espacios.

Una configuración básica con dos streams podría tener este aspecto:

mqtt:
  enabled: false

record:
  enabled: true
  continuous:
    days: 3

cameras:
  entrada:
    ffmpeg:
      inputs:
        - path: rtsp://usuario:{FRIGATE_RTSP_PASSWORD}@192.168.1.50:554/substream
          roles:
            - detect
        - path: rtsp://usuario:{FRIGATE_RTSP_PASSWORD}@192.168.1.50:554/mainstream
          roles:
            - record
    detect:
      width: 1280
      height: 720
      fps: 5

Las rutas son solo ejemplos y deben sustituirse por las correspondientes a tu cámara. La contraseña puede almacenarse en una variable cuyo nombre empiece por FRIGATE_, evitando dejarla expuesta directamente en el archivo.

En lugar de recurrir únicamente a un validador YAML genérico, utiliza el editor de configuración de Frigate. Un validador externo puede detectar errores de indentación, pero no sabe si una clave concreta existe o es compatible con la versión instalada.

Qué hacer si aparece el error de que no hay frames

Mensajes como “Unable to read frames from ffmpeg process” o “No frames have been received” indican que el proceso encargado de capturar el vídeo no está entregando imágenes a Frigate.

Abre los registros desde la sección de sistema y localiza las líneas correspondientes a la cámara afectada. Las causas más habituales son:

• La dirección IP de la cámara ha cambiado.
• El usuario o la contraseña son incorrectos.
• La ruta RTSP pertenece a otro modelo de cámara.
• El firmware limita el número de conexiones simultáneas.
• La cámara pierde cobertura WiFi o reinicia el stream.
• Se ha configurado una aceleración de vídeo incompatible.
• El códec o los parámetros emitidos por la cámara no son válidos.

Si utilizas go2rtc, revisa también el estado de los streams desde /api/go2rtc/streams. Esto permite comprobar si go2rtc logra conectarse a la cámara y qué códecs está recibiendo.

Cuando una cámara ofrece varios protocolos de transporte, probar RTSP sobre TCP puede mejorar la estabilidad en redes donde se pierden paquetes. No obstante, una conexión Ethernet sigue siendo preferible al WiFi para cámaras que transmiten vídeo continuamente.

El vídeo funciona, pero Frigate no guarda grabaciones

Que la imagen aparezca en directo no significa que las grabaciones estén correctamente configuradas. Para conservar vídeo deben cumplirse tres condiciones: existir un stream con el rol record, estar activada la grabación y haberse definido una política de retención.

La antigua clave retain_days no debe utilizarse en configuraciones actuales. Para guardar todo el vídeo durante tres días, la estructura correcta es:

record:
  enabled: true
  continuous:
    days: 3

Si prefieres reducir el uso del disco y conservar únicamente los periodos donde hubo movimiento, puedes utilizar:

record:
  enabled: true
  motion:
    days: 3
  alerts:
    retain:
      days: 10
      mode: motion
  detections:
    retain:
      days: 10
      mode: motion

Las grabaciones se almacenan dentro de /media/frigate/recordings. Comprueba que el volumen esté montado en la ubicación correcta, tenga permisos de escritura y disponga de espacio suficiente. Un montaje fallido puede provocar que Frigate escriba accidentalmente en el disco del sistema y lo llene rápidamente.

También debes considerar el códec. Las grabaciones H.265 no funcionan en todos los navegadores, mientras que H.264 ofrece una compatibilidad mucho mayor. Si los archivos existen, pero no se reproducen desde la interfaz, el problema puede estar en el navegador y no en la cámara.

Integración con Home Assistant y MQTT

Para integrar Frigate con Home Assistant necesitas instalar la integración de Frigate y configurar previamente la integración MQTT. Además, ambos sistemas deben conectarse al mismo broker MQTT para que funcionen correctamente muchas de las entidades, sensores y contadores.

Una configuración básica sería:

mqtt:
  enabled: true
  host: 192.168.1.20
  user: frigate
  password: "{FRIGATE_MQTT_PASSWORD}"

Al añadir la integración en Home Assistant también debes indicar la URL interna de Frigate. Puede utilizarse el puerto 5000, que no incorpora autenticación, o el 8971, que ofrece acceso autenticado. El puerto 5000 solo debería exponerse dentro de una red de confianza.

Para el vídeo en directo conviene distinguir dos puertos:

• 8554: restream RTSP proporcionado por go2rtc.
• 8555 TCP y UDP: conexiones WebRTC.

El restream puede abrirse con una dirección como rtsp://IP_DEL_SERVIDOR:8554/nombre_stream. Si Home Assistant está en otra red, en una VLAN diferente o detrás de determinados proxies, WebRTC puede necesitar que se configure como candidato la dirección real del servidor Frigate que resulte accesible desde el dispositivo cliente.

Un proxy inverso HTTP como Traefik puede servir para acceder a la interfaz web, pero no sustituye la exposición de los puertos utilizados directamente por RTSP o WebRTC.

Reduce el consumo de CPU correctamente

Frigate realiza varias tareas diferentes y cada una puede utilizar un componente distinto. La decodificación de vídeo corresponde a FFmpeg y puede acelerarse con una GPU integrada o dedicada. La detección de objetos, en cambio, utiliza un detector como Coral, Hailo, OpenVINO, ONNX o TensorRT.

Un Coral USB puede reducir enormemente el trabajo necesario para ejecutar el modelo de detección, pero no acelera por sí mismo la decodificación de los streams. Para eso debes configurar un preset de hwaccel_args compatible con el hardware del servidor.

Por ejemplo, muchos equipos Intel y AMD compatibles pueden utilizar:

ffmpeg:
  hwaccel_args: preset-vaapi

No debes copiar este valor sin comprobar la compatibilidad del equipo. Una configuración incorrecta puede hacer que FFmpeg se cierre continuamente, ya que no siempre existe una sustitución automática por software cuando falla la aceleración seleccionada.

Además, evita interpretar las cifras de CPU de Frigate como si representaran todo el procesador. En sus estadísticas, un proceso al 100 % suele significar que está utilizando por completo un único núcleo. Para conocer el consumo total, compara los datos con docker stats o con el monitor del sistema anfitrión.

Para reducir la carga sin perjudicar las grabaciones:

• Utiliza un substream para detect.
• Configura normalmente la detección a unos 5 FPS.
• Reserva el stream de alta resolución para record.
• Activa la decodificación por hardware compatible.
• Utiliza un detector adecuado en lugar del detector de CPU de prueba.
• Evita abrir varias conexiones innecesarias contra la misma cámara.

Lista de comprobación si una cámara sigue sin funcionar

1. Comprueba que la cámara responde en su dirección IP.
2. Verifica la URL exacta mediante VLC o ffplay.
3. Confirma que RTSP u ONVIF están activados en la cámara.
4. Revisa el usuario, la contraseña, el puerto y los caracteres especiales.
5. Prueba el stream desde el asistente para añadir cámaras de Frigate.
6. Comprueba los roles detect y record.
7. Consulta los registros de FFmpeg y de captura.
8. Desactiva temporalmente hwaccel_args si FFmpeg se reinicia.
9. Revisa los streams de go2rtc y los nombres utilizados en el restream.
10. Comprueba el espacio, el montaje y los permisos de /media/frigate.
11. Verifica que Frigate y Home Assistant utilizan el mismo broker MQTT.
12. Expón correctamente los puertos 8554 y 8555 si necesitas RTSP o WebRTC.

Seguir este orden evita cambiar varias opciones a la vez y permite localizar con precisión dónde se interrumpe el flujo. Si la cámara funciona en VLC, el stream aparece correctamente en go2rtc y FFmpeg no muestra errores, el problema suele encontrarse en los roles, la retención de grabaciones o la integración utilizada para mostrar el vídeo.

Una configuración estable depende de separar correctamente cada función: un stream ligero para analizar imágenes, otro de mayor calidad para grabar, aceleración específica para la decodificación y un detector adecuado para la inteligencia artificial. Con esta estructura, Frigate puede funcionar durante largos periodos sin cortes ni un consumo desproporcionado de recursos.