The SDK: @leumas/headlock

One tracker, one pose contract, one component that is allowed to start the camera. Everything on this site is built from it.

Install

The package is in the Leumas monorepo as @leumas/headlock and is what this site runs. It is not yet on the public npm registry; the download page has a single-file demo you can open today, and this page will carry the npm command when the package is published.

useHeadLock

const { pose, active, start, stop, videoRef } = useHeadLock(). Attach videoRef to a hidden video element. start() loads MediaPipe, then asks for the camera through the latch; stop() runs on unmount so the camera cannot outlive the component.

The pose contract

pose is { x, y, z, hasFace }. x and y are the midpoint between the eyes in image space, 0 to 1, so the centre is (0.5, 0.5). z is the distance between the eyes in the same units, roughly 0.08 at arm's length; it grows as you lean in. hasFace is true only when a face was seen in the last half second. Poses are smoothed; without a face they drift slowly so a scene settles instead of freezing.

locateFile

MediaPipe fetches its model files at start. locateFile maps a file name to a URL; this site points it at /perspective-mediapipe/, its own copy, so nothing depends on a CDN. Point yours at your own copy for an offline or CSP-restricted install.

The latch

The stream comes from @leumas/devices' requestMedia. A blocked camera is remembered for the session; start() rejects with code media-blocked and the browser is not prompted again. Only retryMedia("video") from an explicit click lifts it. useMediaConsent() reports prompt, granted or denied without ever asking.

HeadlockStage

<HeadlockStage scene={getScene("neon-corridor")} /> renders the scene on a canvas with a drifting pose, a hidden video and the one consent button. Pass onPose to drive your own three.js or DOM instead of a scene. It is the only component in the package that starts a camera.