RTSP Video Extractor System

A comprehensive, production-ready RTSP video extraction system built with Python and FFmpeg. Features continuous video buffering, incident-based clip extraction, automatic upload with offline retry, and a RESTful API for management.

Features

• Continuous Video Buffering: Maintains a rolling 2-hour buffer from RTSP cameras
• Automatic Reconnection: Handles camera disconnections with automatic retry
• Incident-Based Extraction: Extracts video clips (pre/post incident) from buffer
• Upload Management: Automatic upload to server with offline retry queue
• Web-Compatible Output: MP4 format optimized for web playback
• RESTful API: Complete API for camera and incident management
• SQLite Database: Persistent storage for cameras, incidents, and audit logs
• Thread Management: Independent threads for each component with health monitoring
• Audit Logging: Comprehensive logging to both files and database

Architecture

The system follows OOP principles with clear separation of concerns:

rtsp_extractor/
├── api/                    # REST API
│   └── flask_api.py
├── config/                 # Configuration
│   └── settings.py
├── database/               # Database layer
│   ├── interface.py        # Abstract interface
│   └── sqlite_repository.py # SQLite implementation
├── models/                 # Data models
│   └── data_models.py
├── services/               # Business logic services
│   ├── video_service_interface.py
│   └── ffmpeg_video_service.py
├── threads/                # Worker threads
│   ├── base_thread.py
│   ├── buffer_thread.py
│   ├── incident_processor_thread.py
│   ├── offline_uploader_thread.py
│   ├── cleanup_thread.py
│   └── thread_manager.py
├── utils/                  # Utilities
│   └── logger.py
└── main.py                 # Application entry point

Design Principles

1. Open/Closed Principle: Easy to extend without modifying existing code
2. Interface Segregation: Clear interfaces for database and video services
3. Single Responsibility: Each class has one clear purpose
4. Dependency Injection: Components receive dependencies rather than creating them
5. Separation of Concerns: Clear boundaries between API, business logic, and data

Thread Architecture

The system uses multiple specialized threads:

1. Buffer Thread (per camera): Continuously records video to buffer
2. Incident Processor Thread (per camera): Processes incidents and extracts clips
3. Offline Uploader Thread: Retries failed uploads
4. Cleanup Thread: Removes old segments and logs

Installation

1. Install system dependencies:

sudo apt-get update
sudo apt-get install -y ffmpeg

2. Install Python dependencies:

pip install -r requirements.txt

3. Run the application:

python main.py

Configuration

Edit config/settings.py to customize:

• Buffer duration (default: 2 hours)
• Pre/post incident seconds (default: 5 seconds each)
• API host and port
• Video codec and format
• Cleanup intervals
• Reconnection settings

API Documentation

Camera Management

Add Camera

POST /api/cameras
{
    "name": "Front Door",
    "rtsp_url": "rtsp://192.168.1.100:554/stream",
    "post_url": "https://server.com/upload",
    "enabled": true
}

Get All Cameras

GET /api/cameras

Get Camera

GET /api/cameras/{camera_id}

Delete Camera

DELETE /api/cameras/{camera_id}

Restart Camera

POST /api/cameras/{camera_id}/restart

Incident Management

Create Incident

POST /api/incidents
{
    "camera_id": 1,
    "incident_time": "2025-01-27T14:30:00"
}

Get Incidents

GET /api/incidents?camera_id=1&status=pending

System Management

Get Thread Status

GET /api/threads

Get Audit Logs

GET /api/logs?limit=100&source=Buffer-Camera-1

Start System

POST /api/system/start

Stop System

POST /api/system/stop

Health Check

GET /health

Usage Examples

1. Add a Camera

import requests

response = requests.post('http://localhost:5000/api/cameras', json={
    'name': 'Parking Lot',
    'rtsp_url': 'rtsp://admin:password@192.168.1.100:554/stream1',
    'post_url': 'https://myserver.com/api/videos',
    'enabled': True
})

camera_id = response.json()['id']
print(f"Camera added with ID: {camera_id}")

2. Create an Incident

from datetime import datetime
import requests

response = requests.post('http://localhost:5000/api/incidents', json={
    'camera_id': 1,
    'incident_time': datetime.now().isoformat()
})

print(f"Incident created: {response.json()}")

3. Monitor System

import requests

# Check thread status
threads = requests.get('http://localhost:5000/api/threads').json()
for thread in threads:
    print(f"{thread['name']}: {thread['status']}")

# Check logs
logs = requests.get('http://localhost:5000/api/logs?limit=10').json()
for log in logs:
    print(f"[{log['level']}] {log['source']}: {log['message']}")

How It Works

Buffer Management

1. Each camera has a dedicated buffer thread
2. FFmpeg continuously records to timestamped TS segments
3. Segments are automatically cleaned up after buffer duration
4. Buffer remains in memory-mapped filesystem for fast access

Incident Processing

1. User creates incident via API with timestamp
2. Incident processor extracts relevant segments from buffer
3. Segments are concatenated and re-encoded to MP4
4. Video is uploaded to configured post URL
5. If upload fails, incident moves to offline queue

Offline Queue

1. Offline uploader periodically checks for failed uploads
2. Retries uploads in order (oldest first)
3. Successfully uploaded files are deleted locally
4. Failed uploads remain in queue for next retry

Cleanup

1. Cleanup thread runs periodically
2. Removes buffer segments older than configured duration
3. Removes audit logs older than 30 days
4. Removes successfully uploaded videos

Video Format

Output videos are in MP4 format with:

• Video codec: H.264 (libx264)
• Audio codec: AAC
• Container: MP4 with faststart flag
• Optimized for web playback

Database Schema

cameras

• id, name, rtsp_url, status, post_url, enabled, created_at, updated_at

incidents

• id, camera_id, incident_time, video_path, upload_status, upload_attempts, error_message, created_at, uploaded_at

audit_logs

• id, level, source, message, details, created_at

Error Handling

• Automatic camera reconnection on failure
• Graceful handling of network issues
• Comprehensive error logging
• Upload retry mechanism
• Thread health monitoring

Production Deployment

1. Use systemd service for automatic startup
2. Configure firewall for API port
3. Set up HTTPS reverse proxy (nginx/Apache)
4. Monitor disk space for buffer storage
5. Regular database backups
6. Log rotation for application logs

Troubleshooting

Camera won't connect:

• Check RTSP URL and credentials
• Verify network connectivity
• Check FFmpeg logs in logs/Buffer-Camera-X.log

Videos not extracting:

• Ensure buffer has sufficient data
• Check incident timestamp is within buffer range
• Verify disk space availability

Upload failures:

• Check post_url is accessible
• Verify network connectivity
• Check offline queue in database

License

MIT License - Feel free to use and modify for your needs.

Support

For issues and questions, check the audit logs:

GET /api/logs

Or check the thread status:

GET /api/threads