Provider & client

Canonical SDK API from the offline package (@pose-tracker/react-native-pose-estimation). Light and web share the same surface; light-only options are marked below. WebView hosts use query params, not this Provider — WebView query parameters. See also: WebViewPoseView · Exercises · Events · Features & plans

PoseTrackerProvider

<PoseTrackerProvider
  apiToken="ptk_…"           // optional — omit for free keypoints-only
  autoPreload={false}        // default false — mount does NOT load MoveNet
  options={{ /* PoseTrackerClientOptions */ }}
>
  {children}
</PoseTrackerProvider>

Prop	Type	Default	Notes
`apiToken`	`string`	—	Optional. Without a token → `keypoints-only`. With a valid key → handshake + remote movement engine.
`autoPreload`	`boolean`	`false`	If `true`, calls `preload()` on mount (basic cold-start — no camera).
`options`	`PoseTrackerClientOptions`	`{}`	See options.
`children`	`ReactNode`	—	Required.

Options

PoseTrackerClientOptions extends handshake ConfigureOptions plus runtime knobs.

Shared (offline + light)

Option	Type	Default	Notes
`features`	`PoseTrackerFeatures`	all `false`	`angles`, `recommendations`, `progression`, `keypoints` (during exercise), `minGrade`. See Features & plans.
`qualityChoice`	`'AdaptiveChoice' \| QualityProfileId`	`'AdaptiveChoice'`	Pin: `prime` \| `pro` \| `lite` \| `ultralite` \| `basic`.
`capturePriority`	`'performance' \| 'quality'`	`'performance'`	FPS floor vs sharp preview. See Adaptive quality.
`baseUrl`	`string`	PoseTracker Strapi host	Override for staging / self-hosted handshake.
`locale`	`string`	—	Localized hints from the engine.
`poseModelProfile`	`'UltraLite' \| 'Lite' \| 'Pro' \| 'Prime' \| 'AdaptiveChoice'`	`'AdaptiveChoice'`	Handshake request profile (server may resolve differently).
`preferredBackend`	`'auto' \| 'webview' \| 'vision'`	`'auto'`	`auto` / `webview` = MoveNet in WebView (Expo Go OK). `vision` = Apple Vision, iOS native only, explicit opt-in.
`onDiagnostic`	`(message: string) => void`	Metro/logcat logger	GL / quality / boot diagnostic lines.

Light-only

Option	Type	Default	Notes
`model`	`'movenet' \| 'movenet-singlepose-lightning' \| 'lightning' \| 'blazepose' \| string`	`'movenet'`	Product Lightning URL. `blazepose` loads CDN pose-detection (lite) in the WebView; same COCO-17 keypoints. Ignored if `modelUrl` is set.
`modelUrl`	`string`	Front MoveNet JSON URL	Explicit TF.js graph-model topology; weight shards are relative neighbors.
`tfjsCdnBase`	`string`	`https://cdn.jsdelivr.net/npm`	Mirror root for TF.js scripts.
`tfjsVersion`	`string`	`'4.22.0'`	CDN version pin.

Offline has no model / modelUrl / CDN options — MoveNet + TF.js are bundled.

// Light
<PoseTrackerProvider
  options={{
    model: 'movenet',
    // modelUrl: 'https://…/model.json',
    // tfjsCdnBase: 'https://cdn.jsdelivr.net/npm',
    // tfjsVersion: '4.22.0',
    features: { angles: true, minGrade: 'B' },
    capturePriority: 'performance',
  }}
/>

usePoseTracker

Must run under PoseTrackerProvider. Pass optional typed callbacks; returns the context value below.

const {
  status,
  mode,
  exercises,
  preload,
  startExercise,
  stopExercise,
  configure,
  quality,
  client,
} = usePoseTracker({
  onKeypoints: (e) => {},
  onCounter: (e) => {},
});

Context fields

Field	Type	Notes
`client`	`PoseTrackerClient`	Escape hatch; stable across renders.
`status`	`'idle' \| 'configuring' \| 'downloading' \| 'warming' \| 'ready' \| 'error'`	Pipeline lifecycle.
`mode`	`'keypoints-only' \| 'full-engine'`	Commercial boundary.
`acceleration`	`'unknown' \| 'gpu' \| 'cpu-fallback' \| 'unavailable'`	WebGL health after warm-up.
`accelerationDiagnostics`	object \| `null`	Full GPU / GL report.
`quality`	`QualityState`	Active capture profile, FPS, floors.
`error`	`ErrorEvent \| null`	Last error (can coexist with `ready` + keypoints-only).
`manifest`	`SdkManifest \| null`	Handshake result.
`exercises`	`ExerciseConfig[]`	Catalog from handshake; empty in keypoints-only. Same as `client.getAvailableExercises()`.

Methods

Method	Signature	Notes
`preload`	`(options?: PreloadOptions) => Promise<void>`	Warm model (+ optional handshake/engine). Default `coldStart: 'basic'` — no camera. Alias: `warmup`. See Preload.
`warmup`	same as `preload`	Alias.
`configure`	`(apiToken?: string) => Promise<boolean>`	Hot (re)config; `true` when full-engine. Does not restart the camera pipeline.
`startExercise`	`(exerciseId: string, options?: StartExerciseOptions) => void`	Catalog id or custom jump. Requires full-engine. Unknown id → `invalid_exercise`. Calling it again while the camera (or `processFrame`) is open switches exercise in the same tracking call. See Several exercises, one call.
`stopExercise`	`() => void`	Ends session; may emit `exercise_summary`.
`warmupExternal`	`() => Promise<void>`	Model only, no camera. Required before external frames. See External frames.
`processFrame`	external frame → `Promise<{ dropped, pose, events }>`	Host camera. One frame in flight. Same exercise session as `startExercise`.
`estimatePose`	`(frame: PoseInputFrame) => Promise<Pose \| null>`	Legacy tensor / vision-camera buffer. Not the external-frames API.
`addEventListener`	`(listener) => () => void`	Typed events.
`addMessageListener`	`(listener) => () => void`	Classic WebView JSON.

StartExerciseOptions

Field	Type	Default	Notes
`difficulty`	`string`	`'medium'`	Optional. Default `'medium'`. Not a WebView query param.
`userHeightCm`	`number`	—	Required for `jump_analysis`.
`devicePitchDeg`	`number`	—	Jump exercises: camera tilt compensation.

startExercise('squat', { difficulty: 'hard' });
startExercise('jump_analysis', { userHeightCm: 178, devicePitchDeg: 5 });
startExercise('air_time_jump');

Several exercises, one call

The SDK counts one tracking call on camera_start, when the camera opens (or on warmupExternal() for external frames). startExercise never counts again. To chain exercises in one call, keep the camera open and call startExercise again:

startExercise('squat');
// …later, same camera still open:
startExercise('plank'); // previous session ends (exercise_summary may fire), placement + counter restart, no new call

Unmounting WebViewPoseView / PoseCamera, stop() then start(), or any new camera open ends the session; the next exercise counts as a new call. stopExercise() alone keeps the camera open, so a later startExercise is still the same call. See What counts as one tracking call.

Common recipes

Keypoints only (no API key):

<PoseTrackerProvider>
  <WebViewPoseView style={{ flex: 1 }} drawSkeleton />
</PoseTrackerProvider>

Exercise + paid streams:

<PoseTrackerProvider
  apiToken="YOUR_API_KEY"
  options={{ features: { angles: true, progression: true, keypoints: true, minGrade: 'B' } }}
>
  {/* startExercise('push_up') once status === 'ready' and mode === 'full-engine' */}
  <WebViewPoseView style={{ flex: 1 }} drawSkeleton />
</PoseTrackerProvider>

Jump analysis:

startExercise('jump_analysis', { userHeightCm: 178, devicePitchDeg: 5 });

WebView equivalents of these recipes: Query parameters.

PoseTrackerClient (escape hatch)

Same methods as the hook, plus: | Method | Notes | |---|---|---| | getStatus() / getMode() / getError() / getManifest() | Introspection. | | getPlanType() | 'free', 'developer', … or null (keyless). | | getFeatures() | Resolved feature flags. | | getAvailableExercises() | Catalog ids for the current session. Empty outside full-engine. | | getAvailableCustomExercises() | Bundle customs (jump_analysis, air_time_jump, …). | | getCurrentExerciseId() | Active session id or null. | | getQualityState() / getColdStartMode() | Quality + last preload cold-start. | | fetchSkeleton(uuid) | GET /api/sdk/skeleton → SkeletonDefinition. | | dispose() | Tear down backend, session, listeners. |

const off = client.addEventListener((event) => { /* … */ });
const offMsg = client.addMessageListener((msg) => { /* classic */ });

Injectables (backend, engineLoader, fileStore, usageTracker) exist for tests / advanced hosts — prefer TypeScript types in the package for those.

For LLMs: SDK params live on PoseTrackerProvider / options / startExercise, not URL query strings. Keypoints need no apiToken. Overlay/timer/reference/userExercise are WebView-only. Host-owned camera: warmupExternal + processFrame — https://docs.posetracker.com/external-frames. Repeated startExercise while the camera stays open = same billed call; closing the camera or stop()/start() = new call. https://docs.posetracker.com/reference/provider-client

Start here

WebView integration

SDK integration

Reference

Advanced (SDK)

AI & agents

PoseTrackerProvider

Options

Shared (offline + light)

Light-only

usePoseTracker

Context fields

Methods

StartExerciseOptions

Several exercises, one call

Common recipes

PoseTrackerClient (escape hatch)

​PoseTrackerProvider

​Options

​Shared (offline + light)

​Light-only

​usePoseTracker

​Context fields

​Methods

​StartExerciseOptions

​Several exercises, one call

​Common recipes

​PoseTrackerClient (escape hatch)

PoseTrackerProvider

Options

Shared (offline + light)

Light-only

usePoseTracker

Context fields

Methods

StartExerciseOptions

Several exercises, one call

Common recipes

PoseTrackerClient (escape hatch)