> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Camera-based heart rate measurement with @elata-biosciences/rppg-web

## What is rPPG?

Remote photoplethysmography (rPPG) extracts heart rate from subtle color changes in facial skin captured by a standard camera. No contact sensor is needed, just a webcam.

***

## When To Use This Package

Use `@elata-biosciences/rppg-web` when your app needs:

* camera-based biosignal processing in the browser
* a higher-level rPPG session API instead of raw WASM orchestration
* diagnostics and app-facing helpers around rPPG sessions

***

## Installation

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add @elata-biosciences/rppg-web
  ```

  ```bash npm theme={null}
  npm install @elata-biosciences/rppg-web
  ```
</CodeGroup>

Requirements: Node.js 20+, browser with camera access and WebAssembly support.

***

## Recommended Usage: `createRppgSession`

For most browser apps, start with `createRppgSession()`. It handles WASM init, frame capture, ROI orchestration, diagnostics, and cleanup.

```typescript theme={null}
import { createRppgSession } from "@elata-biosciences/rppg-web";

const session = await createRppgSession({
  video: videoEl,
  sampleRate: 30,
  backend: "auto",
  faceMesh: "off",
  onDiagnostics: (diagnostics) => {
    console.log(diagnostics.state.status, diagnostics.faceTrackingMode);
    console.log(diagnostics.framesSeen, diagnostics.totalSamplesReceived);
  },
});

const metrics = session.getMetrics();
console.log("BPM:", metrics.bpm);

// Stop and release camera on cleanup
await session.stop();
```

Use `createManagedRppgSession()` if you also want automatic restart after terminal processor failures.

***

## Diagnostics Guidance

Every session diagnostics payload includes state, issue codes, sampling stats, and processor failure information.

* If `session.state.status` becomes `failed`, treat the underlying processor as terminal and recreate the session.
* If `backend: "auto"` falls back to an unavailable backend mode, diagnostics report that state instead of failing silently.

***

## Advanced: `RppgProcessor`

For custom orchestration, drop to `RppgProcessor` directly. Only use this when you need something `createRppgSession()` does not provide. If you are debugging, compare against `createRppgSession()` first.

```typescript theme={null}
import { RppgProcessor } from "@elata-biosciences/rppg-web";

const processor = new RppgProcessor("wasm", 30); // backend, sampleRate

// Feed green-channel intensity from face ROI each frame
processor.pushSample(performance.now(), greenIntensity);

const metrics = processor.getMetrics();
console.log("BPM:", metrics.bpm);
```

### Constructor

```typescript theme={null}
new RppgProcessor(backend: Backend, sampleRate: number, windowSeconds?: number)
```

| Parameter       | Type                   | Description                           |
| --------------- | ---------------------- | ------------------------------------- |
| `backend`       | `"wasm"` or `"native"` | Processing backend                    |
| `sampleRate`    | `number`               | Expected frames per second (e.g., 30) |
| `windowSeconds` | `number`               | Analysis window length (default: 10)  |

### Pushing Samples

```typescript theme={null}
processor.pushSample(timestampMs, intensity);           // green channel only
processor.pushSampleRgb(timestampMs, r, g, b, skinRatio?);
processor.pushSampleRgbMeta(timestampMs, r, g, b, skinRatio?, motion?, clipRatio?);
```

### Metrics

| Field         | Type     | Description                 |
| ------------- | -------- | --------------------------- |
| `bpm`         | `number` | Estimated heart rate in BPM |
| `quality`     | `number` | Signal quality (0 to 1)     |
| `spectralBpm` | `number` | Spectral analysis estimate  |
| `acfBpm`      | `number` | Autocorrelation estimate    |
| `confidence`  | `number` | Overall confidence          |

***

## Key Exports

* `createRppgSession`
* `createManagedRppgSession`
* `RppgProcessor`
* `loadWasmBackend`
* `createRppgAppAdapter`
* `createRppgAppMonitor`
* `normalizeRppgError`
* `computeTraceWaveformDebug`
* `ensureVideoPlaying`

***

## Next

<CardGroup cols={2}>
  <Card title="rPPG Existing App Tutorial" icon="circle-play" iconType="light" href="/sdk/tutorials/rppg-existing-app">
    Step-by-step integration guide
  </Card>

  <Card title="Frame Sources" icon="camera" iconType="light" href="/sdk/rppg-web/frame-sources">
    MediaPipe face detection and camera capture
  </Card>

  <Card title="Calibration" icon="bullseye" iconType="light" href="/sdk/rppg-web/calibration">
    Muse fusion and calibration models
  </Card>

  <Card title="Camera Integration Guide" icon="video" iconType="light" href="/sdk/guides/rppg-camera">
    End-to-end rPPG setup
  </Card>
</CardGroup>