©️REFERENCE

🆕 Reference Movement Tracking with PoseTracker

PoseTracker supports custom reference-based tracking with the reference query parameter.

A reference movement is a short movement created in the PoseTracker dashboard and stored as a reusable reference. Once created, it can be used in both:

• real-time tracking

• uploaded video analysis

This allows developers to compare a user’s movement against a custom movement instead of using a built-in exercise.

---

1. Create a Reference Movement

Before using the reference parameter, you first need to create a reference movement in the PoseTracker dashboard.

👉 Create and manage your references here:

https://app.posetracker.com/reference-movements/list

In the dashboard, you can:

• upload a short reference video

• trim one clean repetition

• generate a reference movement

• retrieve its UUID

This UUID is the value used in the reference query parameter.

Example:

reference=7f3c5a0d-9d84-4d15-9c5a-cc1e3a4b1baf

---

2. Use the reference Parameter

Use reference when you want PoseTracker to track a custom movement.

Real-time tracking

https://app.posetracker.com/pose_tracker/tracking?token=YOUR_TOKEN&reference=REFERENCE_UUID

Upload tracking

https://app.posetracker.com/pose_tracker/upload_tracking?token=YOUR_TOKEN&source=video&reference=REFERENCE_UUID

⚠️ reference and exercise cannot be used together.

Use:

• exercise=... for built-in PoseTracker exercises

• reference=... for custom dashboard-created movements

---

3. How It Works

When reference is provided:

1. PoseTracker loads the reference movement

2. PoseTracker compares the live or uploaded movement to that reference

3. PoseTracker detects repetitions

4. PoseTracker returns similarity scores for each repetition

This works with the same integration flow as the standard tracking endpoints.

---

4. Integration Flow

Create reference in dashboard
        ↓
Get reference UUID
        ↓
Pass reference=REFERENCE_UUID in the tracking URL
        ↓
Embed PoseTracker in iframe / WebView
        ↓
Listen to postMessage events
        ↓
Read repetition count and reference scores

---

5. Returned Data

When using reference, PoseTracker sends the usual tracking events, and counter events may include a reference_score object.

Example:

{
  "type": "counter",
  "current_count": 2,
  "reference_score": {
    "overallScore": 0.84,
    "poseScore": 0.79,
    "timingScore": 0.91,
    "movementScore": 0.85,
    "grade": "B"
  }
}

reference_score fields

Field	Type	Description
overallScore	number	Global similarity score
poseScore	number	Pose similarity
timingScore	number	Timing similarity
movementScore	number	Movement amplitude similarity
grade	string	Global letter grade

All numeric scores are returned between 0 and 1.

---

6. Upload Video Summary

When using reference with uploaded videos, PoseTracker may also return a summary event at the end of the analysis.

Example:

{
  "type": "exercise_summary",
  "counter": 12,
  "avg_similarity": 0.76,
  "avg_rep_score": 0.81,
  "total_frames_compared": 530
}

Summary fields

Field	Type	Description
counter	number	Total repetitions detected
avg_similarity	number | null	Average similarity across frames
avg_rep_score	number | null	Average repetition score
total_frames_compared	number	Number of analyzed frames

---

7. Simple Implementation Example

Embed the tracking URL

<iframe
  src="https://app.posetracker.com/pose_tracker/tracking?token=YOUR_TOKEN&reference=REFERENCE_UUID"
  width="400"
  height="700">
</iframe>

Listen to results

window.addEventListener("message", (event) => {
  const data = event.data

  if (data.type === "counter") {
    console.log("Reps:", data.current_count)

    if (data.reference_score) {
      console.log("Overall:", data.reference_score.overallScore)
      console.log("Pose:", data.reference_score.poseScore)
      console.log("Timing:", data.reference_score.timingScore)
      console.log("Movement:", data.reference_score.movementScore)
      console.log("Grade:", data.reference_score.grade)
    }
  }

  if (data.type === "exercise_summary") {
    console.log("Total reps:", data.counter)
    console.log("Average rep score:", data.avg_rep_score)
  }
})

---

8. When to Use reference

Use reference when:

• you want to track a custom movement not available as a built-in exercise

• you want to compare users against a movement recorded in your dashboard

• you want per-repetition similarity scoring

Use exercise when:

• you want to use PoseTracker’s built-in movement logic

• you do not need a custom movement reference

---

9. Best Practices

For best results:

• create references from a short video containing one clean repetition

• keep the movement clearly visible

• ask end users to perform the movement from a similar camera angle

---

10. Related Links

• Reference dashboard https://app.posetracker.com/reference-movements/list

• Real-time tracking docs Use PoseTracker on real-time camera / webcam

• Upload tracking docs Use PoseTracker on uploaded files