🎥 Video streaming via API

🎥 Video streaming via API

🎯 Purpose

Enables hardware devices to capture and stream video from beehive entrances to the cloud for remote monitoring and AI analysis.

🎭 User Story

  • As a beekeeper with custom hardware or limited compute resources
  • I want to stream video from my beehive entrance to the cloud
  • So that I can leverage cloud-based AI analysis and remote monitoring without requiring powerful on-device processing

🚀 Key Benefits

  • Hardware flexibility: Works with Raspberry Pi, custom PCs, or Jetson Nano devices
  • Cloud processing: Offloads AI analysis to cloud infrastructure for devices without GPU
  • Remote access: View live and historical video streams from anywhere
  • Easy integration: Simple API token authentication and setup

🔧 Technical Overview

Video upload system (src/uploader.py) captures processed video chunks with detection overlays and uploads them to video.gratheon.com via GraphQL mutations. Uses multipart/form-data encoding with both video files and detection metadata, supporting batch uploads with bearer token authentication.

📋 Acceptance Criteria

  • Supports USB camera video capture with OpenCV (CAP_V4L2/CAP_AVFOUNDATION)
  • Encodes video with AVC1/MP4V codecs for compatibility
  • Uploads video chunks with detection overlays via GraphQL API
  • Includes detection metadata file alongside video upload
  • Uses bearer token authentication (API_TOKEN environment variable)
  • Supports configurable video chunk length (VIDEO_CHUNK_LENGTH_SEC)
  • Handles network interruptions with threaded async uploads

🚫 Out of Scope

  • Real-time live streaming (batch upload of processed chunks)
  • Audio streaming (video only)
  • Real-time two-way communication
  • Storage management beyond standard retention policies

🏗️ Implementation Approach

  • Video Encoding: OpenCV VideoWriter with AVC1/MP4V codecs
  • Upload Protocol: GraphQL mutation via HTTPS POST with multipart/form-data
  • Authentication: Bearer token in Authorization header
  • Threading: Async upload processing to prevent blocking video capture
  • Integration: Links to SECTION_ID (box ID) and timestamp metadata
  • Error Handling: Graceful fallback when API credentials not configured

📊 Success Metrics

  • Video encoding with proper codec compatibility (AVC1 primary, MP4V fallback)
  • Successful GraphQL mutation uploads to video.gratheon.com endpoint
  • Threaded async processing without blocking main video pipeline
  • Proper multipart encoding with detection metadata files
  • Bearer token authentication and box ID association

🔗 Related Features

📚 Resources & References

💬 Notes

Actual implementation using GraphQL mutations for video upload with detection metadata. Enables cloud-based processing for devices without sufficient local compute resources.