PunchPlay

End users

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

PunchPlay support is experimental. Functionality may change as the integration improves.

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.

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:

"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.