### Minimal Browser Setup with CDN

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/README.md

Quickest way to start using VitalLens in the browser without a build step. This example uses the raw VitalLens class to analyze a webcam feed via CDN.

```html
<video id="my-video" autoplay muted playsinline></video>

<script type="module">
  import { VitalLens } from 'https://cdn.jsdelivr.net/npm/vitallens';

  (async () => {
    try {
      const videoElement = document.getElementById('my-video');
      const stream = await navigator.mediaDevices.getUserMedia({ video: true });
      videoElement.srcObject = stream;

      const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

      // Attach stream and start
      await vl.setVideoStream(stream, videoElement);
      
      vl.addEventListener('vitals', (result) => {
        console.log('Heart Rate:', result.vitals.heart_rate.value);
      });
      
      vl.startVideoStream();
    } catch (err) {
      console.error("Failed to start VitalLens:", err);
    }
  })();
</script>
```

--------------------------------

### Build and Run Vitallens.js Examples

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/README.md

Instructions for building the Vitallens.js library and running included examples locally. Replace YOUR_KEY with your actual API Key.

```bash
npm install
npm run build
```

```bash
API_KEY=YOUR_KEY npm run start:scan
```

```bash
API_KEY=YOUR_KEY npm run start:monitor
```

```bash
API_KEY=YOUR_KEY npm run start:file
```

```bash
API_KEY=YOUR_KEY npm run start:widget
```

```bash
API_KEY=YOUR_KEY npm run start:webcam-minimal
```

```bash
API_KEY=YOUR_KEY npm run start:file-node
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Clone the repository and install project dependencies using npm. Ensure Node.js version 20 or higher is used.

```bash
git clone https://github.com/Rouast-Labs/vitallens.js.git
cd vitallens.js
npm install
```

--------------------------------

### Start Video Stream (Browser)

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Initiates the camera stream and begins processing. If no stream is set, it attempts to acquire the user's webcam automatically.

```javascript
vl.startVideoStream();
```

--------------------------------

### Install Vitallens via NPM or Yarn

Source: https://github.com/rouast-labs/vitallens.js/blob/main/README.md

Install the Vitallens package using npm or yarn for use in Node.js projects or with bundlers.

```bash
npm install vitallens
# or
yarn add vitallens
```

--------------------------------

### startVideoStream

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Starts the camera stream and begins processing. If a stream hasn't been set via `setVideoStream`, it attempts to acquire the user's webcam automatically. This method is browser-only.

```APIDOC
### `startVideoStream()`

*(Browser Only)*

Starts the camera stream and begins processing. If a stream hasn't been set via `setVideoStream`, it attempts to acquire the user's webcam automatically.

```javascript
vl.startVideoStream();
```
```

--------------------------------

### Start Real-Time Inference with `startVideoStream()`

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Initiates continuous vital sign estimation from the active webcam. If no stream is set, it attempts to acquire the user's webcam. Emits 'vitals' events as results become available.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

async function startMonitoring() {
  const videoEl = document.getElementById('video');
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  videoEl.srcObject = stream;

  await vl.setVideoStream(stream, videoEl);

  vl.addEventListener('vitals', (result) => {
    const hr = result.vitals.heart_rate;
    if (hr) {
      document.getElementById('hr-display').textContent =
        `Heart Rate: ${hr.value.toFixed(1)} ${hr.unit} (confidence: ${(hr.confidence * 100).toFixed(0)}%)`;
    }
  });

  vl.startVideoStream(); // Start inference loop
}

startMonitoring();
```

--------------------------------

### Stream Lifecycle Management (Pause/Resume)

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/README.md

Manage the stream lifecycle by toggling processing to save bandwidth when results are not actively being viewed. This example shows how to pause and resume the video stream.

```javascript
let isProcessing = true;
const btn = document.getElementById('toggle-btn');

btn.onclick = () => {
  if (isProcessing) {
    // Pauses API calls, but keeps the webcam active
    vl.pauseVideoStream();
    btn.textContent = 'Resume';
  } else {
    // Resumes API calls
    vl.startVideoStream();
    btn.textContent = 'Pause';
  }
  isProcessing = !isProcessing;
};

// Cleanup when leaving the page
window.onbeforeunload = () => {
  vl.stopVideoStream();
};
```

--------------------------------

### Node.js/Express Proxy Implementation

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/proxies.md

A production-ready example of a proxy server using Node.js and Express. It handles model resolution and video stream forwarding, securely using an API key from environment variables.

```javascript
const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');

const app = express();
const PORT = process.env.PORT || 3000;

// Securely store your API key in an environment variable
const API_KEY = process.env.VITALLENS_API_KEY;
const API_BASE = 'https://api.rouast.com/vitallens-v3';

// Increase limit for video file uploads if necessary
app.use(bodyParser.json({ limit: '50mb' }));
app.use(bodyParser.raw({ type: 'application/octet-stream', limit: '50mb' }));

// Enable CORS for your allowed domain
app.use(cors({
  origin: 'http://example.com', // Your allowed domain
  methods: ['GET', 'POST', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Encoding', 'X-State', 'X-Model', 'X-Origin']
}));

// 1. Forward Model Resolution
app.get('/resolve-model', async (req, res) => {
  try {
    const upstreamUrl = new URL(`${API_BASE}/resolve-model`);
    upstreamUrl.search = new URLSearchParams(req.query).toString();

    const response = await fetch(upstreamUrl, {
      method: 'GET',
      headers: { 'x-api-key': API_KEY },
    });
    
    const data = await response.json();
    res.status(response.status).json(data);
  } catch (error) {
    console.error('Proxy Resolve error:', error);
    res.status(500).send('Internal server error');
  }
});

// 2. Forward Stream/Inference
app.post(['/stream', '/file'], async (req, res) => {
  try {
    // Forward to the exact same path on the upstream API
    const upstreamUrl = `${API_BASE}${req.path}`;
    
    const response = await fetch(upstreamUrl, {
      method: 'POST',
      headers: {
        'Content-Type': req.headers['content-type'] || 'application/json',
        'x-api-key': API_KEY,
        // Forward custom headers used by the client
        'X-Encoding': req.headers['x-encoding'] || '',
        'X-State': req.headers['x-state'] || '',
        'X-Model': req.headers['x-model'] || '',
        'X-Origin': req.headers['x-origin'] || ''
      },
      body: req.headers['content-type'] === 'application/json' 
            ? JSON.stringify(req.body) 
            : req.body
    });
    
    const data = await response.text();
    res.status(response.status).send(data);
  } catch (error) {
    console.error('Proxy Inference error:', error);
    res.status(500).send('Internal server error');
  }
});

app.listen(PORT, () => {
  console.log(`Proxy server listening on port ${PORT}`);
});
```

--------------------------------

### Example VitalLensResult Object

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

An example of a `VitalLensResult` object obtained after processing a video file. It demonstrates the structure and typical values for face coordinates, vital signs, and waveform data.

```typescript
const exampleResult = {
  face: {
    coordinates: [[247, 52, 444, 332], /* ...per frame */],
    confidence:  [0.6115, 0.9207, 0.9183],
    note: "Face detection coordinates (x0,y0,x1,y1)"
  },
  vitals: {
    heart_rate:       { value: 60.21, unit: "bpm", confidence: 0.9205, note: "Global HR estimate" },
    respiratory_rate: { value: 12.08, unit: "bpm", confidence: 0.9969, note: "Global RR estimate" },
    hrv_sdnn:         { value: 45.3,  unit: "ms",  confidence: 0.85,   note: "HRV SDNN" },
    hrv_rmssd:        { value: 38.1,  unit: "ms",  confidence: 0.82,   note: "HRV RMSSD" },
  },
  waveforms: {
    ppg_waveform:           { data: [0.12, 0.15, 0.18], confidence: [0.99, 0.99], unit: "unitless", note: "" },
    respiratory_waveform:   { data: [0.01, 0.02, 0.03], confidence: [0.95, 0.95], unit: "unitless", note: "" },
  },
  fps: 30.0,
  model_used: "vitallens-2.0",
  message: "The provided values are estimates for general wellness only."
};
```

--------------------------------

### Node.js File Processing

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/README.md

Process a video file server-side using Node.js. This example demonstrates initializing VitalLens, listening for progress updates, and processing a video file.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({
  method: 'vitallens',
  apiKey: process.env.VITALLENS_API_KEY
});

// Listen for progress updates
vl.addEventListener('fileProgress', (msg) => console.log(msg));

async function run() {
  try {
    const result = await vl.processVideoFile('./examples/sample_video_1.mp4');
    console.log('Result:', JSON.stringify(result, null, 2));
  } catch (error) {
    console.error('Processing failed:', error);
  } finally {
    await vl.close();
  }
}

run();
```

--------------------------------

### Initialize and Start VitalLens Webcam Stream

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/browser/webcam_minimal.html

This code initializes VitalLens with your API key, sets up the webcam stream, and begins processing video for vital sign detection. It logs detected vitals to the console and automatically stops after 30 seconds. Ensure you replace 'YOUR_API_KEY' with your actual key.

```javascript
import { VitalLens } from '../vitallens.browser.js';

const options = {
  method: 'vitallens',
  apiKey: 'YOUR_API_KEY', // Replace with actual API key
};

const vitallens = new VitalLens(options);

async function detectVitals() {
  // Set up webcam
  const video = document.getElementById('video');
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: false,
    video: { facingMode: 'user' },
  });
  video.srcObject = stream;
  await vitallens.setVideoStream(stream, video);

  // Listen for vitals events
  vitallens.addEventListener('vitals', (result) => {
    console.log(result); // Log detected vitals
  });

  // Start VitalLens
  vitallens.startVideoStream();

  // Stop detection after 30 seconds
  setTimeout(() => vitallens.stop(), 30000);
}

// Initialize and start VitalLens
window.onload = async () => {
  console.log('Initializing VitalLens...');
  await detectVitals();
};
```

--------------------------------

### Basic Usage of vitallens-scan Component

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/components.md

Use the `<vitallens-scan>` tag to embed a guided 30-second measurement process. Requires an API key for authentication.

```html
<vitallens-scan api-key="YOUR_KEY"></vitallens-scan>
```

--------------------------------

### Attach Media Stream to VitalLens (Browser)

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Manually attach an existing MediaStream and an optional video element to the VitalLens instance in the browser. This is used when managing camera permissions and UI independently. Must be called before starting the video stream.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

async function init() {
  const videoEl = document.getElementById('my-video');

  // Acquire camera
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: 'user', width: 640, height: 480 },
    audio: false,
  });
  videoEl.srcObject = stream;

  // Attach to VitalLens
  await vl.setVideoStream(stream, videoEl);
  console.log('Stream attached, ready to start.');
}

init();
```

--------------------------------

### Integrate `<vitallens-scan>` for Health Checks

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Use this component for a 30-second guided health check. It manages face positioning, lighting, progress, and results. Ideal for telemedicine waiting rooms or onboarding.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
  <link rel="preconnect" href="https://api.rouast.com" crossorigin>
</head>
<body style="background: black; display: flex; align-items: center; justify-content: center;">
  <!-- api-key for development; use proxy-url in production -->
  <vitallens-scan api-key="YOUR_API_KEY"></vitallens-scan>

  <!-- Production: hide key behind a proxy -->
  <!-- <vitallens-scan proxy-url="https://your-proxy.com/api"></vitallens-scan> -->
</body>
</html>
```

--------------------------------

### setVideoStream(stream, videoElement) — Attach Media Stream

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Manually attaches an existing MediaStream and an optional video element to the VitalLens instance. This is useful when your application handles camera permissions and UI independently. Must be called before starting the video stream.

```APIDOC
## setVideoStream(stream, videoElement) — Attach Media Stream

### Description
*(Browser Only)* Manually attaches an existing `MediaStream` and an optional `<video>` element to the VitalLens instance. Use this when your application manages camera permission and UI independently. Must be called before `startVideoStream()`.

### Parameters
- **stream** (MediaStream) - The `MediaStream` object obtained from `navigator.mediaDevices.getUserMedia()`.
- **videoElement** (HTMLVideoElement) - The optional `<video>` element to which the stream is attached and from which frames will be processed.

### Request Example
```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

async function init() {
  const videoEl = document.getElementById('my-video');

  // Acquire camera
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: 'user', width: 640, height: 480 },
    audio: false,
  });
  videoEl.srcObject = stream;

  // Attach to VitalLens
  await vl.setVideoStream(stream, videoEl);
  console.log('Stream attached, ready to start.');
}

init();
```
```

--------------------------------

### new VitalLens(options) — Constructor

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Initializes a new VitalLens instance. Configure the inference method, API credentials, and waveform behavior. API-backed methods require an apiKey or proxyUrl, while local-only methods do not.

```APIDOC
## new VitalLens(options)

### Description
The main entry point for the library. Creates a new VitalLens instance configured with the desired inference method, API credentials, and waveform behavior. `method: 'vitallens'` routes through the VitalLens API and requires an `apiKey` or `proxyUrl`. Methods `pos`, `chrom`, and `g` are offline-only and support only heart rate and PPG waveform.

### Parameters
- **options** (object) - Configuration options for the VitalLens instance.
  - **method** (string) - The inference method to use. Options: `'vitallens'`, `'vitallens-2.0'`, `'pos'`, `'chrom'`, `'g'`. Defaults to `'vitallens'`. For `'vitallens'` methods, an `apiKey` or `proxyUrl` is required.
  - **apiKey** (string) - Your VitalLens API key. Required for `'vitallens'` methods.
  - **proxyUrl** (string) - A URL for a proxy server. Use instead of `apiKey` in production browser applications.
  - **waveformMode** (string) - Controls how waveform data is processed. Options: `'incremental'`, `'windowed'`, `'global'`. Defaults to `'incremental'`.
  - **fDetFs** (number) - Face detection frequency in Hz. Only applicable for streaming.

### Request Example
```javascript
import { VitalLens } from 'vitallens';

// API-backed inference (recommended)
const vl = new VitalLens({
  method: 'vitallens',       // 'vitallens' | 'vitallens-2.0' | 'pos' | 'chrom' | 'g'
  apiKey: 'YOUR_API_KEY',    // Required for 'vitallens' methods
  proxyUrl: undefined,       // Use instead of apiKey in production browser apps
  waveformMode: 'incremental', // 'incremental' | 'windowed' | 'global'
  fDetFs: 1.0,               // Face detection frequency in Hz (streaming only)
});

// Local-only fallback (no API key needed)
const vlLocal = new VitalLens({ method: 'pos' });
```
```

--------------------------------

### VitalLens.js Result JSON Structure

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/results.md

This is an example of the JSON structure returned by VitalLens.js. It includes face coordinates, detected vital signs, and waveform data.

```json
{
  "face": {
    "coordinates": [[247, 52, 444, 332], ...],
    "confidence": [0.6115, 0.9207, 0.9183, ...],
    "note": "Face detection coordinates..."
  },
  "vitals": {
    "heart_rate": {
      "value": 60.21,
      "unit": "bpm",
      "confidence": 0.9205,
      "note": "Global estimate of Heart Rate..."
    },
    "respiratory_rate": {
      "value": 12.08,
      "unit": "bpm",
      "confidence": 0.9969,
      "note": "Global estimate of Respiratory Rate..."
    },
    ...
  },
  "waveforms": {
    "ppg_waveform": {
      "data": [0.12, 0.15, 0.18, ...],
      "confidence": [0.99, 0.99, ...],
      "unit": "unitless"
    },
    ...
  },
  "fps": 30.0,
  "message": "The provided values are estimates..."
}
```

--------------------------------

### Initialize VitalLens with Options

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Instantiate the VitalLens class with optional configuration for the rPPG inference method, API key, proxy URL, waveform mode, and face detection frequency.

```javascript
new VitalLens(options)
```

--------------------------------

### Run All Tests

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Execute the entire test suite, including unit and integration tests, with a single npm command.

```bash
npm run test
```

--------------------------------

### Initialize VitalLens and Process Video File

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/browser/file_minimal.html

Initializes the VitalLens SDK with an API key and demonstrates processing a video file. Ensure you replace 'YOUR_API_KEY' with your actual key. This function handles both file input and drag-and-drop events.

```javascript
import { VitalLens } from '../vitallens.browser.js';

// Create VitalLens with your API key and chosen method.
const options = {
  method: 'vitallens',
  apiKey: 'YOUR_API_KEY' // Replace with your actual API key.
};

const vitallens = new VitalLens(options);

async function processVideo(videoFile) {
  if (!videoFile) return;
  console.log(`Processing file: ${videoFile.name}`);
  try {
    const result = await vitallens.processVideoFile(videoFile);
    console.log("Processing complete!");
    console.log(result);
  } catch (error) {
    console.error("Error processing file:", error);
  }
}

// Handle file input changes.
const fileInput = document.getElementById("videoInput");
fileInput.addEventListener("change", () => {
  if (fileInput.files.length) {
    processVideo(fileInput.files[0]);
  }
});

// Handle drag and drop.
const dropZone = document.getElementById("dropZone");
dropZone.addEventListener("click", () => fileInput.click());
dropZone.addEventListener("dragover", event => {
  event.preventDefault();
  dropZone.classList.add("hover");
});
dropZone.addEventListener("dragleave", () => {
  dropZone.classList.remove("hover");
});
dropZone.addEventListener("drop", event => {
  event.preventDefault();
  dropZone.classList.remove("hover");
  const files = event.dataTransfer.files;
  if (files.length) {
    processVideo(files[0]);
  }
});
```

--------------------------------

### startVideoStream()

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Begins continuous vital sign estimation from the active webcam stream. If no stream is attached, it attempts to acquire the user's webcam automatically. Emits 'vitals' events continuously as results become available.

```APIDOC
## `startVideoStream()` — Begin Real-Time Inference

*(Browser Only)* Starts continuous vital sign estimation from the active webcam stream. If no stream has been attached via `setVideoStream()`, the library attempts to acquire the user's webcam automatically. Emits `vitals` events continuously as results become available.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

async function startMonitoring() {
  const videoEl = document.getElementById('video');
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  videoEl.srcObject = stream;

  await vl.setVideoStream(stream, videoEl);

  vl.addEventListener('vitals', (result) => {
    const hr = result.vitals.heart_rate;
    if (hr) {
      document.getElementById('hr-display').textContent =
        `Heart Rate: ${hr.value.toFixed(1)} ${hr.unit} (confidence: ${(hr.confidence * 100).toFixed(0)}%)`;
    }
  });

  vl.startVideoStream(); // Start inference loop
}

startMonitoring();
```
```

--------------------------------

### Initialize VitalLens Constructor

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Instantiate the VitalLens class with options for inference method, API credentials, and waveform behavior. API-backed methods require an apiKey or proxyUrl, while local-only methods do not.

```javascript
import { VitalLens } from 'vitallens';

// API-backed inference (recommended)
const vl = new VitalLens({
  method: 'vitallens',       // 'vitallens' | 'vitallens-2.0' | 'pos' | 'chrom' | 'g'
  apiKey: 'YOUR_API_KEY',    // Required for 'vitallens' methods
  proxyUrl: undefined,       // Use instead of apiKey in production browser apps
  waveformMode: 'incremental', // 'incremental' | 'windowed' | 'global'
  fDetFs: 1.0,               // Face detection frequency in Hz (streaming only)
});

// Local-only fallback (no API key needed)
const vlLocal = new VitalLens({ method: 'pos' });
```

--------------------------------

### Build Package

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Build the distribution bundles for the package, including ESM, CommonJS, and Browser formats. Artifacts are generated in the dist/ directory.

```bash
npm run build
```

--------------------------------

### VitalLens Constructor

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Initializes a new VitalLens instance. You can configure the rPPG method, API key, proxy URL, waveform mode, and face detection frequency.

```APIDOC
## Constructor

```javascript
new VitalLens(options)
```

**Method Options:**

You can choose from several rPPG methods to control how inference is performed:

- `vitallens`: **(Recommended)** Uses the VitalLens API and automatically selects the best model available for your API key (e.g., VitalLens 2.0 with HRV support).
- `vitallens-2.0`: Forces the use of the VitalLens 2.0 model.
- `vitallens-1.0` / `vitallens-1.1`: Forces the use of older model versions.
- `pos`, `chrom`, `g`: Classic rPPG algorithms that run locally (in the browser or Node.js) and do not require an API key.

**Parameters:**

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `method` | `string` | The rPPG method to be used for inference (see options above). | `'vitallens'` |
| `apiKey` | `string` | Your API Key. Required if `method` starts with `vitallens`. | `undefined` |
| `proxyUrl` | `string` | URL to a backend proxy to hide your API Key (Recommended for production). | `undefined` |
| `waveformMode` | `string` | How waveforms are returned: `"incremental"`, `"windowed"`, or `"global"`. | `'incremental'` |
| `fDetFs` | `number` | Face detection frequency in Hz (Live stream only). | `1.0` |
```

--------------------------------

### Integrate `<vitallens-widget>` for Unified Development

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

This advanced widget supports switching between webcam and file inputs, selecting inference algorithms, real-time data visualization, and JSON export. Best for developer tooling and debugging.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
</head>
<body>
  <div style="width: 100%; height: 600px;">
    <vitallens-widget
      api-key="YOUR_API_KEY"
      method="vitallens">
    </vitallens-widget>
  </div>
</body>
</html>
```

--------------------------------

### Initialize and Use Local rPPG Method in VitalLens.js

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

This snippet demonstrates how to initialize VitalLens with a local rPPG method (e.g., 'pos') and process a video stream to extract heart rate and PPG waveform data. Ensure the video element and stream are correctly set up.

```javascript
import { VitalLens } from 'vitallens';

// POS — Plane-Orthogonal-to-Skin, no API key required
const vl = new VitalLens({ method: 'pos' });
// Alternatives: method: 'chrom' | method: 'g'

const videoEl = document.getElementById('video');
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
videoEl.srcObject = stream;

await vl.setVideoStream(stream, videoEl);

vl.addEventListener('vitals', (result) => {
  // Only heart_rate and ppg_waveform are available with local methods
  console.log('Heart Rate (local):', result.vitals.heart_rate?.value, 'bpm');
  console.log('PPG samples:', result.waveforms.ppg_waveform?.data.length);
});

vl.startVideoStream();
```

--------------------------------

### Run Targeted Tests

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Execute specific subsets of tests, such as browser-only tests, Node.js tests, or integration tests. Ensure API_KEY is set for integration tests.

```bash
# Run only Browser tests
npm run test:browser

# Run only Node.js tests
npm run test:node

# Run integration tests (Requires API_KEY)
npm run test:browser-integration
npm run test:node-integration
```

--------------------------------

### Basic Usage of vitallens-file Component

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/components.md

Integrate the `<vitallens-file>` component for processing video files. It handles uploads, processing states, and displays results. Requires an API key.

```html
<vitallens-file api-key="YOUR_KEY"></vitallens-file>
```

--------------------------------

### Robustness and Auto-Reconnect

Source: https://github.com/rouast-labs/vitallens.js/blob/main/examples/README.md

Handle unstable network conditions by listening for the `streamReset` event. This recipe demonstrates how to automatically recover the session by restarting the stream after a connection drop.

```javascript
vl.addEventListener('streamReset', (event) => {
  console.warn('Stream was reset:', event.message);
  
  // 1. Notify user and stop the old stream
  showToast('Connection unstable. Reconnecting...');
  vl.stopVideoStream();

  // 2. Wait a moment and restart
  setTimeout(async () => {
    try {
      // Re-acquire media (good practice to ensure fresh state)
      const stream = await navigator.mediaDevices.getUserMedia({ video: true });
      videoElement.srcObject = stream;
      
      await vl.setVideoStream(stream, videoElement);
      vl.startVideoStream();
      
      hideToast();
    } catch (err) {
      showError('Could not reconnect. Please refresh.');
    }
  }, 3000);
});
```

--------------------------------

### Push Changes and Tag for Prerelease

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Push the version commit and the new prerelease tag to the main branch. This triggers the CI to publish to NPM with the @beta tag.

```bash
git push origin main --follow-tags
```

--------------------------------

### Run Specific Test File

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Execute a single test file using vitest. This command runs the specified test file once.

```bash
npx vitest run test/core/VitalLens.browser.test.ts
```

--------------------------------

### Use Vitallens Core API

Source: https://github.com/rouast-labs/vitallens.js/blob/main/README.md

Initialize and use the VitalLens class for custom logic and data handling in Node.js or browser environments. Requires an API key.

```javascript
import { VitalLens } from 'vitallens';

// Initialize
const vl = new VitalLens({
  method: 'vitallens',
  apiKey: 'YOUR_API_KEY'
});

// Process a file
const result = await vl.processVideoFile(myFile);
console.log("Heart Rate:", result.vitals.heart_rate.value);
```

--------------------------------

### Bump Version for Prerelease

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Increment the package version for a prerelease (beta) using npm. This is used for testing new features before a stable release.

```bash
npm version prerelease --preid=beta
```

--------------------------------

### Set API Key for Integration Tests

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Set the API_KEY environment variable to run integration tests. This is required for verifying communication with the live API.

```bash
# Mac/Linux
export API_KEY="your_api_key_here"
```

```powershell
# Windows (PowerShell)
$env:API_KEY="your_api_key_here"
```

--------------------------------

### Basic Usage of vitallens-widget Component

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/components.md

Use the `<vitallens-widget>` for an advanced interface supporting webcam and file modes, algorithm selection, and data export. Requires an API key.

```html
<vitallens-widget api-key="YOUR_KEY"></vitallens-widget>
```

--------------------------------

### Configure Client with Proxy URL

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/proxies.md

Set the `proxyUrl` option when initializing the VitalLens client to point to your backend proxy. This ensures API keys are not exposed in the browser.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({
  method: 'vitallens',
  // The client will append /resolve-model and /stream to this base URL
  proxyUrl: 'https://your-proxy-server.com/api' 
});
```

--------------------------------

### addEventListener(event, callback)

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Registers a listener for library lifecycle and data events. Supported events include 'vitals', 'streamReset', 'faceDetected', and 'fileProgress'.

```APIDOC
## `addEventListener(event, callback)` — Event Handling

Registers a listener for library lifecycle and data events. The `vitals` event delivers a full `VitalLensResult` object on every inference cycle during streaming. The `streamReset` event enables automatic reconnection on network instability. The `faceDetected` event provides real-time bounding box updates. The `fileProgress` event reports status strings during file processing.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

// Real-time vitals during streaming
vl.addEventListener('vitals', (result) => {
  console.log('HR:',   result.vitals.heart_rate?.value);
  console.log('RR:',   result.vitals.respiratory_rate?.value);
  console.log('SDNN:', result.vitals.hrv_sdnn?.value);
});

// Live face bounding box
vl.addEventListener('faceDetected', (roi) => {
  // roi: { x0, y0, x1, y1, confidence }
  drawBoundingBox(roi);
});

// Auto-reconnect on stream failure
vl.addEventListener('streamReset', (event) => {
  console.warn('Stream reset:', event.message);
  vl.stopVideoStream();
  setTimeout(async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    await vl.setVideoStream(stream, document.getElementById('video'));
    vl.startVideoStream();
  }, 3000);
});

// File processing progress
vl.addEventListener('fileProgress', (msg) => {
  // e.g. "Detecting faces...", "Sending to API...", "Done."
  document.getElementById('status').textContent = msg;
});
```
```

--------------------------------

### Configure Widget with Proxy URL

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/proxies.md

When using VitalLens widgets, set the `proxy-url` attribute to your backend proxy's address. This is an alternative to configuring the client directly.

```html
<vitallens-widget proxy-url="https://your-proxy-server.com/api"></vitallens-widget>
```

--------------------------------

### Browser Client Configuration with Proxy

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Configure the VitalLens client in a browser application to use a backend proxy. Set the `proxyUrl` to your proxy server's endpoint. The `apiKey` is not needed when using a proxy.

```javascript
import { VitalLens } from 'vitallens';
const vl = new VitalLens({
  method: 'vitallens',
  proxyUrl: 'https://your-proxy-server.com/api', // No apiKey needed
});
```

--------------------------------

### Express.js Backend Proxy Server

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Implement a lightweight backend proxy using Express.js to securely route VitalLens traffic. This server forwards requests to the VitalLens API and handles authentication using an API key stored in environment variables.

```javascript
const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');

const app = express();
const API_KEY = process.env.VITALLENS_API_KEY;
const API_BASE = 'https://api.rouast.com/vitallens-v3';

app.use(bodyParser.json({ limit: '50mb' }));
app.use(bodyParser.raw({ type: 'application/octet-stream', limit: '50mb' }));
app.use(cors({
  origin: 'https://your-app.com',
  methods: ['GET', 'POST', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Encoding', 'X-State', 'X-Model', 'X-Origin'],
}));

// Forward model resolution
app.get('/resolve-model', async (req, res) => {
  try {
    const url = new URL(`${API_BASE}/resolve-model`);
    url.search = new URLSearchParams(req.query).toString();
    const response = await fetch(url, {
      method: 'GET',
      headers: { 'x-api-key': API_KEY },
    });
    res.status(response.status).json(await response.json());
  } catch (err) {
    res.status(500).send('Internal server error');
  }
});

// Forward inference requests
app.post(['/stream', '/file'], async (req, res) => {
  try {
    const response = await fetch(`${API_BASE}${req.path}`, {
      method: 'POST',
      headers: {
        'Content-Type': req.headers['content-type'] || 'application/json',
        'x-api-key': API_KEY,
        'X-Encoding': req.headers['x-encoding'] || '',
        'X-State':    req.headers['x-state'] || '',
        'X-Model':    req.headers['x-model'] || '',
        'X-Origin':   req.headers['x-origin'] || '',
      },
      body: req.headers['content-type'] === 'application/json'
        ? JSON.stringify(req.body)
        : req.body,
    });
    res.status(response.status).send(await response.text());
  } catch (err) {
    res.status(500).send('Internal server error');
  }
});

app.listen(3000, () => console.log('Proxy listening on port 3000'));
```

--------------------------------

### Bump Version for Production Release

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Increment the package version for a production release using npm. Use 'patch', 'minor', or 'major' as needed.

```bash
npm version patch # or minor/major
```

--------------------------------

### Import vitallens.js Browser Bundle

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/components.md

Ensure the browser bundle is imported to use the web components. This script tag should be included in your HTML.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
```

--------------------------------

### Integrate `<vitallens-file>` for Video Analysis

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Use this component for file upload and analysis. It prompts for video selection, shows a processing indicator, and then displays extracted vitals and waveforms.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
</head>
<body>
  <!-- Best for: post-processing, async clinical review of recorded videos -->
  <vitallens-file api-key="YOUR_API_KEY"></vitallens-file>
</body>
</html>
```

--------------------------------

### Basic Usage of vitallens-monitor Component

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/components.md

Embed the `<vitallens-monitor>` component for continuous vital sign monitoring. It displays real-time data and handles user adjustments. Requires an API key.

```html
<vitallens-monitor api-key="YOUR_KEY"></vitallens-monitor>
```

--------------------------------

### Process Video File (Browser/Node.js)

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Process a video file using batch mode. Supports File, Blob, or string path inputs. This method is available in both browser and Node.js environments.

```javascript
// Browser
const result = await vl.processVideoFile(fileInput.files[0]);
```

```javascript
// Node.js
const result = await vl.processVideoFile("./video.mp4");
```

--------------------------------

### Include vitallens.js via CDN

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Include this script tag in your HTML to use vitallens.js directly in the browser without a build step.

```html
<!-- CDN (no build step) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
```

--------------------------------

### Run Specific Test File in Watch Mode

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Execute a single test file using vitest in watch mode. Tests will automatically re-run when file changes are detected.

```bash
npx vitest test/core/VitalLens.browser.test.ts
```

--------------------------------

### pauseVideoStream()

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Suspends data transmission to the API while keeping the webcam active. No inference occurs while paused, reducing bandwidth and API costs. Resumes by calling `startVideoStream()` again.

```APIDOC
## `pauseVideoStream()` — Pause Inference

*(Browser Only)* Suspends data transmission to the API while keeping the webcam active. No inference occurs while paused, reducing bandwidth and API costs. Resume by calling `startVideoStream()` again.

```javascript
let isProcessing = true;
const toggleBtn = document.getElementById('toggle-btn');

toggleBtn.addEventListener('click', () => {
  if (isProcessing) {
    vl.pauseVideoStream();
    toggleBtn.textContent = 'Resume';
  } else {
    vl.startVideoStream();  // Resumes inference
    toggleBtn.textContent = 'Pause';
  }
  isProcessing = !isProcessing;
});
```
```

--------------------------------

### Set Video Stream Manually (Browser)

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Manually attach a MediaStream and an optional video element to the VitalLens client. This is useful for custom camera permission management.

```javascript
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
await vl.setVideoStream(stream, document.getElementById('myVideo'));
```

--------------------------------

### Use Vitallens Web Component

Source: https://github.com/rouast-labs/vitallens.js/blob/main/README.md

Integrate the vitallens-scan web component into your HTML for quick vital scanning functionality. Ensure the script is loaded first.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>

<vitallens-scan api-key="YOUR_API_KEY"></vitallens-scan>
```

--------------------------------

### Integrate `<vitallens-monitor>` for Continuous Monitoring

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

This component provides continuous vital signs monitoring, displaying Heart Rate, Respiratory Rate, and HRV. It handles transient issues like face loss or poor lighting automatically.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/vitallens/dist/vitallens.browser.js"></script>
</head>
<body>
  <!-- Best for: dashboards, wellness apps, continuous fitness tracking -->
  <vitallens-monitor api-key="YOUR_API_KEY"></vitallens-monitor>
</body>
</html>
```

--------------------------------

### setVideoStream

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Manually attaches a MediaStream and an optional video element to the client. This method is browser-only and useful for custom camera permission management.

```APIDOC
### `setVideoStream(stream, videoElement)`

*(Browser Only)*

Manually attaches a `MediaStream` and a `<video>` element to the client. Useful if you are managing camera permissions in your own app logic.

**Parameters:**

* `stream`: `MediaStream` object.
* `videoElement`: (Optional) `HTMLVideoElement` to render the feed.

```javascript
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
await vl.setVideoStream(stream, document.getElementById('myVideo'));
```
```

--------------------------------

### Handle Library Events with `addEventListener()`

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Registers listeners for library events such as real-time vitals, face detection, stream resets, and file processing progress. The 'vitals' event delivers a full `VitalLensResult` object.

```javascript
import { VitalLens } from 'vitallens';

const vl = new VitalLens({ method: 'vitallens', apiKey: 'YOUR_API_KEY' });

// Real-time vitals during streaming
vl.addEventListener('vitals', (result) => {
  console.log('HR:',   result.vitals.heart_rate?.value);
  console.log('RR:',   result.vitals.respiratory_rate?.value);
  console.log('SDNN:', result.vitals.hrv_sdnn?.value);
});

// Live face bounding box
vl.addEventListener('faceDetected', (roi) => {
  // roi: { x0, y0, x1, y1, confidence }
  drawBoundingBox(roi);
});

// Auto-reconnect on stream failure
vl.addEventListener('streamReset', (event) => {
  console.warn('Stream reset:', event.message);
  vl.stopVideoStream();
  setTimeout(async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    await vl.setVideoStream(stream, document.getElementById('video'));
    vl.startVideoStream();
  }, 3000);
});

// File processing progress
vl.addEventListener('fileProgress', (msg) => {
  // e.g. "Detecting faces...", "Sending to API...", "Done."
  document.getElementById('status').textContent = msg;
});
```

--------------------------------

### Pause and Resume Video Stream Inference

Source: https://context7.com/rouast-labs/vitallens.js/llms.txt

Suspends data transmission to the API to reduce bandwidth and costs while keeping the webcam active. Resume inference by calling `startVideoStream()` again.

```javascript
let isProcessing = true;
const toggleBtn = document.getElementById('toggle-btn');

toggleBtn.addEventListener('click', () => {
  if (isProcessing) {
    vl.pauseVideoStream();
    toggleBtn.textContent = 'Resume';
  } else {
    vl.startVideoStream();  // Resumes inference
    toggleBtn.textContent = 'Pause';
  }
  isProcessing = !isProcessing;
});
```

--------------------------------

### addEventListener

Source: https://github.com/rouast-labs/vitallens.js/blob/main/docs/ref.md

Registers a listener for specific library events. Supported events include 'vitals', 'streamReset', 'faceDetected', and 'fileProgress'. 'vitals', 'streamReset', and 'faceDetected' are browser-only.

```APIDOC
### `addEventListener(event, callback)`

Registers a listener for specific library events.

**Supported Events:**

- `"vitals"`: *(Browser Only)* Emitted continuously during streaming with the latest estimation results.
- `"streamReset"`: *(Browser Only)* Emitted if the connection is unstable and the stream needs to restart.
- `"faceDetected"`: *(Browser Only)* Emitted when the local face detector updates (contains bounding box).
- `"fileProgress"`: Emitted during file processing with status strings (e.g. "Detecting faces...").

```javascript
vl.addEventListener('vitals', (result) => {
  console.log(result.vitals.heart_rate.value);
});
```
```

--------------------------------

### Lint Code

Source: https://github.com/rouast-labs/vitallens.js/blob/main/CONTRIBUTING.md

Check code quality using eslint. Run this command before submitting a Pull Request to ensure code adheres to project standards.

```bash
npm run lint
```