# 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": 1,
    "reference_score": {
        "overallScore": 0.91,
        "nccScore": 0.92,
        "dtwScore": 0.77,
        "timingScore": 0.99,
        "grade": "A"
    }
}
```

#### `reference_score` fields

| Field          | Name          | Description                                                                                                                                                                                           |
| -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overallScore` | Overall Score | Combined metric that blends NCC shape similarity with a DTW warping-path-length penalty. Represents the holistic quality of the repetition.                                                           |
| `nccScore`     | NCC Score     | Normalized Cross-Correlation computed on DTW-aligned joint-angle trajectories. Measures how closely the shape of the user's movement matches the reference movement, regardless of speed differences. |
| `dtwScore`     | DTW Score     | Dynamic Time Warping alignment quality. Reflects the angular accuracy per aligned step — lower average warping cost yields a higher score.                                                            |
| `timingScore`  | Timing Score  | How close the live repetition duration matches the reference duration. A perfect 1.0 means the user performed the movement in the exact same time as the reference.                                   |
| `grade`        | Grade         | Letter grade (A / B / C / D / F) derived from `overallScore`.                                                                                                                                         |

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": 1,
    "avg_similarity": 0.92,
    "avg_rep_score": 0.91,
    "total_frames_compared": 161,
    "history": [
        {
            "rep": 1,
            "reference_score": {
                "overallScore": 0.91,
                "nccScore": 0.92,
                "dtwScore": 0.77,
                "timingScore": 0.99,
                "grade": "A"
            }
        }
    ]
}
```

### 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 [PoseTracker integration](/posetracker-api/posetracker-integration.md#id-1-real-time-tracking-camera-webcam)
* Upload tracking docs [Use PoseTracker on uploaded files](/posetracker-api/use-posetracker-on-uploaded-files/upload-tracking-endpoint-video-and-image.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://posetracker.gitbook.io/posetracker-api/use-posetracker-on-real-time-camera-webcam/query-params-details/reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.