cricket-pose-tracker

Browser pose-tracking toolkit extracted from Cricket Shadow Coach. Wraps MediaPipe Pose with a simple detector API and ships the supporting math you need for real-time sport motion analysis: One Euro landmark smoothing, joint-angle calculation, and camera-framing hints.

Built for cricket coaching — works for any sport or movement app that tracks a single person.

Install

npm install cricket-pose-tracker

Zero npm dependencies. MediaPipe Pose (~5 MB of model files) is loaded at runtime from the jsDelivr CDN, so the detector requires a browser environment and network access on first use. The math utilities (PoseSmoother, calculateAngle, getFramingHint, …) are pure functions and run anywhere, including Node.

Quick start

import {
  createPoseDetector,
  PoseSmoother,
  calculateAngle,
  getFramingHint,
} from 'cricket-pose-tracker';

const video = document.querySelector('video');
const smoother = new PoseSmoother();

const detector = createPoseDetector(video, (landmarks, worldLandmarks) => {
  if (!landmarks) return;

  // Debounce-worthy framing feedback ('' = well framed)
  const hint = getFramingHint(landmarks);

  // Smooth jittery landmarks before doing math on them
  const smoothed = smoother.smooth(worldLandmarks ?? landmarks, performance.now());

  // Elbow angle: shoulder (11) – elbow (13) – wrist (15)
  const leftElbow = calculateAngle(smoothed[11], smoothed[13], smoothed[15]);
  console.log({ hint, leftElbow });
});

await detector.start();
// later: detector.stop() or detector.destroy()

API

createPoseDetector(videoElement, onPoseLandmarks, options?)

Creates a detector that pumps video frames through MediaPipe Pose on requestAnimationFrame.

• onPoseLandmarks(landmarks, worldLandmarks) is called every processed frame with the 33 normalized 2D image landmarks (for drawing) and metric 3D world landmarks (for angle math). World landmarks may be null on some devices — fall back to 2D.
• options overrides MediaPipe Pose settings (modelComplexity, minDetectionConfidence, …). By default modelComplexity is 0 on mobile and 1 on desktop. The Pose instance is shared, so options apply on first initialization only.
• Returns { start, stop, destroy }.

new PoseSmoother(minCutoff = 1.0, beta = 0.007)

One Euro filter (Casiez et al., CHI 2012) over a full 33-landmark stream — one filter per landmark per axis. Heavy smoothing at rest, minimal lag during fast motion. Automatically resets after a >500 ms gap (tracking loss).

• smooth(landmarks, timestampMs) → new array of smoothed {x, y, z, visibility} objects. Visibility passes through unfiltered.
• reset() clears filter state.

OneEuroFilter is also exported for smoothing single scalar signals.

calculateAngle(a, b, c)

Angle at vertex b formed by 3D points a–b–c, in rounded degrees (0–180). Returns 0 for missing/degenerate input.

calculateSpineTilt(landmarks)

Torso tilt from vertical in degrees, using mid-shoulder and mid-hip of the 33-landmark array.

getFramingHint(landmarks)

Pre-drill camera framing check. Returns a human-readable hint ('Move closer to the camera', 'Step back — make sure your whole body is in frame', …) or '' when the subject is well framed. Pair with the exported FRAMING_HINT_HOLD_MS (800 ms) to debounce hints so they don't flicker.

Landmark indices

Landmarks follow the MediaPipe Pose 33-point topology: 11/12 shoulders, 13/14 elbows, 15/16 wrists, 23/24 hips, 25/26 knees, 27/28 ankles.

License

MIT © Bilal Hasan