# REFERENCE

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

* Demo video : <https://youtu.be/uYJkuKqESBE>
* Reference dashboard : <https://app.posetracker.com/reference-movements/list>
* Real-time tracking docs [#id-1-real-time-tracking-camera-webcam](https://posetracker.gitbook.io/posetracker-api/posetracker-integration#id-1-real-time-tracking-camera-webcam "mention")
* Upload tracking docs [use-posetracker-on-uploaded-files](https://posetracker.gitbook.io/posetracker-api/use-posetracker-on-uploaded-files "mention")