This page is generated. It is published automatically from doc/wiki/rtsp-troubleshooting.md in the BirdNET-Go repository. Do not edit it here; changes are overwritten on the next sync. To propose a change, open a pull request against the source file.

This guide covers common RTSP streaming issues and their solutions in BirdNET-Go, including advanced configuration options for problematic cameras.

• Common RTSP Issues
• Health Monitoring Configuration
• Advanced FFmpeg Parameters
• Camera-Specific Issues
• Troubleshooting Steps
• Configuration Examples

Symptoms:

• Stream starts normally and receives data
• After camera reboot, stream shows "unhealthy" but never recovers
• Restart count shows as 0 in logs despite multiple restart attempts
• FFmpeg process doesn't exit immediately when camera reboots

Root Cause: Some cameras don't properly close TCP connections during reboots, leaving "half-open" TCP sessions. FFmpeg continues waiting on these dead connections instead of detecting the failure immediately.

Solution: Use custom FFmpeg parameters to add connection timeouts and failure detection strategies.

Symptoms:

• Frequent stream restarts
• Circuit breaker opens after consecutive failures
• Streams get throttled or stopped completely

Root Cause: Network issues, authentication problems, or incompatible camera settings causing repeated failures.

Solution: Check network connectivity, verify RTSP credentials, and adjust health monitoring thresholds.

BirdNET-Go includes configurable health monitoring for RTSP streams:

realtime:
  rtsp:
    health:
      healthydatathreshold: 60 # seconds before stream considered unhealthy
      monitoringinterval: 30 # health check interval in seconds

• healthydatathreshold: How long (in seconds) without receiving data before a stream is considered unhealthy (default: 60)
• monitoringinterval: How often (in seconds) to check stream health (default: 30)

For unstable networks or slow cameras:

realtime:
  rtsp:
    health:
      healthydatathreshold: 120 # Allow 2 minutes without data
      monitoringinterval: 60 # Check every minute

For fast networks requiring quick recovery:

realtime:
  rtsp:
    health:
      healthydatathreshold: 30 # Only allow 30 seconds without data
      monitoringinterval: 15 # Check every 15 seconds

The ffmpegparameters setting allows you to add custom FFmpeg command-line arguments for problematic cameras.

Important: FFmpeg parameter names and defaults have changed across versions:

• FFmpeg 5.0+: Uses -timeout for socket timeouts (current)
• FFmpeg 4.x and earlier: Used -stimeout for socket timeouts (deprecated)

Check your FFmpeg version:

ffmpeg -version

If using an older version, you may need to use -stimeout instead of -timeout.

All parameters in this guide have been tested with:

• FFmpeg version: 5.1.6-0+deb12u1
• Test stream: Live RTSP camera stream
• Verification method: Direct FFmpeg command testing

Parameters marked as ✅ Verified have been tested and confirmed working. Parameters marked as ❌ Not Available have been tested and confirmed not supported for RTSP.

realtime:
  rtsp:
    ffmpegparameters:
      - "-parameter1"
      - "value1"
      - "-parameter2"
      - "value2"

realtime:
  rtsp:
    ffmpegparameters:
      - "-timeout"
      - "5000000" # 5 second socket timeout (in microseconds)
      - "-buffer_size"
      - "65536" # 64KB buffer size for better data handling

Important Notes:

• FFmpeg 5.0+ uses -timeout instead of the older -stimeout option
• Parameter placement is crucial: The -timeout parameter must be placed before the RTSP URL in the command line for proper functionality
• Default timeout values:
  • -timeout: 0 (no timeout, infinite wait)
  • -listen_timeout: -1 (infinite timeout)
• Units are microseconds (1 second = 1,000,000 microseconds)
• Timeout functionality verified: When a timeout occurs, FFmpeg will exit with "Connection timed out" error

Example:

ffmpeg -rtsp_transport tcp -timeout 5000000 -i rtsp://usser:password@192.168.1.100/stream -vn -f s16le -ar 48000 -ac 1 -f null -

Common timeout values:

• 1 second = 1,000,000 microseconds
• 5 seconds = 5,000,000 microseconds
• 10 seconds = 10,000,000 microseconds

realtime:
  rtsp:
    ffmpegparameters:
      - "-rtsp_flags"
      - "prefer_tcp" # Force TCP transport (helpful for firewall issues)
      - "-listen_timeout"
      - "10" # Connection timeout in seconds (default: -1, infinite)

Note: Reconnection parameters (-reconnect, -reconnect_at_eof, etc.) are not available for RTSP - they only work with HTTP/HTTPS protocols.

realtime:
  rtsp:
    ffmpegparameters:
      - "-probesize"
      - "1000000" # 1MB probe size for faster detection (default: 5000000)
      - "-analyzeduration"
      - "1000000" # 1 second analysis duration (default: 5000000)
      - "-reorder_queue_size"
      - "1000" # Packet reorder buffer size (default: -1, auto)

Note: TCP-specific parameters like -tcp_nodelay are not available for RTSP.

realtime:
  rtsp:
    ffmpegparameters:
      - "-timeout"
      - "5000000" # 5 second socket timeout
      - "-buffer_size"
      - "65536" # 64KB buffer size
      - "-rtsp_flags"
      - "prefer_tcp" # Force TCP transport
      - "-probesize"
      - "2000000" # 2MB probe size for faster detection
      - "-analyzeduration"
      - "2000000" # 2 second analysis duration

Generally work well with default settings. If issues occur, try:

realtime:
  rtsp:
    ffmpegparameters:
      - "-rtsp_flags"
      - "prefer_tcp"

May require authentication parameters:

realtime:
  rtsp:
    ffmpegparameters:
      - "-rtsp_flags"
      - "prefer_tcp"
      - "-timeout"
      - "5000000" # 5 second timeout

Often benefit from increased timeouts:

realtime:
  rtsp:
    ffmpegparameters:
      - "-timeout"
      - "15000000" # 15 second timeout
      - "-buffer_size"
      - "131072" # 128KB buffer size for better handling

For cameras that don't properly close connections:

realtime:
  rtsp:
    ffmpegparameters:
      - "-timeout"
      - "5000000" # 5 second socket timeout
      - "-buffer_size"
      - "65536" # 64KB buffer size
      - "-rtsp_flags"
      - "prefer_tcp" # Force TCP transport
      - "-listen_timeout"
      - "10" # 10 second connection timeout

# Test RTSP stream with FFmpeg directly
ffmpeg -rtsp_transport tcp -i rtsp://camera-ip:554/stream -t 10 -f null -

Look for these patterns in logs:

• unhealthy stream detected - Stream health monitoring triggered
• restart_count - Should increment with each restart attempt
• circuit breaker opened - Too many consecutive failures

• Ensure RTSP is enabled on camera
• Check authentication credentials
• Verify stream URL format
• Confirm camera is accessible on network

realtime:
  rtsp:
    transport: tcp # Try: tcp, udp, udp_multicast, http

Check FFmpeg errors by temporarily changing log level:

realtime:
  rtsp:
    ffmpegparameters:
      - "-loglevel"
      - "warning" # Change from "error" to see more details

realtime:
  rtsp:
    urls:
      - "rtsp://admin:password@192.168.1.100:554/stream1"
      - "rtsp://admin:password@192.168.1.101:554/stream1"
    transport: tcp
    health:
      healthydatathreshold: 90 # Allow 90 seconds without data
      monitoringinterval: 30 # Check every 30 seconds
    ffmpegparameters:
      - "-timeout"
      - "5000000" # 5 second socket timeout
      - "-buffer_size"
      - "65536" # 64KB buffer size
      - "-rtsp_flags"
      - "prefer_tcp" # Force TCP transport
      - "-listen_timeout"
      - "15" # 15 second connection timeout
      - "-probesize"
      - "2000000" # 2MB probe size
      - "-analyzeduration"
      - "2000000" # 2 second analysis duration

realtime:
  rtsp:
    urls:
      - "rtsp://admin:password@192.168.1.100:554/stream1"
    transport: tcp
    health:
      healthydatathreshold: 60
      monitoringinterval: 30
    # No custom FFmpeg parameters needed for stable cameras

realtime:
  rtsp:
    urls:
      - "rtsp://admin:password@192.168.1.100:554/stream1"
    transport: tcp
    health:
      healthydatathreshold: 30 # Quick failure detection
      monitoringinterval: 15 # Frequent health checks
    ffmpegparameters:
      - "-timeout"
      - "3000000" # 3 second timeout for quick failure detection
      - "-probesize"
      - "1000000" # Fast stream detection (1MB)
      - "-analyzeduration"
      - "1000000" # Quick analysis (1 second)
      - "-buffer_size"
      - "32768" # 32KB buffer for lower latency

• Camera reboots don't properly close TCP connections
• Network has high latency or packet loss
• Streams frequently disconnect and don't recover
• You need faster failure detection
• Camera has specific RTSP implementation quirks

• Default settings work fine
• You're unsure about the impact
• Camera manufacturer provides specific recommendations
• Network is stable and reliable

If you're still experiencing issues:

1. Check the GitHub Issues: Search for similar problems in the BirdNET-Go GitHub repository

2. Enable Debug Logging: Add -loglevel warning to see detailed FFmpeg output

3. Test with FFmpeg Directly: Verify the stream works outside of BirdNET-Go

4. Provide Logs: Include relevant log entries when reporting issues

5. Camera Information: Specify camera make/model and firmware version

Remember: Start with conservative settings and gradually adjust based on your specific camera and network conditions.