@touchcastllc/napster-companion-api 1.0.0-alpha.34 → 1.0.0-alpha.35

package/README.md

@@ -523,7 +523,90 @@ const instance = await NapsterCompanionApiSdk.init(token, {
 });
 ```
 
-### 3.2 Position & Layout
+### 3.2 Face Tracking
+
+Real-time face detection using TensorFlow.js + MediaPipe Face Mesh. Detects the user's face via their camera, extracts 468 facial landmarks, and determines talking state via mouth-opening ratio. Fully client-side — no backend involved.
+
+#### Prerequisites
+
+Install the optional peer dependencies (only needed when face tracking is enabled):
+
+```bash
+npm install @tensorflow/tfjs @tensorflow-models/face-landmarks-detection
+```
+
+These libraries (~2MB) are lazy-loaded at runtime — they are not included in the main SDK bundle.
+
+#### Enable & Configure
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    faceTracking: {
+      enabled: true,
+      fps: 15,                // Detection rate: 1–30 FPS (default: 15)
+      talkingThreshold: 0.015, // Mouth opening ratio threshold (default: 0.015)
+    },
+  },
+  onFaceTrackingData: (data) => {
+    if (data) {
+      console.log("Talking:", data.isTalking);
+      console.log("Landmarks:", data.landmarks.length); // 468
+      console.log("Mouth:", data.mouthLandmarks);
+    } else {
+      console.log("No face detected");
+    }
+  },
+  onFaceTrackingError: (error) => {
+    console.error("Face tracking error:", error.message);
+  },
+});
+```
+
+#### Start & Stop
+
+```typescript
+// Start detection (opens camera, loads model on first call)
+await instance.startFaceTracking();
+
+// Pause detection (stops camera, keeps model loaded for fast restart)
+instance.stopFaceTracking();
+
+// Restart — reuses model, only reopens camera
+await instance.startFaceTracking();
+```
+
+#### Face Tracking Data
+
+Each detection frame emits a `FaceTrackingData` object (or `null` if no face is detected):
+
+```typescript
+interface FaceTrackingData {
+  landmarks: Array<{ x: number; y: number; z: number }>; // 468 points, 0–1 normalized
+  mouthLandmarks: {
+    topLip:      { x: number; y: number };
+    bottomLip:   { x: number; y: number };
+    leftCorner:  { x: number; y: number };
+    rightCorner: { x: number; y: number };
+  } | null;
+  isTalking: boolean; // smoothed mouth-opening ratio > threshold
+}
+```
+
+#### Error Codes
+
+| Code                       | When                                      |
+| -------------------------- | ----------------------------------------- |
+| `CAMERA_PERMISSION_DENIED` | User denied camera access                 |
+| `CAMERA_NOT_FOUND`         | No camera available                       |
+| `MODEL_LOAD_FAILED`        | TensorFlow.js / MediaPipe failed to load  |
+| `DETECTION_FAILED`         | Runtime detection error                   |
+
+#### Cleanup
+
+Face tracking is automatically destroyed when `instance.destroy()` is called. The model is disposed and camera tracks are stopped.
+
+### 3.3 Position & Layout
 
 Customize the avatar's position on the screen using predefined positions or custom styles. Also you can override the position using style properties.
 
@@ -685,7 +768,27 @@ if (instance.isFeatureEnabled("disclaimer")) {
 }
 ```
 
-### 5.4 Communication Methods
+### 5.4 Face Tracking Methods
+
+#### `startFaceTracking(): Promise<void>`
+
+Start face tracking. Opens the user's camera and begins the detection loop. The model is loaded on the first call and reused on subsequent calls.
+
+```typescript
+await instance.startFaceTracking();
+```
+
+> **Note:** Requires `features.faceTracking.enabled = true` in the init config. Throws a `FeatureError` if not enabled.
+
+#### `stopFaceTracking(): void`
+
+Pause face tracking. Stops the camera and detection loop but keeps the model loaded for fast restart.
+
+```typescript
+instance.stopFaceTracking();
+```
+
+### 5.5 Communication Methods
 
 #### `sendCommand(command: { type: string; data?: object }): void`
 
@@ -736,6 +839,11 @@ interface NapsterCompanionApiConfig {
     };
     disclaimer?: { enabled: boolean; text?: string };
     showSDKLoader?: { enabled: boolean; bgColor?: string };
+    faceTracking?: {
+      enabled: boolean;
+      fps?: number;              // 1–30, default 15
+      talkingThreshold?: number; // default 0.015
+    };
   };
 
   // Configuration
@@ -749,6 +857,8 @@ interface NapsterCompanionApiConfig {
   onInactivityStatusChange?: (isInactive: boolean) => void;
   onDestroy?: () => void;
   onFeaturesUpdate?: (features: FeatureConfig) => void;
+  onFaceTrackingData?: (data: FaceTrackingData | null) => void;
+  onFaceTrackingError?: (error: Error) => void;
 }
 ```
 
@@ -767,6 +877,9 @@ npm install @touchcastllc/napster-companion-api
 
 # Install peer dependencies
 npm install @reduxjs/toolkit
+
+# If using face tracking, also install:
+npm install @tensorflow/tfjs @tensorflow-models/face-landmarks-detection
 ```
 
 **Problem: Invalid or expired token**  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api",
-  "version": "1.0.0-alpha.34",
+  "version": "1.0.0-alpha.35",
   "keywords": [
     "napster",
     "companion-api",