🎥 RTSP Stream Analyzer

Professional RTSP stream validation tool with visual snapshots and comprehensive metrics

A modern web application for analyzing RTSP camera streams to ensure optimal quality for AI applications, video surveillance, and real-time monitoring. Features accurate frame counting with OpenCV, bitrate measurement, visual snapshots, and professional report generation.

---

Features

🎯 Core Features

• 🎥 Real-time Stream Analysis - Accurate frame counting with OpenCV and FFmpeg
• 📸 Visual Snapshots - Capture and display frames from your RTSP stream
• 📊 Comprehensive Metrics - FPS, bitrate, resolution, codec, frame loss, and jitter
• 🚨 Health Monitoring - Color-coded pass/fail indicators for critical metrics
• 📄 Report Export - Professional reports in Text and JSON formats
• ⚡ Background Processing - Non-blocking analysis with real-time updates
• 🎬 Live Video Preview - Watch streams in browser via WebRTC (MediaMTX, 10-min TTL)
• 🔍 RTSP URL Helper - Built-in database of 11+ camera vendors with auto-generated URLs
• 🎯 Anavid Shoplifting Cloud Validation - Instant verification of DVR settings for cloud AI
• 📡 Bandwidth Calculator - Multi-camera capacity planning with speedtest integration
• 🔌 Network Diagnostics - Pre-flight connection testing without authentication (prevents IP bans)
• ⏱️ Auto-Cleanup - MediaMTX streams auto-expire after 10 minutes

💎 Technical Highlights

• 🎨 Modern UI - Beautiful, responsive dashboard with TailwindCSS
• 🐳 Docker Ready - Multi-stage build for production deployment
• 🔧 Accurate Measurements - OpenCV for frame counting, FFmpeg for bitrate
• 📱 Mobile Friendly - Responsive design works on all devices
• 🌐 Open Source - MIT licensed, contributions welcome!

Requirements for AI Detection

The analyzer checks for these critical requirements:

• Minimum FPS: 15 frames per second
• Minimum Bitrate: 500 kbps
• Frame Loss: Less than 5%
• Codec: H.264, H.265, or HEVC recommended

Quick Start (Local Development)

Prerequisites

• Python 3.11+
• Node.js 20+
• FFmpeg and FFprobe installed

Install FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ffmpeg

Windows: Download from ffmpeg.org

Backend Setup

cd backend
pip install -r requirements.txt
python main.py

The backend will start on http://localhost:8000

Frontend Setup

cd frontend
npm install
npm run dev

The frontend will start on http://localhost:3000

Docker Deployment

Build and Run Locally

docker build -t rtsp-analyzer .
docker run -p 8000:8000 rtsp-analyzer

Or use Docker Compose:

docker-compose up -d

Deploy to Easypanel

1. Push to GitHub:

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin <your-repo-url>
   git push -u origin main

2. In Easypanel:

   • Create a new app
   • Connect your GitHub repository
   • Set build method to "Dockerfile"
   • Set port to 8000
   • Deploy!

Usage

🔍 RTSP URL Helper (New!)

Don't know your camera's RTSP URL format? Use the built-in helper:

1. Click "RTSP URL Helper" at the top
2. Select your camera vendor (Hikvision, Dahua, Axis, etc.)
3. Choose stream type (Sub-stream auto-selected for Anavid)
4. Fill in IP, credentials, channel
5. Click "Use This URL" - auto-fills the form!

Features:

• 11+ camera vendors supported
• Auto-detect public IP with one click
• Anavid Shoplifting Cloud requirements shown for sub-streams
• Local vs remote testing guidance

📊 Stream Analysis

1. Enter RTSP Stream URL (or use the helper above)

   rtsp://admin:password@192.168.1.100:554/Streaming/Channels/202
   

2. Set Analysis Duration (default: 30 seconds)

   • Longer duration = more accurate frame loss detection
   • Recommended: 30-60 seconds

3. View Results

   • Stream health status (Healthy/Warning/Critical)
   • Anavid Shoplifting Cloud validation badge - instant pass/fail
   • Video codec and resolution
   • FPS and bitrate measurements
   • Frame loss percentage
   • Visual snapshot of the stream
   • "Watch Live" button (if MediaMTX is configured)
   • Bandwidth check for multiple cameras
   • Detailed warnings for any issues

4. Export Reports

   • Click the text icon for a human-readable report
   • Click the download icon for JSON format

🎯 Anavid Shoplifting Cloud Integration

For cloud AI shoplifting detection, the analyzer validates:

• ✅ Sub-stream selected
• ✅ FPS ≥ 15
• ✅ Bitrate ≥ 1 Mbps (CBR)
• ✅ Resolution = 704x480

Testing workflow: Use your camera's public IP address to test. The analyzer runs from our remote server to simulate Anavid's cloud connectivity - exactly how Anavid will access your cameras in production.

The validation badge shows instant pass/fail for each requirement!

🔌 Network Diagnostics (Test Connection)

Prevent IP bans! Test network connectivity WITHOUT attempting RTSP authentication.

Click "Test Connection" before analysis to check:

1. Ping - Is the host reachable?
2. Port Scan - Is RTSP port 554 open?
3. Connection Test - Can we establish TCP connection?
4. Traceroute - What's the network path?

Benefits:

• ✅ No authentication attempts
• ✅ No risk of IP ban from failed logins
• ✅ Diagnose network issues before analysis
• ✅ Clear pass/fail for each test
• ✅ Includes nmap, ping, traceroute, netcat

Perfect for: Testing cameras with unknown credentials, diagnosing firewall issues, checking if DVR blocked your IP.

🎬 Live Video Preview (Optional)

Want to watch your RTSP streams live in the browser? Set up MediaMTX integration!

See MEDIAMTX_SETUP.md for complete setup instructions.

When configured, a purple "Watch Live" button appears on completed analyses, allowing you to view the stream via WebRTC directly in your browser - no plugins required!

Auto-cleanup: Streams automatically expire after 10 minutes to prevent resource buildup.

API Endpoints

POST /api/analyze

Start analyzing a stream

{
  "url": "rtsp://...",
  "duration": 30
}

GET /api/streams

List all analyzed streams

GET /api/stream/{stream_id}

Get detailed metrics for a specific stream

DELETE /api/stream/{stream_id}

Remove a stream from the list

POST /api/diagnose

Network diagnostics without authentication

{
  "url": "rtsp://admin:password@192.168.1.100:554/stream"
}

Returns: Ping, port scan, connection test, traceroute results

GET /health

Health check endpoint

Architecture

┌─────────────┐
│   Frontend  │  React + TailwindCSS + Vite
│  (Port 3000)│  Real-time polling for updates
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Backend   │  FastAPI + Python
│  (Port 8000)│  Background task processing
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   FFmpeg    │  Stream analysis
│   FFprobe   │  Metadata extraction
└─────────────┘

Metrics Explained

FPS (Frames Per Second)

• Measures how many frames the stream delivers per second
• Requirement: Minimum 15 FPS for AI detection
• Lower FPS = missed events

Bitrate

• Measures data transfer rate
• Requirement: Minimum 500 kbps
• Lower bitrate = reduced image quality

Frame Loss

• Percentage of expected frames that were not received
• Requirement: Less than 5% loss
• High frame loss = unreliable stream

Codec

• Video compression format
• Recommended: H.264, H.265, HEVC
• Affects compatibility and quality

Troubleshooting

"Analysis timeout - stream may be unreachable"

• Check if the RTSP URL is correct
• Verify network connectivity
• Ensure camera is online and accessible
• Check firewall rules

Low FPS Warning

• Camera may be configured for low frame rate
• Network bandwidth issues
• Camera processing limitations

High Frame Loss

• Network congestion
• Unstable connection
• Camera hardware issues
• RTSP server overload

FFmpeg Not Found (Docker)

• FFmpeg is included in the Docker image
• For local development, ensure FFmpeg is installed

Environment Variables

• PORT - Server port (default: 8000)
• VITE_API_URL - Frontend API URL (default: /api)

Development

Project Structure

rtsp_station/
├── backend/
│   ├── main.py              # FastAPI application
│   └── requirements.txt     # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── App.jsx         # Main React component
│   │   ├── main.jsx        # React entry point
│   │   └── index.css       # TailwindCSS styles
│   ├── package.json        # Node dependencies
│   └── vite.config.js      # Vite configuration
├── Dockerfile              # Production build
├── docker-compose.yml      # Local Docker setup
└── README.md              # This file

Adding New Metrics

1. Update analyze_stream_ffprobe() or analyze_stream_detailed() in backend/main.py
2. Add metric extraction logic
3. Update StreamMetrics model
4. Display in StreamCard component in frontend/src/App.jsx

🤝 Contributing

Contributions are welcome! This project is open source and built for the RTSP community.

Ways to Contribute

• 🐛 Report Bugs - Open an issue with details
• 💡 Suggest Features - Share your ideas
• 📝 Improve Documentation - Help others understand
• 🔧 Submit Pull Requests - Code contributions welcome
• ⭐ Star the Project - Show your support!

Development Setup

git clone https://github.com/magnusfroste/rtsp-stream-analyzer.git
cd rtsp-stream-analyzer
./setup.sh
./start-local.sh

🌟 Use Cases

• AI/ML Applications - Validate streams for computer vision
• Video Surveillance - Ensure camera quality
• IoT Monitoring - Check device stream health
• Pre-deployment Testing - Validate before installation
• Network Diagnostics - Identify streaming issues
• Quality Assurance - Continuous stream monitoring

📊 Tech Stack

• Backend: Python 3.11, FastAPI, OpenCV, FFmpeg
• Frontend: React 18, Vite, TailwindCSS, Axios
• Deployment: Docker, Multi-stage builds
• Analysis: OpenCV (frame counting), FFmpeg (bitrate)

🙏 Acknowledgments

Built with ❤️ for the RTSP and video streaming community.

Special thanks to:

• Anavid.ai - For the use case and inspiration
• OpenCV - For accurate frame analysis
• FFmpeg - For reliable stream processing
• FastAPI - For the excellent Python framework
• React - For the modern UI framework

📄 License

MIT License - see LICENSE file for details

👤 Author

Magnus Froste (@magnusfroste)

• Built for RTSP enthusiasts and video professionals
• Open source contributions welcome
• Available for consulting and custom development

🔗 Links

• GitHub: magnusfroste/rtsp-stream-analyzer
• Issues: Report a bug or request a feature
• Discussions: Join the conversation

---

⭐ If you find this useful, please star the repository!

Made with ❤️ by @magnusfroste | Powered by Anavid.ai