Skip to main content

WebSocket API

Real-time face identification through WebSocket connection.

Endpoint​

ws://localhost:8000/ws/identify

Connection​

JavaScript Example​

const ws = new WebSocket('ws://localhost:8000/ws/identify');

ws.onopen = () => {
  console.log('WebSocket connected');
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  console.log('Identification result:', result);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket disconnected');
};

Message Format​

Client → Server​

Send base64-encoded image frames:

{
  "type": "frame",
  "data": "base64-encoded-image-data"
}

Server → Client​

Receive identification results:

{
  "type": "identification",
  "timestamp": "2025-12-04T10:30:00Z",
  "face_detected": true,
  "match": {
    "person_id": "uuid-here",
    "name": "John Doe",
    "relationship": "Friend",
    "confidence": 0.87
  }
}

No match response:

{
  "type": "identification",
  "timestamp": "2025-12-04T10:30:00Z",
  "face_detected": true,
  "match": null
}

No face detected:

{
  "type": "identification",
  "timestamp": "2025-12-04T10:30:00Z",
  "face_detected": false,
  "match": null
}

Complete Example​

Sending Webcam Frames​

const video = document.querySelector('video');
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
const ws = new WebSocket('ws://localhost:8000/ws/identify');

// Capture and send frames at 2 FPS
const captureInterval = setInterval(() => {
  if (ws.readyState !== WebSocket.OPEN) return;

  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  ctx.drawImage(video, 0, 0);

  const imageData = canvas.toDataURL('image/jpeg', 0.8);
  const base64Data = imageData.split(',')[1];

  ws.send(JSON.stringify({
    type: 'frame',
    data: base64Data
  }));
}, 500); // 2 FPS

// Handle results
ws.onmessage = (event) => {
  const result = JSON.parse(event.data);

  if (result.match) {
    console.log(`Identified: ${result.match.name} (${result.match.confidence})`);
  } else if (result.face_detected) {
    console.log('Face detected but no match');
  }
};

// Cleanup
ws.onclose = () => {
  clearInterval(captureInterval);
};

Connection Lifecycle​

  1. Connect: Client initiates WebSocket connection
  2. Stream: Client sends video frames as base64 strings
  3. Process: Server detects faces and generates embeddings
  4. Match: Server compares against memory bank
  5. Respond: Server sends identification results
  6. Repeat: Continue streaming frames

Best Practices​

  1. Frame Rate: Send 2-5 frames per second (not every frame)
  2. Image Quality: Use JPEG with 0.7-0.8 quality
  3. Error Handling: Implement reconnection logic
  4. Cleanup: Close connection when done
  5. Heartbeat: Implement ping/pong for connection health

Heartbeat​

The server sends periodic heartbeat messages:

{
  "type": "heartbeat",
  "timestamp": "2025-12-04T10:30:00Z"
}

Respond with a pong:

{
  "type": "pong"
}

Error Messages​

Server may send error messages:

{
  "type": "error",
  "code": "PROCESSING_ERROR",
  "message": "Failed to process frame"
}

Next Steps​