# Camera SDK overview
The Meeeetup camera SDK turns a video stream into **one good photograph per face**. It detects faces, tracks each one across frames, scores how well the subject is facing the lens, and hands you the best frame it saw.
It is capture-only. The SDK never opens a socket: you receive face crops through a callback and decide where they go — the Meeeetup `/capture` API, your own backend, disk, anywhere.
## Packages
| Package | Install | What it is |
|---|---|---|
| `@meeeetup/camera-core` | `pnpm add @meeeetup/camera-core` | The pipeline: tracking, pose scoring, selection. No DOM, no native code. |
| `@meeeetup/camera-web` | `pnpm add @meeeetup/camera-web` | MediaPipe BlazeFace + React provider, hooks and components. |
| `@meeeetup/camera-react-native` | `pnpm add @meeeetup/camera-react-native` | Vision Camera frame processor backed by native ML Kit. |
The platform packages depend on core, so installing `@meeeetup/camera-web` pulls the pipeline with it. Install core on its own only when you are wiring a detector the SDK does not ship.
Both platform packages are published publicly on npmjs.org — no token, no registry configuration.
## How a face becomes a photo
```
video frame
└─ detector (MediaPipe on web, ML Kit on native) → Detection[]
└─ admission: drop anything under minDetectionScore or minFaceHeight
└─ track: match each face to a track by centroid distance
└─ score pose: getFrontalness() → 0–100
└─ select the best frame for that track
└─ onSelect(face) / onBatchCapture(faces)
```
Two things are worth internalising before you configure anything:
- **Tracking is per face, not per frame.** A subject who walks in, hesitates and then looks up is one track with many frames, and the SDK's job is choosing among them.
- **Pose and detector confidence are different numbers.** `Detection.score` is the detector's certainty that a face is there. Frontalness is how well that face is turned towards the camera. They are filtered separately and never multiplied.
## Two capture modes
**Passive** watches a room. Every face in frame is tracked independently, best frames are buffered, and a timer hands them to you in batches. This is the mode for a ceiling camera, a doorway, a reception desk that nobody interacts with.
**Interactive** captures one subject who knows they are being photographed — a check-in kiosk. On web this is the alignment ring: the subject centres their face, holds still, and a frame is taken.
```tsx
```
## Where to go next
- [Quick start (React)](/en/docs/sdk/quickstart-react/) — a working passive camera in about twenty lines.
- [Configuration](/en/docs/sdk/configuration/) — every capture gate, what it defaults to, and when to move it.
- [React Native](/en/docs/sdk/react-native/) — the Vision Camera frame processor.
Nothing beats watching it run: the [live demo](/en/demo) executes this exact pipeline in your browser, with the thresholds on sliders.
---
# Quick start (React)
`@meeeetup/camera-web` ships a provider that owns the camera, the detector and the capture session, plus components that read from it. Everything below runs client-side; nothing leaves the browser unless your own sink sends it.
```bash
pnpm add @meeeetup/camera-web
```
## The shortest working camera
```tsx
import { MeeeetUpCamProvider, CameraViewport, FaceGrid } from "@meeeetup/camera-web";
export function Reception() {
return (
{
await fetch("/capture", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ images: faces.map((f) => f.dataUrl) }),
});
}}
>
);
}
```
That is a complete passive deployment: the viewport requests the camera and draws tracking boxes, every face gets its best frame selected, and `onBatchCapture` fires every ten seconds with whatever was selected.
## Configuration as an object
Capture settings are plain data, so keep them in one object and spread it. This is the shape most deployments end up with — one module exporting the profile, one component consuming it:
```tsx
import type { PassiveCaptureOnlyMeeeetUpCamProviderProps } from "@meeeetup/camera-web";
type CaptureConf = Omit;
export const conf = {
mode: "passive",
minDetectionScore: 0.6, // ignore what the detector is unsure about
minFaceHeight: 0.18, // ignore faces smaller than 18% of frame height
minFrontalness: 55, // ignore faces not turned towards the lens
captureWindowMs: 2_000, // search two seconds for the best frame
cooldownMs: 30_000, // then leave that person alone for 30s
onBatchCapture: send,
} satisfies CaptureConf;
```
```tsx
```
Every field is optional except `mode` and the sink (`onBatchCapture` in passive, `onCapture` in interactive). Omit one and you get the shipped default — see [Configuration](/en/docs/sdk/configuration/) for the full table.
## Reading capture state
`useMeeeetUpCam()` returns the live state of the session. It is a discriminated union on `mode`, so narrow before touching mode-specific fields:
```tsx
import { useMeeeetUpCam } from "@meeeetup/camera-web";
function CaptureStatus() {
const cam = useMeeeetUpCam();
if (cam.error) return
{cam.error}
;
if (!cam.ready) return
Starting the camera…
;
if (cam.mode !== "passive") return null;
return (
{cam.trackedCount} in frame · {cam.totalCount} captured this session
);
}
```
| Field | Meaning |
|---|---|
| `ready` / `error` | Camera and model status. |
| `trackedCount` | Faces being tracked this instant. |
| `totalCount` | Distinct faces selected at least once this session. |
| `livePreviews` | Best crop so far per visible face — the thumbnails `FaceGrid` renders. |
| `selectedFaces` | Faces buffered and waiting for the next batch. |
| `flushBatch()` | Hand the buffer to `onBatchCapture` now — call it on page hide. |
| `rearm()` | Restart every capture window, so faces already captured are searched again. |
| `devices`, `currentDeviceId`, `setDeviceId`, `toggleCamera` | Camera selection, persisted in `localStorage`. |
## Components
All of them read the provider through context, so they take no props and can be placed anywhere inside it.
| Component | Renders |
|---|---|
| `CameraViewport` | The `