MODEL/usda-vision
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(video-streaming): add ApiStatusIndicator, PerformanceDashboard, VideoDebugger, and VideoErrorBoundary components

Browse Source 
- Implemented ApiStatusIndicator to monitor video API connection status with health check functionality.
- Created PerformanceDashboard for monitoring video streaming performance metrics in development mode.
- Developed VideoDebugger for diagnosing video streaming issues with direct access to test video URLs.
- Added VideoErrorBoundary to handle errors in video streaming components with user-friendly messages and recovery options.
- Introduced utility functions for performance monitoring and thumbnail caching to optimize video streaming operations.
- Added comprehensive tests for video streaming API connectivity and functionality.
This commit is contained in:
Alireza Vaezi
2025-08-06 11:46:25 -04:00
parent 228efb0f55
commit 81828f61cf
38 changed files with 3117 additions and 441 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
API Documentations/docs/API_DOCUMENTATION.md
View File

@@ -13,18 +13,16 @@ This document provides comprehensive documentation for all API endpoints in the
- [💾 Storage & File Management](#-storage--file-management)
- [🔄 Camera Recovery & Diagnostics](#-camera-recovery--diagnostics)
- [📺 Live Streaming](#-live-streaming)
- [🎬 Video Streaming & Playback](#-video-streaming--playback)
- [🌐 WebSocket Real-time Updates](#-websocket-real-time-updates)
## 🔧 System Status & Health
### Get System Status
```http
GET /system/status
```
**Response**: `SystemStatusResponse`
```json
{
"system_started": true,
@@ -52,13 +50,10 @@ GET /system/status
```
### Health Check
```http
GET /health
```
**Response**: Simple health status
```json
{
"status": "healthy",
@@ -69,21 +64,16 @@ GET /health
## 📷 Camera Management
### Get All Cameras
```http
GET /cameras
```
**Response**: `Dict[str, CameraStatusResponse]`
### Get Specific Camera Status
```http
GET /cameras/{camera_name}/status
```
**Response**: `CameraStatusResponse`
```json
{
"name": "camera1",
@@ -108,13 +98,12 @@ GET /cameras/{camera_name}/status
## 🎥 Recording Control
### Start Recording
```http
POST /cameras/{camera_name}/start-recording
Content-Type: application/json
{
"filename": "test_recording.mp4",
"filename": "test_recording.avi",
"exposure_ms": 2.0,
"gain": 4.0,
"fps": 5.0
@@ -122,36 +111,30 @@ Content-Type: application/json
```
**Request Model**: `StartRecordingRequest`
- `filename` (optional): Custom filename (datetime prefix will be added automatically)
- `exposure_ms` (optional): Exposure time in milliseconds
- `gain` (optional): Camera gain value
- `fps` (optional): Target frames per second
**Response**: `StartRecordingResponse`
```json
{
"success": true,
"message": "Recording started for camera1",
"filename": "20240115_103000_test_recording.mp4"
"filename": "20240115_103000_test_recording.avi"
}
```
**Key Features**:
- ✅ **Automatic datetime prefix**: All filenames get `YYYYMMDD_HHMMSS_` prefix
- ✅ **Dynamic camera settings**: Adjust exposure, gain, and FPS per recording
- ✅ **Backward compatibility**: All existing API calls work unchanged
### Stop Recording
```http
POST /cameras/{camera_name}/stop-recording
```
**Response**: `StopRecordingResponse`
```json
{
"success": true,
@@ -163,13 +146,10 @@ POST /cameras/{camera_name}/stop-recording
## 🤖 Auto-Recording Management
### Enable Auto-Recording for Camera
```http
POST /cameras/{camera_name}/auto-recording/enable
```
**Response**: `AutoRecordingConfigResponse`
```json
{
"success": true,
@@ -180,21 +160,16 @@ POST /cameras/{camera_name}/auto-recording/enable
```
### Disable Auto-Recording for Camera
```http
POST /cameras/{camera_name}/auto-recording/disable
```
**Response**: `AutoRecordingConfigResponse`
### Get Auto-Recording Status
```http
GET /auto-recording/status
```
**Response**: `AutoRecordingStatusResponse`
```json
{
"running": true,
@@ -205,7 +180,6 @@ GET /auto-recording/status
```
**Auto-Recording Features**:
- 🤖 **MQTT-triggered recording**: Automatically starts/stops based on machine state
- 🔄 **Retry logic**: Failed recordings are retried with configurable delays
- 📊 **Per-camera control**: Enable/disable auto-recording individually
@@ -214,13 +188,10 @@ GET /auto-recording/status
## 🎛️ Camera Configuration
### Get Camera Configuration
```http
GET /cameras/{camera_name}/config
```
**Response**: `CameraConfigResponse`
```json
{
"name": "camera1",
@@ -255,7 +226,6 @@ GET /cameras/{camera_name}/config
```
### Update Camera Configuration
```http
PUT /cameras/{camera_name}/config
Content-Type: application/json
@@ -269,13 +239,11 @@ Content-Type: application/json
```
### Apply Configuration (Restart Required)
```http
POST /cameras/{camera_name}/apply-config
```
**Configuration Categories**:
- ✅ **Real-time**: `exposure_ms`, `gain`, `target_fps`, `sharpness`, `contrast`, etc.
- ⚠️ **Restart required**: `noise_filter_enabled`, `denoise_3d_enabled`, `bit_depth`, `video_format`, `video_codec`, `video_quality`
@@ -284,21 +252,16 @@ For detailed configuration options, see [Camera Configuration API Guide](api/CAM
## 📡 MQTT & Machine Status
### Get All Machines
```http
GET /machines
```
**Response**: `Dict[str, MachineStatusResponse]`
### Get MQTT Status
```http
GET /mqtt/status
```
**Response**: `MQTTStatusResponse`
```json
{
"connected": true,
@@ -313,13 +276,10 @@ GET /mqtt/status
```
### Get MQTT Events History
```http
GET /mqtt/events?limit=10
```
**Response**: `MQTTEventsHistoryResponse`
```json
{
"events": [
@@ -340,13 +300,10 @@ GET /mqtt/events?limit=10
## 💾 Storage & File Management
### Get Storage Statistics
```http
GET /storage/stats
```
**Response**: `StorageStatsResponse`
```json
{
"base_path": "/storage",
@@ -372,7 +329,6 @@ GET /storage/stats
```
### Get File List
```http
POST /storage/files
Content-Type: application/json
@@ -384,9 +340,7 @@ Content-Type: application/json
"limit": 50
}
```
**Response**: `FileListResponse`
```json
{
"files": [
@@ -403,7 +357,6 @@ Content-Type: application/json
```
### Cleanup Old Files
```http
POST /storage/cleanup
Content-Type: application/json
@@ -412,9 +365,7 @@ Content-Type: application/json
"max_age_days": 30
}
```
**Response**: `CleanupResponse`
```json
{
"files_removed": 25,
@@ -426,55 +377,42 @@ Content-Type: application/json
## 🔄 Camera Recovery & Diagnostics
### Test Camera Connection
```http
POST /cameras/{camera_name}/test-connection
```
**Response**: `CameraTestResponse`
### Reconnect Camera
```http
POST /cameras/{camera_name}/reconnect
```
**Response**: `CameraRecoveryResponse`
### Restart Camera Grab Process
```http
POST /cameras/{camera_name}/restart-grab
```
**Response**: `CameraRecoveryResponse`
### Reset Camera Timestamp
```http
POST /cameras/{camera_name}/reset-timestamp
```
**Response**: `CameraRecoveryResponse`
### Full Camera Reset
```http
POST /cameras/{camera_name}/full-reset
```
**Response**: `CameraRecoveryResponse`
### Reinitialize Camera
```http
POST /cameras/{camera_name}/reinitialize
```
**Response**: `CameraRecoveryResponse`
**Recovery Response Example**:
```json
{
"success": true,
@@ -488,39 +426,176 @@ POST /cameras/{camera_name}/reinitialize
## 📺 Live Streaming
### Get Live MJPEG Stream
```http
GET /cameras/{camera_name}/stream
```
**Response**: MJPEG video stream (multipart/x-mixed-replace)
### Start Camera Stream
```http
POST /cameras/{camera_name}/start-stream
```
### Stop Camera Stream
```http
POST /cameras/{camera_name}/stop-stream
```
**Streaming Features**:
- 📺 **MJPEG format**: Compatible with web browsers and React apps
- 🔄 **Concurrent operation**: Stream while recording simultaneously
- ⚡ **Low latency**: Real-time preview for monitoring
For detailed streaming integration, see [Streaming Guide](guides/STREAMING_GUIDE.md).
## 🎬 Video Streaming & Playback
The system includes a comprehensive video streaming module that provides YouTube-like video playback capabilities with HTTP range request support, thumbnail generation, and intelligent caching.
### List Videos
```http
GET /videos/
```
**Query Parameters:**
- `camera_name` (optional): Filter by camera name
- `start_date` (optional): Filter videos created after this date (ISO format)
- `end_date` (optional): Filter videos created before this date (ISO format)
- `limit` (optional): Maximum number of results (default: 50, max: 1000)
- `include_metadata` (optional): Include video metadata (default: false)
**Response**: `VideoListResponse`
```json
{
"videos": [
{
"file_id": "camera1_auto_blower_separator_20250804_143022.mp4",
"camera_name": "camera1",
"filename": "camera1_auto_blower_separator_20250804_143022.mp4",
"file_size_bytes": 31457280,
"format": "mp4",
"status": "completed",
"created_at": "2025-08-04T14:30:22",
"start_time": "2025-08-04T14:30:22",
"end_time": "2025-08-04T14:32:22",
"machine_trigger": "blower_separator",
"is_streamable": true,
"needs_conversion": false,
"metadata": {
"duration_seconds": 120.5,
"width": 1920,
"height": 1080,
"fps": 30.0,
"codec": "mp4v",
"bitrate": 5000000,
"aspect_ratio": 1.777
}
}
],
"total_count": 1
}
```
### Get Video Information
```http
GET /videos/{file_id}
```
**Response**: `VideoInfoResponse` with detailed video information including metadata.
### Stream Video
```http
GET /videos/{file_id}/stream
```
**Headers:**
- `Range: bytes=0-1023` (optional): Request specific byte range for seeking
**Features:**
- ✅ **HTTP Range Requests**: Enables video seeking and progressive download
- ✅ **Partial Content**: Returns 206 status for range requests
- ✅ **Format Conversion**: Automatic AVI to MP4 conversion for web compatibility
- ✅ **Intelligent Caching**: Optimized performance with byte-range caching
- ✅ **CORS Enabled**: Ready for web browser integration
**Response Headers:**
- `Accept-Ranges: bytes`
- `Content-Length: {size}`
- `Content-Range: bytes {start}-{end}/{total}` (for range requests)
- `Cache-Control: public, max-age=3600`
### Get Video Thumbnail
```http
GET /videos/{file_id}/thumbnail?timestamp=5.0&width=320&height=240
```
**Query Parameters:**
- `timestamp` (optional): Time position in seconds (default: 1.0)
- `width` (optional): Thumbnail width in pixels (default: 320)
- `height` (optional): Thumbnail height in pixels (default: 240)
**Response**: JPEG image data with caching headers
### Get Streaming Information
```http
GET /videos/{file_id}/info
```
**Response**: `StreamingInfoResponse`
```json
{
"file_id": "camera1_recording_20250804_143022.avi",
"file_size_bytes": 52428800,
"content_type": "video/mp4",
"supports_range_requests": true,
"chunk_size_bytes": 262144
}
```
### Video Validation
```http
POST /videos/{file_id}/validate
```
**Response**: Validation status and accessibility check
```json
{
"file_id": "camera1_recording_20250804_143022.avi",
"is_valid": true
}
```
### Cache Management
```http
POST /videos/{file_id}/cache/invalidate
```
**Response**: Cache invalidation status
```json
{
"file_id": "camera1_recording_20250804_143022.avi",
"cache_invalidated": true
}
```
### Admin: Cache Cleanup
```http
POST /admin/videos/cache/cleanup?max_size_mb=100
```
**Response**: Cache cleanup results
```json
{
"cache_cleaned": true,
"entries_removed": 15,
"max_size_mb": 100
}
```
**Video Streaming Features**:
- 🎥 **Multiple Formats**: Native MP4 support with AVI conversion
- 📱 **Web Compatible**: Direct integration with HTML5 video elements
- ⚡ **High Performance**: Intelligent caching and adaptive chunking
- 🖼️ **Thumbnail Generation**: Extract preview images at any timestamp
- 🔄 **Range Requests**: Efficient seeking and progressive download
## 🌐 WebSocket Real-time Updates
### Connect to WebSocket
```javascript
const ws = new WebSocket('ws://vision:8000/ws');
const ws = new WebSocket('ws://localhost:8000/ws');
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
@@ -529,7 +604,6 @@ ws.onmessage = (event) => {
```
**WebSocket Message Types**:
- `system_status`: System status changes
- `camera_status`: Camera status updates
- `recording_started`: Recording start events
@@ -538,7 +612,6 @@ ws.onmessage = (event) => {
- `auto_recording_event`: Auto-recording status changes
**Example WebSocket Message**:
```json
{
"type": "recording_started",
@@ -554,28 +627,26 @@ ws.onmessage = (event) => {
## 🚀 Quick Start Examples
### Basic System Monitoring
```bash
# Check system health
curl http://vision:8000/health
curl http://localhost:8000/health
# Get overall system status
curl http://vision:8000/system/status
curl http://localhost:8000/system/status
# Get all camera statuses
curl http://vision:8000/cameras
curl http://localhost:8000/cameras
```
### Manual Recording Control
```bash
# Start recording with default settings
curl -X POST http://vision:8000/cameras/camera1/start-recording \
curl -X POST http://localhost:8000/cameras/camera1/start-recording \
-H "Content-Type: application/json" \
-d '{"filename": "manual_test.avi"}'
# Start recording with custom camera settings
curl -X POST http://vision:8000/cameras/camera1/start-recording \
curl -X POST http://localhost:8000/cameras/camera1/start-recording \
-H "Content-Type: application/json" \
-d '{
"filename": "high_quality.avi",
@@ -585,30 +656,57 @@ curl -X POST http://vision:8000/cameras/camera1/start-recording \
}'
# Stop recording
curl -X POST http://vision:8000/cameras/camera1/stop-recording
curl -X POST http://localhost:8000/cameras/camera1/stop-recording
```
### Auto-Recording Management
```bash
# Enable auto-recording for camera1
curl -X POST http://vision:8000/cameras/camera1/auto-recording/enable
curl -X POST http://localhost:8000/cameras/camera1/auto-recording/enable
# Check auto-recording status
curl http://vision:8000/auto-recording/status
curl http://localhost:8000/auto-recording/status
# Disable auto-recording for camera1
curl -X POST http://vision:8000/cameras/camera1/auto-recording/disable
curl -X POST http://localhost:8000/cameras/camera1/auto-recording/disable
```
### Video Streaming Operations
```bash
# List all videos
curl http://localhost:8000/videos/
# List videos from specific camera with metadata
curl "http://localhost:8000/videos/?camera_name=camera1&include_metadata=true"
# Get video information
curl http://localhost:8000/videos/camera1_recording_20250804_143022.avi
# Get video thumbnail
curl "http://localhost:8000/videos/camera1_recording_20250804_143022.avi/thumbnail?timestamp=5.0&width=320&height=240" \
--output thumbnail.jpg
# Get streaming info
curl http://localhost:8000/videos/camera1_recording_20250804_143022.avi/info
# Stream video with range request
curl -H "Range: bytes=0-1023" \
http://localhost:8000/videos/camera1_recording_20250804_143022.avi/stream
# Validate video file
curl -X POST http://localhost:8000/videos/camera1_recording_20250804_143022.avi/validate
# Clean up video cache (admin)
curl -X POST "http://localhost:8000/admin/videos/cache/cleanup?max_size_mb=100"
```
### Camera Configuration
```bash
# Get current camera configuration
curl http://vision:8000/cameras/camera1/config
curl http://localhost:8000/cameras/camera1/config
# Update camera settings (real-time)
curl -X PUT http://vision:8000/cameras/camera1/config \
curl -X PUT http://localhost:8000/cameras/camera1/config \
-H "Content-Type: application/json" \
-d '{
"exposure_ms": 1.5,
@@ -623,47 +721,47 @@ curl -X PUT http://vision:8000/cameras/camera1/config \
### ✨ New in Latest Version
#### 1. Enhanced Recording API
- **Dynamic camera settings**: Set exposure, gain, and FPS per recording
- **Automatic datetime prefixes**: All filenames get timestamp prefixes
- **Backward compatibility**: Existing API calls work unchanged
#### 2. Auto-Recording Feature
- **Per-camera control**: Enable/disable auto-recording individually
- **MQTT integration**: Automatic recording based on machine states
- **Retry logic**: Failed recordings are automatically retried
- **Status tracking**: Monitor auto-recording attempts and failures
#### 3. Advanced Camera Configuration
- **Real-time settings**: Update exposure, gain, image quality without restart
- **Image enhancement**: Sharpness, contrast, saturation, gamma controls
- **Noise reduction**: Configurable noise filtering and 3D denoising
- **HDR support**: High Dynamic Range imaging capabilities
#### 4. Live Streaming
- **MJPEG streaming**: Real-time camera preview
- **Concurrent operation**: Stream while recording simultaneously
- **Web-compatible**: Direct integration with React/HTML video elements
#### 5. Enhanced Monitoring
- **MQTT event history**: Track machine state changes over time
- **Storage statistics**: Monitor disk usage and file counts
- **WebSocket updates**: Real-time system status notifications
#### 6. Video Streaming Module
- **HTTP Range Requests**: Efficient video seeking and progressive download
- **Thumbnail Generation**: Extract preview images from videos at any timestamp
- **Format Conversion**: Automatic AVI to MP4 conversion for web compatibility
- **Intelligent Caching**: Byte-range caching for optimal streaming performance
- **Admin Tools**: Cache management and video validation endpoints
### 🔄 Migration Notes
#### From Previous Versions
1. **Recording API**: All existing calls work, but now return filenames with datetime prefixes
2. **Configuration**: New camera settings are optional and backward compatible
3. **Auto-recording**: New feature, requires enabling in `config.json` and per camera
#### Configuration Updates
```json
{
"cameras": [
@@ -689,34 +787,38 @@ curl -X PUT http://vision:8000/cameras/camera1/config \
- [📷 Camera Configuration API Guide](api/CAMERA_CONFIG_API.md) - Detailed camera settings
- [🤖 Auto-Recording Feature Guide](features/AUTO_RECORDING_FEATURE_GUIDE.md) - React integration
- [📺 Streaming Guide](guides/STREAMING_GUIDE.md) - Live video streaming
- [🎬 Video Streaming Guide](VIDEO_STREAMING.md) - Video playback and streaming
- [🤖 AI Agent Video Integration Guide](AI_AGENT_VIDEO_INTEGRATION_GUIDE.md) - Complete integration guide for AI agents
- [🔧 Camera Recovery Guide](guides/CAMERA_RECOVERY_GUIDE.md) - Troubleshooting
- [📡 MQTT Logging Guide](guides/MQTT_LOGGING_GUIDE.md) - MQTT configuration
## 📞 Support & Integration
### API Base URL
- **Development**: `http://vision:8000`
- **Development**: `http://localhost:8000`
- **Production**: Configure in `config.json` under `system.api_host` and `system.api_port`
### Error Handling
All endpoints return standard HTTP status codes:
- `200`: Success
- `404`: Resource not found (camera, file, etc.)
- `206`: Partial Content (for video range requests)
- `400`: Bad Request (invalid parameters)
- `404`: Resource not found (camera, file, video, etc.)
- `416`: Range Not Satisfiable (invalid video range request)
- `500`: Internal server error
- `503`: Service unavailable (camera manager, MQTT, etc.)
### Rate Limiting
**Video Streaming Specific Errors:**
- `404`: Video file not found or not streamable
- `416`: Invalid range request (malformed Range header)
- `500`: Failed to read video data or generate thumbnail
### Rate Limiting
- No rate limiting currently implemented
- WebSocket connections are limited to reasonable concurrent connections
### CORS Support
- CORS is enabled for web dashboard integration
- Configure allowed origins in the API server settings
```
```