Health

Monitor Screenpipe system health and pipeline metrics

Health Check

The health endpoint provides comprehensive system status information, including pipeline metrics for vision and audio processing.

Endpoint

GET /health

Example

curl "http://localhost:3030/health"

Response

status · string

Overall health status: "healthy" or "degraded"

status_code · integer

HTTP status code: 200 for healthy, 503 for degraded

last_frame_timestamp · string

Timestamp of the most recent frame captured

last_audio_timestamp · string

Timestamp of the most recent audio chunk

frame_status · string

Status of frame capture pipeline

Values:

• "ok" - Working normally
• "stale" - No recent frames (may indicate issue)
• "not_started" - Pipeline not yet started
• "disabled" - Frame capture disabled in settings

audio_status · string

Status of audio recording pipeline

Values: Same as frame_status

message · string

Human-readable status message

verbose_instructions · string

Detailed troubleshooting instructions if there are issues

device_status_details · string

Specific device status information

monitors · array

List of detected monitors/displays

pipeline · object

Detailed vision pipeline metrics

Show Vision Pipeline Metrics

uptime_secs · number

Pipeline uptime in seconds

frames_captured · integer

Total frames captured since start

frames_db_written · integer

Frames successfully written to database

frames_dropped · integer

Number of frames dropped due to performance issues

frame_drop_rate · number

Percentage of frames dropped (0.0 to 1.0)

capture_fps_actual · number

Actual frames per second being captured

avg_ocr_latency_ms · number

Average OCR processing time in milliseconds

avg_db_latency_ms · number

Average database write time in milliseconds

ocr_queue_depth · integer

Number of frames waiting for OCR processing

video_queue_depth · integer

Number of frames waiting to be encoded

time_to_first_frame_ms · number

Time taken to capture first frame after startup

pipeline_stall_count · integer

Number of times the pipeline stalled

ocr_cache_hit_rate · number

OCR cache hit rate (0.0 to 1.0)

audio_pipeline · object

Detailed audio pipeline metrics

Show Audio Pipeline Metrics

uptime_secs · number

Pipeline uptime in seconds

chunks_sent · integer

Audio chunks sent for processing

chunks_channel_full · integer

Times the processing channel was full

stream_timeouts · integer

Number of stream timeout events

vad_passed · integer

Chunks with detected speech (Voice Activity Detection)

vad_rejected · integer

Chunks without speech

vad_passthrough_rate · number

Percentage passing VAD (0.0 to 1.0)

avg_speech_ratio · number

Average speech ratio in audio chunks

transcriptions_completed · integer

Successful transcriptions

transcriptions_empty · integer

Empty transcription results

transcription_errors · integer

Failed transcription attempts

db_inserted · integer

Transcriptions written to database

total_words · integer

Total words transcribed

words_per_minute · number

Average transcription rate

transcription_mode · string

Current transcription mode

transcription_paused · boolean

Whether transcription is paused

segments_deferred · integer

Number of deferred segments

segments_batch_processed · integer

Number of batch processed segments

batch_paused_reason · string

Reason for batch processing pause

Example Response

Healthy System

{
  "status": "healthy",
  "status_code": 200,
  "last_frame_timestamp": "2024-03-08T14:30:00Z",
  "last_audio_timestamp": "2024-03-08T14:30:05Z",
  "frame_status": "ok",
  "audio_status": "ok",
  "message": "All systems operational",
  "monitors": ["Built-in Display", "External Monitor"],
  "pipeline": {
    "uptime_secs": 3600.5,
    "frames_captured": 21600,
    "frames_db_written": 21595,
    "frames_dropped": 5,
    "frame_drop_rate": 0.0002,
    "capture_fps_actual": 6.0,
    "avg_ocr_latency_ms": 45.3,
    "avg_db_latency_ms": 12.1,
    "ocr_queue_depth": 2,
    "video_queue_depth": 1,
    "time_to_first_frame_ms": 1250.5,
    "pipeline_stall_count": 0,
    "ocr_cache_hit_rate": 0.85
  },
  "audio_pipeline": {
    "uptime_secs": 3600.5,
    "chunks_sent": 1500,
    "chunks_channel_full": 2,
    "stream_timeouts": 0,
    "vad_passed": 450,
    "vad_rejected": 1050,
    "vad_passthrough_rate": 0.3,
    "avg_speech_ratio": 0.65,
    "transcriptions_completed": 420,
    "transcriptions_empty": 30,
    "transcription_errors": 5,
    "db_inserted": 415,
    "total_words": 12500,
    "words_per_minute": 208.33,
    "transcription_mode": "streaming",
    "transcription_paused": false
  }
}

Degraded System

{
  "status": "degraded",
  "status_code": 503,
  "last_frame_timestamp": "2024-03-08T14:15:00Z",
  "last_audio_timestamp": "2024-03-08T14:30:00Z",
  "frame_status": "stale",
  "audio_status": "ok",
  "message": "Frame capture pipeline is stale",
  "verbose_instructions": "No frames captured in the last 15 minutes. Check:\n1. Screen recording permissions\n2. Monitor connection\n3. System resources (CPU/Memory)\n4. Application logs",
  "device_status_details": "Monitor 'Built-in Display' may be disconnected",
  "monitors": [],
  "pipeline": {
    "uptime_secs": 3600.5,
    "frames_captured": 15000,
    "frames_dropped": 500,
    "frame_drop_rate": 0.032,
    "pipeline_stall_count": 15
  }
}

Health Status Interpretation

Healthy

• status: "healthy"
• Both frame and audio pipelines operating normally
• Recent timestamps (within expected intervals)
• Low frame drop rate (< 1%)
• No pipeline stalls

Degraded

• status: "degraded"
• One or more pipelines experiencing issues
• Stale timestamps
• High frame drop rate (> 5%)
• Pipeline stalls or errors
• Permission issues

Monitoring Best Practices

Regular Health Checks:

• Poll /health every 30-60 seconds for monitoring
• Alert on status: "degraded"
• Track frame_drop_rate over time
• Monitor queue depths for bottlenecks
• Check transcription error rates
• Verify timestamps are recent

Key Metrics to Monitor

1. Frame Drop Rate - Should be < 1%

   • High rates indicate performance issues
   • Check CPU/GPU usage
   • Reduce capture FPS if needed

2. OCR Latency - Should be < 100ms

   • High latency causes queue buildup
   • Consider faster OCR engine
   • Enable OCR caching

3. Queue Depths - Should be < 10

   • High depths indicate processing bottleneck
   • May need to scale processing power

4. Transcription Errors - Should be < 2%

   • High rates indicate audio quality issues
   • Check microphone configuration
   • Reduce background noise

5. VAD Passthrough Rate - Typically 20-40%

   • Very low may indicate audio issues
   • Very high may indicate noise

Troubleshooting

Stale Frame Status

# Check health
curl "http://localhost:3030/health"

# Check vision status
curl "http://localhost:3030/vision/status"

# List monitors
curl "http://localhost:3030/vision/list"

Common causes:

• Screen recording permission denied
• No monitors detected
• Pipeline crashed
• System resources exhausted

High Frame Drop Rate

# Get detailed metrics
curl "http://localhost:3030/vision/metrics"

Solutions:

• Reduce capture FPS in settings
• Close resource-intensive applications
• Enable OCR caching
• Upgrade hardware

Audio Pipeline Issues

# Check audio health
curl "http://localhost:3030/audio/metrics"

# List audio devices
curl "http://localhost:3030/audio/list"

Common causes:

• Microphone permission denied
• Audio device disconnected
• High transcription error rate
• VAD sensitivity too high/low

Integration Example

TypeScript Monitoring

interface HealthResponse {
  status: 'healthy' | 'degraded';
  frame_status: string;
  audio_status: string;
  pipeline?: {
    frame_drop_rate: number;
    ocr_queue_depth: number;
  };
  audio_pipeline?: {
    transcription_errors: number;
    vad_passthrough_rate: number;
  };
}

async function checkHealth(): Promise<void> {
  const response = await fetch('http://localhost:3030/health');
  const health: HealthResponse = await response.json();
  
  if (health.status === 'degraded') {
    console.error('Screenpipe is degraded:', health);
    // Send alert
  }
  
  // Check specific metrics
  if (health.pipeline?.frame_drop_rate > 0.05) {
    console.warn('High frame drop rate:', health.pipeline.frame_drop_rate);
  }
  
  if (health.audio_pipeline?.transcription_errors > 10) {
    console.warn('High transcription errors:', health.audio_pipeline.transcription_errors);
  }
  
  // Log metrics for monitoring
  logMetrics({
    frame_drop_rate: health.pipeline?.frame_drop_rate,
    ocr_queue: health.pipeline?.ocr_queue_depth,
    transcription_errors: health.audio_pipeline?.transcription_errors,
  });
}

// Poll every minute
setInterval(checkHealth, 60000);

Bash Monitoring Script

#!/bin/bash

while true; do
  health=$(curl -s "http://localhost:3030/health")
  status=$(echo $health | jq -r '.status')
  
  if [ "$status" != "healthy" ]; then
    echo "[$(date)] ALERT: Screenpipe is $status"
    echo $health | jq '.'
    
    # Send notification
    osascript -e 'display notification "Screenpipe is degraded" with title "Health Alert"'
  fi
  
  sleep 60
done

WebSocket Health Monitoring

For real-time health monitoring, use the WebSocket endpoint:

ws://localhost:3030/ws/health

Receives health updates pushed by the server in real-time.

const ws = new WebSocket('ws://localhost:3030/ws/health');

ws.onmessage = (event) => {
  const health = JSON.parse(event.data);
  console.log('Health update:', health);
  
  if (health.status === 'degraded') {
    showAlert(health.message);
  }
};

Next Steps

• Query your data with the search endpoint
• Manage audio devices if audio_status is not ok
• Check vision metrics in the health response for frame_status details
• Configure pipes for automated monitoring alerts