Playlists
Configure playlist endpoints, rulesets, and mappings between supported providers.
Use Playlists to connect provider playlists and collections through explicit mappings.
Create and synchronize named playlists between supported CrossWatch providers.
Playlists differ from Watchlist. Watchlist sync manages a provider's standard plan-to-watch list.
Use Playlists for named lists you choose, such as Plex playlists or Trakt lists.
Open Main Dashboard → Playlists.
Start with one source, one destination, and the Direct sync ruleset.
Before you start
Connect at least one compatible provider in Connections.
Plex, Trakt, MDBList, Jellyfin, Emby, PublicMetaDB, SIMKL, and CrossWatch support playlists when configured.
Available actions depend on each provider and playlist. A playlist may be read-only.
Some playlists can be created, renamed, deleted, reordered, or edited.
SIMKL uses built-in status buckets as playlist endpoints. SIMKL Custom Lists are unsupported.
Changing an endpoint can move or remove items from your SIMKL library.
How Playlists is organized
Playlist endpoints
An endpoint connects CrossWatch to one playlist on one provider profile.
It records the provider, profile, and selected provider playlist.
The endpoint list shows its name, playlist type, status, last refresh, and actions.
Treat an endpoint as a reusable reference to a provider playlist.
Mappings
A mapping connects one source endpoint to a destination endpoint.
It defines how playlist items move between those endpoints.
The mapping list shows its source, destination, ruleset, sync pair, status, and latest result.
Activity overview
Activity overview shows recent playlist runs, their changes, and their status.
Select View all activity for more history.
Create an endpoint
Select New endpoint.
Choose the provider and profile.
Select the provider playlist.
Change the generated endpoint name if needed.
Save the endpoint.
Use the search field when a provider has many playlists.
The playlist picker may also offer create, rename, or delete actions.
Those actions change the real provider playlist.
Create a mapping
Select New mapping.
Choose the source endpoint.
Choose a different destination endpoint.
Select a ruleset.
Save the mapping.
CrossWatch associates the mapping with a compatible sync pair.
Choose a ruleset
Use Direct sync for most setups. It synchronizes one source with one destination.
Other presets support source mirroring, large-list splitting, playlist merging, or limited account sharing.
Choose Custom only when you need detailed ruleset settings.
Run and review a sync
Use the mapping's sync action to run that mapping.
CrossWatch blocks conflicting playlist runs while synchronization is active.
Check the mapping result and Activity overview after every run.
A successful run can include unresolved items. CrossWatch could not safely match or write them.
Refresh or edit an endpoint
Refresh reloads provider metadata and updates the endpoint status.
It does not run the playlist mapping.
Refresh an endpoint after renaming, changing, or recreating its provider playlist.
Edit an endpoint to change its name or selected provider playlist.
Delete safely
Check mappings before deleting an endpoint. Mappings can use it as a source or destination.
Deleting an endpoint removes only its CrossWatch reference.
Deleting a provider playlist removes the real playlist from that provider.
Deleting a mapping removes its configuration. It does not delete either provider playlist.
Membership behavior
Add only
Adds missing source items to the destination.
It does not remove destination items.
Use it when you also manage destination items manually.
Managed only
Adds missing source items and removes items CrossWatch previously managed.
It leaves destination-only items unchanged.
This is the normal Direct sync behavior.
Mirror
Makes destination membership match the source.
It can remove destination items absent from the source.
Use Mirror only when the source fully controls the destination.
Playlist order
Use Preserve to request the source order on the destination.
If reordering is unsupported, CrossWatch reports a warning.
Smart and special lists
Smart, discovery, virtual, built-in, and watchlist resources can have limited capabilities.
CrossWatch only enables actions that the provider and playlist support.
Recommended first setup
Create one source endpoint.
Create one destination endpoint.
Create one mapping with Direct sync.
Run the mapping manually.
Review the result and activity.
Use Mirror or advanced rulesets only after this setup works as expected.
Troubleshooting
Provider is unavailable
Confirm the provider is configured in Connections and supports playlists.
Playlist is missing
Refresh the picker and confirm the selected provider profile.
Some list types are not available as playlist resources.
Rename or delete is unavailable
The provider or selected playlist does not support that operation.
Mapping does not run
Confirm both endpoints exist and match the associated sync pair.
Also check whether another synchronization is active.
Items are unresolved
Unresolved items usually need better matching data.
Use stable external IDs where possible. Check Analyzer when failures persist.
Technical reference
This reference covers playlist resources, endpoints, mappings, rulesets, pairs, and runtime state.
Open Main Dashboard → Playlists to manage them through the UI.
Mental model
Playlist synchronization uses four related objects.
Provider resource
A provider resource is a playlist-like object returned by a provider adapter.
CrossWatch also derives flags such as smart, writable, discovery, and endpoint_type.
Endpoint
An endpoint references one provider resource.
instance identifies the provider profile shown as Profile in the UI.
Mapping
A mapping connects one source endpoint to one or more target endpoints.
The UI selects one destination. Internally, target_endpoints remains a list.
Aggregate and partition rulesets can use several target endpoints.
Ruleset
A ruleset controls direction, membership, ordering, aggregation, partitioning, capacities, and assignment.
Built-in rulesets are runtime-managed. They cannot be edited or deleted.
Provider contract and protection
Playlist-capable providers implement these core operations:
They can also expose rename_playlist and delete_playlist.
Capability metadata controls available UI actions.
Plex, Trakt, MDBList, Jellyfin, Emby, PublicMetaDB, SIMKL, and CrossWatch support playlists when configured.
Protected resources cannot be renamed or deleted. These include smart, discovery, virtual, built-in, and watchlist resources.
A manageable resource also needs a valid provider resource ID.
Plex distinguishes playlists, collections, and watchlist-like resources. Only regular playlists support ordering.
SIMKL behavior
SIMKL Custom Lists are unsupported.
SIMKL endpoints represent built-in status buckets. Writes can change an item's library status.
Do not treat SIMKL endpoints as independent custom playlists.
Endpoint lifecycle
Endpoint creation first discovers provider resources. It then stores the selected resource as an endpoint.
The picker can create, rename, or delete a provider playlist where supported.
Provider playlist creation differs from endpoint creation.
Provider playlist names support up to 20 characters. Endpoint, mapping, and ruleset names support 10.
Names must start with a letter or number. They must use supported safe characters.
Pending provider creation
pending_create stores a provider playlist name and media type before creation.
The runner can create that target before writing playlist items.
The UI normally creates provider playlists directly. Manual pending_create changes are rarely needed.
Mapping and pair integration
Pairs store selected playlist mapping IDs here:
When saved, a mapping is validated against endpoint providers and profiles.
For one-way pairs, the source matches the pair source. Targets match the pair target.
For two-way pairs, either pair orientation can match.
Incompatible mappings are skipped during pair resolution.
Ruleset schema
The current ruleset schema version is 1.
Numeric fields:
track_assignments controls stable item placement between runs.
UI presets
Direct sync — one-way, direct, managed membership, unordered, one target.
Mirror source — one-way, direct, mirrored membership, preserved order.
Split large playlists — partitioned writes with capacity and stable assignments.
Merge playlists — aggregate reads with direct writes.
Limited account sharing — bidirectional aggregate reads and partitioned writes.
Custom — exposes detailed ruleset fields.
Built-in TraktFree ruleset
TraktFree uses:
These capacities describe CrossWatch configuration. They do not guarantee provider plan limits.
Membership and ordering
add_only plans additions only. It never removes destination items.
managed_only removes only destination items previously recorded as CrossWatch-managed.
mirror can remove every destination item absent from the source snapshot.
Use Mirror only when the source controls the complete destination membership.
ignore synchronizes membership without ordering. preserve calculates and applies target ordering.
Mappings reject preserve when a destination is known to be unordered.
Runtime state and matching
Playlist state is separate from orchestrator state:
Each scope is derived from mapping identity, ruleset, source, and destination information.
managed determines which items managed_only may remove.
Changing the mapping topology changes the scope and may create a new baseline.
Playlist items use canonical keys, external IDs, and key overlap for cross-provider matching.
Stable external IDs improve matching reliability.
Aggregate, partition, and capacity
Aggregate mode treats several playlist resources as one logical inventory.
Partition mode distributes managed items across target endpoints.
Advanced execution requires aggregate reads with partitioned writes.
stable_first_fit assigns items predictably. track_assignments preserves those placements.
rebalance = never avoids moving assigned items only to equalize targets.
overflow = block prevents silently exceeding logical capacity.
per_endpoint_capacity limits each target. aggregate_capacity limits all targets. maximum_targets limits target count.
These values are ruleset controls, not provider guarantees.
Safety and execution
Large removal plans use the shared mass-delete guard.
The decision uses suspect thresholds and allow_mass_delete.
Verify both snapshots, profile selection, and baseline before allowing mass deletion.
Dry runs calculate additions, removals, and ordering without provider writes.
Use dry runs after changing topology or destructive rulesets.
Plans track source, target, resolved, unresolved, addition, removal, reorder, and warning counts.
Applied results are stored as last_result and shown in the UI.
Unresolved items do not always fail the entire run. They could not be safely written.
Refresh and deletion
Endpoint refresh updates provider metadata and last_synced.
It does not reconcile a mapping.
Provider playlist management checks provider capabilities and resource protection flags.
Deleting an endpoint differs from deleting its provider playlist.
Deleting a mapping removes its configuration and pair reference. It never deletes provider playlists.
Stale state can be pruned after topology changes.
Operational guidance
Validate the provider and profile before creating mappings.
Start with Direct sync and
managed_only.Prefer stable external IDs on both providers.
Run a dry run after ruleset or topology changes.
Review unresolved items before allowing stricter removals.
Use Mirror only when destination-only items should be removed.
Use aggregate and partition rulesets only for real capacity constraints.
Never manually edit
playlists_state.jsonwithout understanding membership baselines.
Troubleshooting
Mapping is not attached to a pair
Confirm the source matches one pair side. Confirm targets match the opposite side.
Mapping is skipped
Check whether it is disabled, incomplete, or incompatible with the pair.
Managed items remain
managed_only removes only items in the stored managed baseline.
Topology changes can select a different scope and baseline.
Unexpected removals
Check membership mode first. mirror intentionally reconciles all destination membership.
Verify source and destination snapshots before allowing a large deletion.
Order is not preserved
Confirm that the destination reports can_reorder.
Some provider endpoint types are intentionally unordered.
Playlist actions are missing
The resource is protected, or the provider lacks the required capability.
Last updated
Was this helpful?