Skip to main content

CCTV Component

Overview​

The CCTV component is CROW's most advanced offering, representing Phase 3 of the rollout. It streams real-time CCTV footage from retail stores, analyzes it using Gemini Live, and generates insights about customer movements, behaviors, and product interactions in physical spaces.

Why CCTV is Phase 3​

The CCTV component requires significant infrastructure knowledge and setup:

  • Real-time video streaming architecture
  • WebRTC/WebSocket conversion
  • Gemini Live API integration
  • Background daemon development for CCTV servers
  • Privacy and compliance considerations
  • High bandwidth and processing requirements

It's deployed after Web and Social components to leverage the established core infrastructure and services.

Architecture​

Key Components​

Background Daemon​

A Linux service that runs on the CCTV server or a dedicated streaming device.

Responsibilities:

  • Capture video streams from multiple CCTV cameras
  • Combine streams into single high-resolution view (optional)
  • Stream via WebRTC to Cloudflare Realtime SFU
  • Manage connection reliability and reconnection
  • Start automatically on system boot
  • Handle hourly session boundaries

Technology:

  • Bash script for setup and installation
  • Background daemon process
  • Systemd service configuration
  • WebRTC client implementation

Installation:

# Provided during signup component configuration
curl -sSL https://setup.crow.example.com/cctv | bash -s YOUR_API_KEY

Stream Combination​

Multiple CCTV camera streams can be combined into a single high-resolution view:

Benefits:

  • AI can see all perspectives simultaneously
  • Better context for customer movement tracking
  • Reduced API calls to Gemini Live
  • More comprehensive spatial understanding
  • Easier pattern recognition across store areas

Implementation:

  • Real-time video composition
  • Configurable layout (grid, picture-in-picture, etc.)
  • Quality optimization for bandwidth

Cloudflare Realtime SFU​

Cloudflare's serverless Selective Forwarding Unit for WebRTC.

Why Cloudflare Realtime SFU:

  • Low-latency WebRTC streaming
  • Serverless architecture (no infrastructure management)
  • Global edge network for reliability
  • Native Cloudflare integration
  • Built-in scalability

Configuration:

  • WebRTC peer connection setup
  • ICE candidate handling
  • STUN/TURN servers managed by Cloudflare
  • Automatic reconnection on failure

WebRTC to WebSocket Adapter​

Cloudflare provides adapters to convert WebRTC streams to WebSocket connections.

Purpose:

  • Gemini Live API requires WebSocket input
  • Adapter bridges WebRTC (from cameras) to WebSocket (for Gemini)
  • Maintains real-time streaming characteristics
  • Handles protocol conversion efficiently

Gemini Live API​

Google's real-time multimodal AI API for video analysis.

Capabilities:

  • Real-time video understanding
  • Customer movement tracking
  • Product interaction detection
  • Behavior analysis
  • Contextual scene understanding

Integration:

  • WebSocket connection for streaming video
  • Real-time response stream
  • Contextual prompts for retail analysis
  • Organization and product context injection

Session Management​

Session Definition​

CCTV Session: 1 hour of continuous footage = one session.

After each hour, the current session is closed and sent to the Interaction Service for processing, and a new session begins.

Hourly Session Creation​

  1. Continuous Streaming: Daemon streams video continuously
  2. Hourly Boundary: Every hour, session marker is created
  3. Gemini Processing: Accumulated hour of analysis sent to queue
  4. New Session Start: Fresh session begins for next hour
  5. Queue Dispatch: Session data sent to Interaction Queue

Why Hourly Sessions?​

  • Manageable Data Size: 1 hour of video analysis is processable
  • Pattern Detection: Sufficient time window for behavior patterns
  • Resource Management: Prevents overwhelming processing pipeline
  • Billing Alignment: Clear billing boundaries for usage tracking

Data Flow​

Real-time Streaming Flow​

Processing Flow​

  1. Video Capture: Cameras record retail space
  2. Stream to Cloud: Daemon streams to Cloudflare
  3. Real-time Analysis: Gemini Live analyzes frames
  4. Accumulate Insights: Analysis accumulated over 1 hour
  5. Session Creation: After hour, insights compiled
  6. Queue Dispatch: Session sent to Interaction Queue
  7. Interaction Processing: Standard interaction pipeline
  8. Pattern Recognition: Patterns identified across sessions

Storage Strategy​

  • Real-time Only: Raw video is not stored; only insights are retained
  • Audit Frames: For debugging or replay, selective frames/clips can be stored in R2
  • Background Processing: Queues handle frame storage without impacting live analysis
  • Interaction Records: Final insights stored in D1 with embeddings in Vectorize

Configuration Setup​

During signup, users configuring the CCTV component receive:

1. Bash Script Command​

# Auto-generated with API key embedded
curl -sSL https://setup.crow.example.com/cctv | bash -s ORG_API_KEY_HERE

The script:

  • Installs daemon dependencies
  • Configures systemd service
  • Sets up WebRTC connection to Cloudflare
  • Embeds API key for authentication
  • Configures hourly session boundaries
  • Enables auto-start on boot

2. API Key Generation​

A unique API key is generated specifically for CCTV access:

  • Scoped to organization
  • Limited to CCTV data submission
  • Used by daemon for authentication
  • Revokable from dashboard

3. Setup Instructions​

  • Where to run the script (CCTV server or dedicated device)
  • Network requirements and firewall rules
  • Camera configuration and selection
  • Privacy compliance guidance
  • Testing and validation steps

Privacy and Compliance​

Privacy Considerations​

  • Selective Camera Streaming: Not all cameras need to be streamed
  • Privacy Zones: Areas can be masked or excluded
  • Data Retention: 24-hour retention policy for compliance
  • No PII Storage: Focus on behavior patterns, not identification
  • Opt-in Design: Cameras explicitly configured

Compliance Features​

  • GDPR Compliance: Data minimization and purpose limitation
  • Retail Privacy Laws: Adherence to retail surveillance regulations
  • Customer Notice: Store signage requirements
  • Data Access Controls: Strict access permissions
  • Audit Logging: All access logged

Security​

  • Encrypted Streaming: TLS 1.3 for all video transmission
  • API Key Authentication: Daemon authenticated to upload
  • Edge Processing: Analysis at edge, not centralized
  • Access Controls: Role-based dashboard access

Analytics and Insights​

Generated Insights​

The CCTV component generates rich insights about:

Customer Behavior:

  • Store navigation patterns
  • Product viewing time
  • Dwell time at displays
  • Group vs. individual shopping
  • Return visits to products

Product Interactions:

  • Products picked up
  • Products returned to shelf
  • Comparison shopping behavior
  • Product location effectiveness

Store Operations:

  • High-traffic areas
  • Bottleneck identification
  • Staff interaction patterns
  • Queue lengths and wait times

Patterns Over Time:

  • Peak hours and days
  • Seasonal behavior changes
  • Campaign effectiveness
  • Store layout optimization opportunities

Integration with Other Components​

CCTV insights are combined with Web and Social data:

  • Correlate in-store behavior with online research
  • Match physical purchases with web browsing
  • Identify social media influence on in-store visits
  • Complete customer journey mapping

Performance Characteristics​

Latency​

  • Streaming Latency: < 2 seconds camera to Gemini
  • Analysis Latency: Near real-time (< 5 seconds)
  • Session Processing: < 10 minutes after hourly boundary

Bandwidth​

  • Per Camera: 2-5 Mbps depending on quality
  • Combined Stream: Optimized for bandwidth efficiency
  • Upload Requirements: Stable broadband connection

Scalability​

  • Cameras per Store: 1-20+ cameras supported
  • Multiple Stores: Each store has independent daemon
  • Concurrent Processing: Cloudflare handles scaling

Troubleshooting​

Common Issues​

Connection Failures:

  • Verify network connectivity
  • Check firewall rules for WebRTC
  • Validate API key
  • Review daemon logs

Stream Quality:

  • Check camera resolution settings
  • Verify bandwidth availability
  • Adjust quality settings
  • Monitor network stability

Processing Delays:

  • Check Interaction Queue health
  • Verify Gemini Live API status
  • Review resource usage
  • Contact support if persistent

Future Enhancements​

Planned Features​

  • Multi-store Aggregation: Patterns across store locations
  • Real-time Alerts: Immediate notifications for events
  • Advanced Analytics: Heatmaps and journey visualization
  • Integration APIs: Third-party analytics tool integration
  • ML Model Training: Custom models for specific retail needs