> 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/navigation/playback.md).
# Playback
Playback Progress shows unfinished movies and episodes from connected providers.
It is a management page for resume records.
It does not sync playback positions continuously in the background.
{% hint style="info" %}
Playback is available in **v0.9.23 and later**.
{% endhint %}
### What Playback Progress shows
Each card can show:
* movie or episode details
* watched percentage
* estimated time remaining
* when playback was last paused
* matching provider profiles
* supported actions
When **All Providers** is selected, CrossWatch tries to combine matching records into one card.
Provider badges show every matching profile.
Actions on a combined card apply to every eligible provider record in that card.
### Supported providers
Playback currently supports:
* **Trakt** — movies and TV episodes
* **SIMKL** — movies, TV episodes, and anime episodes
* **MDBList** — movies and TV episodes
* **PublicMetaDB** — movies and TV episodes
* **Plex** — movies and TV episodes
* **Emby** — movies and TV episodes
* **Jellyfin** — movies and TV episodes
A provider profile must already be connected.
All supported providers can read playback records.
They also support remove, mark watched, edit progress, and bulk actions when configured.
**Edit Progress** can be unavailable for some **PublicMetaDB**, **Plex**, **Emby**, or **Jellyfin** records.
That happens when duration is missing.
### Open Playback
Open **Playback** from the main navigation.
Playback loads all enabled and compatible provider profiles.
If none are available, CrossWatch shows a message.
Use **Refresh** to request current provider data.
### Filters and sorting
The toolbar includes:
* **Search**
* **Provider**
* **Type**
* **Progress**
* **Age**
* **Rating**
* **Sort**
**Search** can match:
* titles and episode titles
* provider and profile names
* source app or device names
* season and episode text like `S02E07`
**Type** supports movies, TV episodes, and anime episodes.
**Age** supports today, last 7 days, last 30 days, and older than 30 days.
**Sort** supports:
* last updated
* highest or lowest progress
* remaining time
* highest rating
* title
* provider
Selecting a specific provider disables cross-provider combining for that result set.
Each provider record is then shown separately.
### Card actions
#### Edit Progress
**Edit Progress** changes the resume position.
It applies to every eligible provider record on the card.
Accepted values are `2` through `79` percent.
Values of `80` percent or higher are rejected.
Use **Mark as Watched** for completed items.
The **Edit** button is hidden when the provider cannot update the record.
Media server and **PublicMetaDB** records need a known duration.
CrossWatch uses that duration to convert percent into a playback position.
#### Mark as Watched
**Mark as Watched** adds the item to provider watch history.
After success, CrossWatch also tries to remove the unfinished playback record.
**Plex** handles resume through watched state.
CrossWatch does not send a separate cleanup request for Plex.
#### Remove Progress
**Remove Progress** removes the unfinished playback record.
It does not add a watched history entry.
For **Plex**, this uses the unplayed or unwatched action.
That can also affect the Plex watched state.
### Bulk actions
Select a card by clicking it.
Keyboard selection also works with **Enter** or **Space**.
After selection, the bulk bar can:
* select visible
* select all filtered results
* clear selection
* edit progress
* mark as watched
* remove progress
Bulk actions apply only to eligible provider records.
Unsupported records are counted separately in the result message.
**Select All Filtered Results** currently loads at most `250` results.
### Playback settings
Open the settings button on the **Playback** page.
#### Provider profiles
Every known supported profile is listed.
Checked profiles are included in Playback.
Unchecked profiles are excluded only from Playback.
They stay connected for other CrossWatch features.
Profiles that are not configured cannot be enabled here.
Profiles that cannot read playback records also stay disabled.
#### Slow provider timeout
**Slow provider timeout** controls how long Playback waits during refresh.
Valid values are `3` through `60` seconds.
The default is `12` seconds.
A timed-out profile does not block other profiles.
Playback can still show partial results.
### Refreshing and partial results
CrossWatch requests enabled profiles in parallel.
Up to six provider requests run at once.
Playback uses a short in-memory cache.
If provider activity did not change, cached data can be reused.
**Refresh** forces a new provider request.
It bypasses normal cache reuse.
A failure from one provider does not discard successful results from others.
Provider errors appear above the result cards.
How CrossWatch combines records
When **All Providers** is selected, CrossWatch groups records by canonical media key when possible.
When no canonical key exists, CrossWatch falls back to:
* movies — title, year, and rounded progress
* episodes — series title, season, episode, and rounded progress
Records with weak identifiers can stay separate.
Records with very different progress can also stay separate.
The newest record in a group supplies the main card values.
CrossWatch still keeps the underlying provider records for actions.
### Troubleshooting
#### No playback records appear
Confirm at least one supported profile is:
* connected
* configured
* readable
* included in Playback settings
Use **Refresh** to bypass cached data.
Check the error area above the cards.
#### A provider is missing from the filter
The provider filter shows only profiles that are:
* configured
* readable
* included
Open Playback settings and confirm the profile is checked.
#### Edit Progress is missing
The provider or record does not support progress updates.
For **PublicMetaDB**, **Plex**, **Emby**, and **Jellyfin**, the record also needs a valid duration.
#### Matching items appear as separate cards
Providers might not supply a common media identifier.
Fallback matching also uses rounded progress.
Records at different positions can stay separate.
#### Refresh is slow
Reduce **Slow provider timeout** when one provider delays the page.
Lower values return other results sooner.
They also skip slow providers more often.
#### Remove Progress changed a Plex watched state
This is expected with Plex.
Plex resume removal uses an unplayed or unwatched operation.
That can affect watched state.
Advanced configuration
Playback settings are stored in `config.json` under `playback_progress`.
The settings dialog creates this object automatically.
If the object is missing, CrossWatch uses defaults.
Defaults include all compatible profiles and a `12` second timeout.
#### Example
```json
{
"playback_progress": {
"provider_timeout_seconds": 12,
"disabled_profiles": [
"plex:default",
"trakt:secondary"
]
}
}
```
Add this object to the root of `config.json`.
#### `provider_timeout_seconds`
* Type: number
* Default: `12`
* Range: `3` through `60`
Values below `3` are raised to `3`.
Values above `60` are reduced to `60`.
Missing or invalid values use `12`.
#### `disabled_profiles`
* Type: array of strings
* Default: empty array
Each value uses this format:
```
provider:instance_id
```
Examples:
```json
[
"trakt:default",
"plex:kids",
"simkl:secondary"
]
```
Supported provider IDs are:
* `trakt`
* `simkl`
* `mdblist`
* `publicmetadb`
* `plex`
* `emby`
* `jellyfin`
The default profile always uses `default`.
Named profiles use the key under the provider `instances` object.
#### Configuration file location
In the container image, CrossWatch usually uses:
```
/config/config.json
```
When `CONFIG_BASE` is set, CrossWatch uses:
```
CONFIG_BASE/config.json
```
Outside containers, and without `CONFIG_BASE`, CrossWatch uses `config.json` in the application directory.
#### Processing details
* only configured, readable, included profiles are queried
* provider requests run concurrently
* slow profiles are skipped after timeout
* filters run after normalization
* combining runs only when no provider filter is active
* sorting runs after filtering and combining
* API page size supports `1` through `250`
* the interface uses `30` cards per page
* action success invalidates affected provider cache
* saving Playback settings clears the full Playback cache
Playback does not create a background sync schedule.
It reads provider state when loaded or refreshed.
It writes changes only when you request an action.
Local API
Playback uses the local CrossWatch API.
#### Read endpoints
```
GET /api/playback_progress/providers
GET /api/playback_progress/settings
GET /api/playback_progress/items
```
The items endpoint accepts:
* `provider`
* `instance_id`
* `media_type`
* `progress_min`
* `progress_max`
* `age`
* `rating_min`
* `search`
* `sort`
* `page`
* `page_size`
* `force_refresh`
Supported sort values are:
* `last_updated`
* `progress_high`
* `progress_low`
* `remaining_time`
* `rating_high`
* `title`
* `provider`
#### Write endpoints
```
POST /api/playback_progress/settings
POST /api/playback_progress/actions/remove
POST /api/playback_progress/actions/mark_watched
POST /api/playback_progress/actions/update_progress
POST /api/playback_progress/actions/bulk
```
The update action accepts only `2` through `79` percent.
Bulk action names are:
* `remove_progress`
* `mark_watched`
* `update_progress`
### Related
* Resume syncing between servers: [Progress](/crosswatch/configure-pairs/features/progress.md)
* Real-time playback handling: [Scrobble](/crosswatch/scrobble.md)
* UI overview: [Navigation](/crosswatch/navigation.md)
---
# 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:
```
GET https://wiki.crosswatch.app/crosswatch/navigation/playback.md?ask=
```
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.