Ring Doorbell Recorder

Project Overview

The Ring Doorbell Recorder is an open-source application I developed to capture and manage events from Ring Doorbell and camera devices. It automatically records and organizes doorbell events with a focus on reliable data capture and video storage.

As most projects go it's about scratching one's own itch. I wanted more control over how my Ring doorbell data was stored and accessed. The official Ring app provides cloud storage, but for a literal $price. I wanted a solution that would give me agency over my doorbell data.

Key Features

• Event-driven architecture using the Observer pattern to respond to doorbell events
• Multiple storage backends (Database & File) for flexible data storage
• Automatic video capture for doorbell rings, motion events, and on-demand viewing
• Token-based authentication with 2FA support for secure access
• Structured event data validation using Pydantic
• Comprehensive logging for system monitoring

The WebRTC Challenge

One of the most interesting learnings came from implementing the WebRTC connection to Ring's cameras. WebRTC (Web Real-Time Communication) is typically used for browser-based video conferencing, but here I had to implement it in Python to connect directly to Ring's proprietary API.

The WebRTC connection flow involves several complex steps:

1. Authentication and Preparation

   • Obtaining the Ring account ID
   • Generating a signalsocket ticket from Ring's API
   • Determining the correct WebSocket URL based on region

2. WebRTC Offer Generation

   • Creating an RTCPeerConnection with STUN servers
   • Adding a receive-only video transceiver
   • Generating an SDP offer and setting it as local description
   • Gathering ICE candidates for NAT traversal

3. Signaling via WebSocket

   • Connecting to Ring's WebSocket server
   • Sending the SDP offer in a "live_view" message
   • Processing incoming messages including SDP answers and ICE candidates

4. Session Maintenance

   • Sending regular "ping" keepalive messages every 5 seconds
   • Monitoring connection state changes
   • Processing incoming frames and forwarding to a video sink
   • Auto-stopping after a maximum duration to prevent battery drain

WebRTC Protocol Insights

I'd never thought I'd work on a real-world WebRTC project. Interesting learnings include:

Message Format and Protocol

Ring uses a specific message format for its WebRTC signaling - and its fucking picky about everything. If you don't format thing just right, it will not work.:

json
Copy
{
  "method": "live_view",
  "dialog_id": "uuid-v4-string",
  "riid": "random-hex-string",
  "body": {
    "doorbot_id": 123456789,
    "sdp": "v=0...",
    "stream_options": {
      "audio_enabled": false,
      "video_enabled": true,
      "ptz_enabled": false
    }
  }
}

Correctly implementing this format was crucial for successful connections.

NAT Traversal with ICE

TIL what STUN was. To establish peer-to-peer connections through firewalls and NAT devices, the implementation uses Google's public STUN servers:

• stun:stun.l.google.com:19302
• stun:stun1.l.google.com:19302
• stun:stun2.l.google.com:19302

I still haven't fully dove into ICE (Interactive Connectivity Establishment) and how it works, but I know it involves gathering candidates and establishing a connection between peers.

Connection Monitoring and Recovery

The system includes connection monitoring:

• Tracking ICE connection state changes
• Implementing recovery strategies for failed connections
• Using timeout guards to prevent resource leaks
• Maintaining WebSocket connections with keepalive messages

Architecture and Design

The application follows a clean, modular architecture with well-defined components:

Future Directions

Honestly, the project will evolve as I need it to. Possible things could be....

• Support for audio capture alongside video
• Enhanced event filtering and processing
• Custom push notification support
• Mobile app for viewing stored videos
• Making it more extensible for other devs as a package.

Technical Stack

• Python 3.11+ for core application logic
• aiortc for WebRTC implementation
• SQLAlchemy for database ORM
• aiohttp for async HTTP client
• asyncio for asynchronous programming
• Pydantic for data validation

Open Source Collaboration

This project builds upon and was inspired by several excellent open-source libraries:

• python-ring-doorbell for core Ring API functionality
• ring-client-api for insights into WebRTC streaming implementation
• go2rtc for reference on Ring API's WebRTC implementation

The code is available on GitHub under the MIT License. Contributions and feedback are always welcome!