> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/punchplay.md).

# PunchPlay

PunchPlay can synchronize with CrossWatch as a source or target. It supports one-way and two-way pairs.

{% hint style="warning" %}
**PunchPlay support is experimental.** The adapter is new and may change as it is tested and improved.
{% endhint %}

### Supported features

| Feature   | Supported media                  | Read | Write |
| --------- | -------------------------------- | ---- | ----- |
| Watchlist | Movies, shows                    | Yes  | Yes   |
| Ratings   | Movies, shows, seasons, episodes | Yes  | Yes   |
| History   | Movies, episodes                 | Yes  | Yes   |
| Progress  | Movies, episodes                 | Yes  | Yes   |

PunchPlay does not support playlist synchronization.

### Using PunchPlay in a pair

First, connect PunchPlay under **Settings** → **Authentication**.

You can then select PunchPlay when creating or editing a synchronization pair.

Examples:

`Plex → PunchPlay`

`PunchPlay → Trakt`

`SIMKL → PunchPlay`

`PunchPlay ↔ CrossWatch Tracker`

CrossWatch only shows features supported by both providers.

Start a new pair with **one-way synchronization** and one feature. Enable more features or two-way synchronization after confirming the results.

### Watchlist

PunchPlay Watchlist synchronization supports:

`Movies`

`Shows`

CrossWatch can add and remove items from the PunchPlay watchlist.

Seasons and episodes are not supported as Watchlist items.

### Ratings

PunchPlay Ratings synchronization supports:

`Movies`

`Shows`

`Seasons`

`Episodes`

PunchPlay uses ratings from **1 to 10**.

Ratings written to PunchPlay are stored as whole numbers. CrossWatch rounds ratings when required.

Ratings can also be removed when removal is enabled for the pair.

### History

PunchPlay History synchronization supports:

`Movies`

`Episodes`

CrossWatch preserves the watched timestamp when writing history to PunchPlay.

Shows and seasons are not written as standalone History entries.

History removals are supported when removal is enabled for the pair.

### Progress

PunchPlay supports Playback Progress synchronization for:

`Movies`

`Episodes`

This synchronizes unfinished playback positions with another provider that supports Progress.

Examples:

`Plex ↔ PunchPlay`

`Jellyfin ↔ PunchPlay`

`Emby ↔ PunchPlay`

Progress is separate from History. An unfinished position does not automatically mark an item watched.

### Matching and IDs

CrossWatch uses provider IDs whenever possible when synchronizing with PunchPlay.

PunchPlay supports these IDs for most operations:

`TMDb`

`IMDb`

`TVDb`

`MAL`

TMDb is the primary ID PunchPlay returns to CrossWatch.

Playback Progress uses TMDb, IMDb, or TVDb IDs.

For the best matching results, configure **TMDb Metadata** in CrossWatch.

### Deletes

PunchPlay detects and applies removals for Watchlist, Ratings, History, and Progress.

CrossWatch safety controls still apply.

CrossWatch only removes data when the feature and pair configuration allow it.

For a new PunchPlay pair, leave removals disabled until after a clean synchronization run.

### Profiles

PunchPlay supports CrossWatch Profiles.

When multiple PunchPlay accounts are connected, select the correct profile for each pair side.

Each profile is handled independently.

### Rate limits

CrossWatch automatically handles PunchPlay API pacing, batching, and retries.

Writes use batches where supported. CrossWatch slows requests when PunchPlay reports API limits.

Most users do not need to change PunchPlay rate-limit settings.

### Experimental status

The PunchPlay sync adapter is version `0.1` and remains experimental.

When reporting a reproducible sync issue, include the feature, pair direction, and relevant Events output.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/punchplay.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.