Troubleshooting Cameras & RTSP Ingest
This guide provides diagnostic procedures and remediation steps when cameras fail to connect, disconnect unexpectedly, or produce corrupted video frames.
1. Camera in offline State
When a camera transitions to offline, inspect the last_error field via the REST API (GET /api/v1/cameras/{id}) or CLI (ruseon-cli cameras list):
bash
# Check camera status via CLI
ruseon-cli cameras status --id cam_entranceCommon Root Causes & Solutions:
| Error Message / Symptom | Root Cause | Remediation Steps |
|---|---|---|
401 Unauthorized | Invalid RTSP credentials | Verify camera username and password. Escape special characters (@, :, #) in RTSP URLs using URL encoding (e.g. %40). |
i/o timeout / connection refused | Network unreachable | Verify network routing, check if camera IP is reachable via ping <IP> and port 554 is open via nc -zv <IP> 554. |
RTSP DESCRIBE failed: 404 Stream Not Found | Wrong RTSP path | Check camera RTSP URL path syntax (e.g., /h264Preview_01_main for Reolink, /Streaming/Channels/101 for Hikvision, /cam/realmonitor?channel=1&subtype=0 for Dahua). |
max connections reached | Camera hardware client limit | Lower simultaneous connections on the camera; ensure RUSEON is the single consumer and restream to other clients. |
2. Testing RTSP Stream Connectivity with FFmpeg
Verify the stream independently using ffmpeg or ffprobe:
bash
# Probe stream video codec, resolution, and SPS/PPS metadata
ffprobe -rtsp_transport tcp -v verbose "rtsp://admin:password@192.168.1.50:554/live"
# Test 10 seconds of packet ingestion without decoding
ffmpeg -rtsp_transport tcp -i "rtsp://admin:password@192.168.1.50:554/live" -t 10 -f null -3. Unsupported Codec or Audio Format
RUSEON Core performs zero-transcoding transmuxing and natively accepts:
- Video:
H.264 (AVC)andH.265 (HEVC). - Audio:
AACandOpus(for WebRTC direct passthrough) andG.711 (PCMU/PCMA).
If the camera is configured for MJPEG or MPEG-4, the RTSP ingest engine will reject the video track.
- Solution: Open the camera's web admin UI (Video/Encoding settings) and select H.264 or H.265.
4. Frequent Reconnections & Green Smearing / Gray Screen Artifacts
Green artifact blocks or smearing indicate lost P-frames over unstable transport:
- Switch Transport to TCP: Set
transport: "tcp"in the camera configuration to eliminate UDP packet loss. - Adjust GOP (KeyFrame Interval): In the camera web settings, set the I-Frame interval (GOP) to match the frame rate (e.g., 25 fps = GOP 25 or 50, meaning 1-2 seconds per keyframe). Avoid GOP intervals longer than 4 seconds.