> 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/connections/trackers/punchplay.md).

# PunchPlay

{% tabs %}
{% tab title="End users" %}

<figure><img src="/files/pohvsmxmIxXK4EmiseOx" alt=""><figcaption></figcaption></figure>

PunchPlay is a media tracker for movies and TV shows. CrossWatch synchronizes your activity with supported providers.

{% hint style="warning" %}
**PunchPlay support is experimental.** Functionality may change as the integration improves.
{% endhint %}

### What it supports

| Feature   | Support                              |
| --------- | ------------------------------------ |
| Watchlist | Movies and shows                     |
| Ratings   | Movies, shows, seasons, and episodes |
| History   | Movies and episodes                  |
| Progress  | Movies and episodes                  |
| Watcher   | Yes                                  |

PunchPlay can be a source or target in synchronization pairs.

It can also receive playback activity from **Watcher**.

### Connect PunchPlay

PunchPlay uses device-code login. You do not need an API application or API key.

1. Open **Settings** → **Authentication**.
2. Open **PunchPlay**.
3. Click **Connect PunchPlay**.
4. CrossWatch displays a code and opens PunchPlay’s linking page.
5. Enter the code and approve CrossWatch.
6. Return to CrossWatch.

PunchPlay shows **Connected** after approval.

CrossWatch stores the required access and refreshes tokens automatically.

### Using PunchPlay

After connecting, PunchPlay is available when creating synchronization pairs.

Examples include:

`Plex → PunchPlay`

`PunchPlay → Trakt`

`SIMKL → PunchPlay`

Enable features supported by both providers.

Select PunchPlay as a **Watcher** destination for real-time playback updates.

### Multiple profiles

PunchPlay supports CrossWatch Profiles.

Each profile uses separate authentication. Choose profiles independently in pairs and Watcher routes.

Keep the default profile when using one PunchPlay account.

### Troubleshooting

* Reconnect under **Settings** → **Authentication** → **PunchPlay** if the connection fails.
* Configure metadata when sync items cannot match. PunchPlay works best with provider IDs.
* Report reproducible integration issues through the CrossWatch GitHub issue tracker.
  {% endtab %}

{% tab title="Power users" %}

## Power users

PunchPlay is an experimental CrossWatch sync provider and Watcher destination.

Current integration version: `0.1`.

### Authentication

PunchPlay uses the OAuth device-code flow.

CrossWatch provides the PunchPlay application ID. Users do not configure client credentials.

The flow requests these scopes:

`profile:read`

`history:read`

`history:write`

`lists:read`

`lists:write`

`ratings:read`

`ratings:write`

`collection:read`

`collection:write`

`playback:read`

`playback:write`

`events:read`

CrossWatch stores and refreshes access tokens automatically.

Do not manually edit these tokens.

### Provider capabilities

#### Watchlist

Read and write are supported for:

`movies`

`shows`

Season and episode watchlist entries are unsupported.

#### Ratings

Read, write, and remove are supported for:

`movies`

`shows`

`seasons`

`episodes`

PunchPlay uses a **1–10** rating scale. CrossWatch rounds writes to whole numbers.

#### History

Read, write, and remove are supported for:

`movies`

`episodes`

History writes require a watched timestamp.

#### Progress

Read, write, and remove are supported for:

`movies`

`episodes`

PunchPlay stores playback state separately from watched history. CrossWatch syncs unfinished playback when supported.

### IDs

PunchPlay writes use available identifiers:

`TMDb`

`IMDb`

`TVDb`

`MAL`

PunchPlay returns TMDb as its primary CrossWatch identifier.

Progress accepts `TMDb`, `IMDb`, and `TVDb`.

Use good metadata coverage when pairing PunchPlay with another provider.

### Watcher

PunchPlay is available as a Watcher destination.

CrossWatch sends these playback events:

`start`

`pause`

`resume`

`progress`

`stop`

CrossWatch maintains a playback session ID for each session.

Movies send available TMDb, IMDb, or TVDb IDs.

Episodes also send season and episode numbers with available show IDs.

PunchPlay can mark an item watched when playback exceeds the configured threshold.

### Rate limiting

CrossWatch uses conservative PunchPlay rate limits. It reacts to API rate-limit responses.

Default configuration:

```json
"punchplay": {
  "timeout": 20.0,
  "max_retries": 3,
  "history_per_page": 100,
  "history_max_pages": 5000,
  "rate_limit": {
    "get_per_sec": 2.0,
    "post_per_sec": 0.5,
    "bulk_per_min": 30,
    "playback_per_5min": 120,
    "sync_read_per_min": 120
  }
}
```

Most installations should keep these values unchanged.

PunchPlay bulk operations use batches of up to **100 items**. CrossWatch batches requests automatically.

### Profiles

PunchPlay supports multiple CrossWatch provider profiles.

Each profile stores separate authentication data:

`access_token`

`refresh_token`

`expires_at`

`refresh_expires_at`

`username`

`user_id`

`device_id`

Pairs select a source or target PunchPlay profile. Watcher routes select a destination profile independently.

### Experimental status

The PunchPlay adapter is marked **experimental**.

API behavior and supported capabilities may change.

Use the UI for normal installations. Do not edit PunchPlay credentials in `config.json`.
{% endtab %}
{% endtabs %}


---

# 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/connections/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.