@hiresphere-acesphere/proctoring-core

A high-performance, intelligent AI proctoring library powered by MediaPipe. Version 2.0.0 introduces a robust event-driven architecture that classifies raw signals into high-level anomalies with automatic visual proof.

🚀 Installation

npm install @hiresphere-acesphere/proctoring-core

📦 TypeScript Support

The package includes built-in TypeScript definitions. You'll get full intellisense for ProctoringSDK, AnomalyEvent, and all configuration options out of the box.

🛠 Quick Start (v2.0.0+)

The SDK now evaluates raw landmarks internally and emits clean anomaly events. Each event includes a snapshot (base64 JPEG) of the exact frame that triggered the violation.

import { ProctoringSDK } from '@hiresphere-acesphere/proctoring-core';

// 1. Initialize with thresholds
const sdk = new ProctoringSDK({
  apiKey: 'your-api-key',
  thresholds: {
    faceAbsentFrames: 3,    // Wait 3 frames before firing FACE_ABSENT
    phoneDetectedFrames: 2, // Wait 2 frames for cell phone
    cooldownMs: 5000        // Prevent same-event spam for 5 seconds
  }
});

await sdk.init();

// 2. Start monitoring
const video = document.querySelector('video');
sdk.start(video);

// 3. Listen for High-Level Anomalies (New in v2.0.0)
sdk.on('anomaly', (event) => {
  console.log(`🚨 ${event.type} Detected!`);
  console.log(`Severity: ${event.severity}`);
  console.log(`Proof Snapshot: ${event.snapshot}`); // Base64 JPEG Data URL
});

// 4. Raw Pulse (Optional, for debugging)
sdk.on('pulse', (data) => {
    // Contains raw MediaPipe coordinates and blendshapes
});

// 5. Cleanup
// sdk.destroy();

🧠 Supported Anomalies

The SDK provides built-in detection for 9 major violation types:

| Event | Logic | Severity | |---|---|---| | FACE_ABSENT | No face detected in frame | 🔴 Critical | | MULTIPLE_FACES | More than 1 face detected | 🔴 Critical | | PHONE_DETECTED | Cell phone visible in environment | 🔴 Critical | | PERSON_DETECTED | Extra person visible in background | 🔴 Critical | | LAPTOP_DETECTED | Second laptop/device detected | 🔴 Critical | | LOOKING_AWAY | Gaze/Head pose significantly off-center | 🟠 Alert | | EYES_CLOSED | Eyes closed for sustained duration | 🟠 Alert | | BOOK_DETECTED | Physical book detected in frame | 🟠 Alert | | MOUTH_MOVING | Jaw movement pattern indicates talking | 🟡 Warning |

📸 Snapshot Proofs

Every anomaly event automatically includes a snapshot field. This is a compressed (70% quality, 50% scale) JPEG base64 string captured at the exact millisecond the anomaly threshold was met. This serves as tamper-proof evidence for later review.

⚙️ Configuration Options

| Option | Default | Description | |---|---|---| | faceAbsentFrames | 3 | Consecutive frames without a face to trigger event | | multipleFacesFrames | 2 | Consecutive frames with 2+ faces | | phoneDetectedFrames | 2 | Consecutive frames with a phone | | cooldownMs | 5000 | Minimum wait time between same-type events | | eyeClosedThreshold | 0.6 | Sensitivity for eye closure (0.0 - 1.0) | | mouthOpenThreshold | 0.3 | Sensitivity for jaw movement |

🧪 Verification Lab

Test your implementation using the built-in lab:

# 1. Install Lab
npm install -D @hiresphere-acesphere/proctoring-lab

# 2. Run Lab
npx proctoring-test

🛡 Security & Guidelines

• Origin Filtering: Restrict your API Key usage to authorized domains in your backend.
• HTTPS Required: The SDK requires a secure context for camera access and telemetry.
• WASM Assets: Ensure CSP allows wasm-eval and blob: sources.

© 2026 HireSphere AceSphereAI. Proprietary and Confidential.