# 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 `