ℹ️Tracking Endpoint Message to handle

Our endpoints emits structured messages to your host app (iframe/WebView). Use these messages to drive UI and logic.

The same message structure is used across:

• real-time tracking

• upload tracking (video/image)

---

Form score and grades (V3)

Each completed repetition is scored 0–100 and mapped to a grade:

• A: score ≥ 90

• B: score ≥ 80

• C: score ≥ 70

• D: score ≥ 60

• F: score < 60

The grade reflects execution quality (depth, angles, tempo, stability, and form).

Where the grade is sent

In V3, the authoritative score/grade for a counted rep is sent inside the counter event (counter.form_score).

Do not rely on a separate form_score event to get the grade of the rep that was just counted.

---

Message types (V3)

Core lifecycle

• initialization

• posture

• counter

• error

Optional outputs (plan-gated)

• keypoints

• angles

• progression

• recommendations

Jump-specific (custom exercises)

• jump_calibration, jump_started, jump_discarded, jump_height, jump_summary

---

counter (updated V3 payload)

The counter message is sent each time the rep count changes. For upload video, a final counter is emitted once processing ends (final: true).

Fields

• type: "counter"

• current_count: number — total counted reps so far

• final: boolean (optional) — true when processing has finished (upload video)

• form_score: object (optional) — score for the rep that was just counted (or current state when final:true)

  • score: number (0–100)

  • avg_score: number (running average)

  • grade: "A" | "B" | "C" | "D" | "F"

reference_score (when using reference)

When using reference=REFERENCE_UUID, the counter event may include a reference_score object.

This object contains similarity metrics between the user’s movement and the selected reference movement.

• overallScore (number, 0..1) — overall similarity score

• poseScore (number, 0..1) — pose similarity

• timingScore (number, 0..1) — timing similarity

• movementScore (number, 0..1) — movement amplitude similarity

• grade (string) — letter grade for the repetition

Example:

{
  "type": "counter",
  "current_count": 3,
  "reference_score": {
    "overallScore": 0.82,
    "poseScore": 0.78,
    "timingScore": 0.9,
    "movementScore": 0.84,
    "grade": "B"
  }
}

Use overallScore if you want a single global score. Use the sub-scores if you want custom logic or custom UI feedback.

Concrete examples

{"type":"counter","current_count":1,"form_score":{"score":88,"avg_score":88,"grade":"B"}}

{"type":"counter","current_count":5,"form_score":{"score":72,"avg_score":81,"grade":"C"}}

{"type":"counter","current_count":10,"final":true,"form_score":{"score":90,"avg_score":84,"grade":"A"}}

---

Standalone form_score event (if you see it)

If a form_score-only message exists in other contexts (e.g. live feedback while a rep is in progress), it must not be treated as the authoritative grade for a counted rep.

Single source of truth for counted reps: counter.form_score.

---

Tips for developers: minGrade vs client-side filtering

Server-side filtering (recommended): minGrade

If you set minGrade=B, PoseTracker only increments current_count for reps graded A or B. This means:

• current_count becomes your “valid reps” count

• each counter event already corresponds to a valid rep

Client-side filtering (if you don’t want server filtering)

If you do not set minGrade, you receive every counted rep with its grade inside counter.form_score. You can maintain your own strict count:

Pseudo-logic:

• if payload.form_score.grade is in ["A","B"], increment your local strict counter

---

Errors

(keep your existing error section; ensure it includes plan restriction errors and invalid_exercise)