> 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/scrobbler/filters.md).

# Filters

Limit which playback events are accepted by a Watcher route or webhook source profile.

Filters are optional. An empty filter accepts every supported movie and episode visible to the selected source profile.

Start empty for the first test. Then add only the restrictions you need.

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

### Start simple

Filters control which playback Watcher routes and webhook profiles accept.

Start with empty filters. Confirm one movie or episode scrobbles correctly.

Add restrictions only after the first successful test.

### Filter indicators

Filter rows use color indicators:

* A green dot marks an allow filter. Set values must match the event.
* A red dot marks a block or ignore filter. Matching events are skipped.

For example, **Username whitelist** allows selected users. **Ignored filename patterns** ignores matching media.

Route and webhook cards show summaries such as `1 user`, `1 UUID allow`, or `Live TV ignored`.

### Filter scope

Watcher routes and webhooks store filters differently.

#### Watcher filters

Each Watcher route has its own filters.

Example:

* Plex Home → Trakt Pascal, with username `Pascal`
* Plex Home → Trakt Family, with username `Family`

#### Webhook filters

Webhook filters belong to the media server profile. Every destination uses the same filter.

Example: Plex Home can send to both Trakt and SIMKL. Changing its webhook filter changes it for both destinations.

Use Watcher routes when each destination needs different filtering.

### Username whitelist

Use **Username whitelist** to accept playback only from selected users. Leave it empty to accept all users.

Use the user picker when possible. It uses names returned by the selected media server profile.

### Plex Server UUID lists

Plex supports a Server UUID allowlist and blocklist.

Use the allowlist when only specific Plex servers may send events:

* Empty allowlist: every UUID is accepted unless blocked.
* Filled allowlist: only matching UUID values are accepted.
* Matching is exact.

Use the blocklist to reject specific Plex servers. The blocklist wins over the allowlist.

CrossWatch rejects an event when its UUID appears in both lists.

### Ignore Plex Live TV and DVR

Enable **Ignore Plex Live TV and DVR** to skip Plex Live TV and DVR playback.

This option is available for Plex Watcher routes.

### Ignore Agregarr placeholder trailers

Enable **Ignore Agregarr placeholder trailers** when Agregarr creates placeholder movie folders with trailer files.

CrossWatch skips media that looks like an Agregarr trailer placeholder, including:

* files with `{edition-Trailer}` in the filename
* media with edition name `Trailer`
* media stored beside a `.comingsoon` marker file

CrossWatch checks the file path, filename, edition, and marker files.

It does not reject a title containing the word `trailer`.

Example skipped file:

```
/data/media/placeholder/movies/The Odyssey (2026)/The Odyssey (2026) {tmdb-1368337} {edition-Trailer}.mp4
```

### Ignored media filters

Use these filters to skip files by location, filename, or edition.

#### Ignored path prefixes

Skips media under matching paths.

Good for placeholder folders, trailer folders, or temporary media roots.

Examples:

```
/data/media/placeholder
Z:\data\media\placeholder
```

#### Ignored filename patterns

Skips media when the filename contains one of the values.

Examples:

```
{edition-Trailer}
-trailer
/sample
```

#### Ignored editions

Skips media when the edition or version name matches.

Example:

```
Trailer
```

### Provider support

These filters work when the source provides enough media details.

Supported well:

* Plex Watcher
* Jellyfin Watcher
* Emby Watcher
* Kodi Watcher
* Plex Webhooks
* Jellyfin Webhooks
* Emby Webhooks

Scrob supports these filters when its payload includes a path, filename, or edition.

### Troubleshooting

#### No events pass

1. Clear **Username whitelist**.
2. Clear Plex UUID allowlist and blocklist.
3. Disable **Ignore Plex Live TV and DVR** for testing.
4. Disable media ignore filters for testing.
5. Start a new playback session.
6. Check the source profile connection.
7. Review debug logs for the rejected field.

#### A trailer still scrobbles

1. Confirm the media source sends a file path or edition.
2. Add the placeholder folder to **Ignored path prefixes**.
3. Add `{edition-Trailer}` to **Ignored filename patterns**.
4. Add `Trailer` to **Ignored editions**.
5. Start a new playback session.

#### Wrong user is scrobbled

1. Use the user picker.
2. Verify the route or webhook scope.
3. Confirm the destination profile belongs to that user.
4. Check for another route or webhook without filters.
   {% endtab %}

{% tab title="Power users" %}

### Filter storage

Filters control whether a playback event is accepted before CrossWatch sends it to a scrobble destination.

Watcher routes use a route-level `filters` object. Webhook source profiles use provider-specific filters.

Examples include `filters_plex`, `filters_jellyfin`, and `filters_emby`.

### Matching behavior

Username matching ignores letter case. Normal names also ignore punctuation and spaces.

A nonmatching whitelist rejects the event. Without a username whitelist, the user filter passes.

Advanced identity values are supported when the source event supplies them:

```
id:123
uuid:abcd1234
```

* `id:` compares account or user IDs.
* `uuid:` compares account or user UUID values.

Use advanced values only when normal username matching is ambiguous or unreliable.

Webhook providers can expose different user fields. Use the exact event-log username when the picker is unavailable.

### Profiles, filters, and libraries

Profiles and filters solve different problems.

A source profile selects a connected server or account. Filters select its accepted events.

Example:

* Profile: Plex Home Server
* Username whitelist: Pascal
* Server UUID allowlist: Home Server UUID

Use profiles for connection separation. Use filters for event separation.

Filters do not replace media server library whitelisting.

Library whitelisting determines usable libraries. Filters determine accepted playback events.

Changing a username or UUID filter cannot bypass a library whitelist rejection.

### Media filter behavior

Media ignore filters are case-insensitive.

Path prefixes are normalized. Windows and Linux paths can both match.

Examples:

```
Z:\data\media\placeholder
/data/media/placeholder
```

Filename patterns use simple contains matching. They do not support regular expressions.

Edition matching compares the detected edition or version name. `Trailer` matches `trailer`.

When a media filter matches, CrossWatch drops the event before sending a scrobble.

### Agregarr placeholder trailers

The Agregarr toggle is a shortcut for the common placeholder trailer setup:

```json
{
  "ignore_agregarr_trailers": true
}
```

It checks the built-in defaults:

```
filename contains: {edition-trailer}
edition equals: trailer
marker file: .comingsoon
```

This check does not use titles. `Trailer Park Boys` is accepted unless another value matches.

### Route filter example

Watcher route filters use the route `filters` object:

```json
{
  "filters": {
    "users": ["Pascal"],
    "ignore_agregarr_trailers": true,
    "ignored_path_prefixes": ["/data/media/placeholder"],
    "ignored_filename_patterns": ["{edition-Trailer}"],
    "ignored_editions": ["Trailer"]
  }
}
```

### Webhook filter example

Webhook filters are stored per source profile. Use the matching provider key:

```json
{
  "filters_plex": {
    "ignore_agregarr_trailers": true,
    "ignored_filename_patterns": ["{edition-Trailer}"]
  },
  "filters_jellyfin": {
    "ignored_path_prefixes": ["/data/media/placeholder"]
  },
  "filters_emby": {
    "ignored_editions": ["Trailer"]
  }
}
```

Every destination on that source profile uses the same provider filter.

Use Watcher routes when each destination needs its own filter set.

### Supported media keys

CrossWatch looks for path-like values in incoming payloads, including:

```
path
file
filename
filepath
file_path
mediafile
media_file
```

It also checks internally enriched Plex values:

```
_cw_file_path
_cw_file_paths
_cw_edition_title
```

Edition-like values include:

```
edition
editionTitle
edition_title
version
versionTitle
version_title
```

CrossWatch also searches nested payloads. This supports fields such as Jellyfin and Emby `NowPlayingItem.Path`.

### Common mistakes

#### Using a display name

The display name can differ from the event username. Use the picker or inspect event logs.

#### Adding a Plex account ID without a prefix

Use:

```
id:123
```

Do not use:

```
123
```

The `id:` prefix is required for an ID match.

#### Expecting different webhook filters per destination

Webhook filters are shared by source profile. Use Watcher routes for destination-specific filtering.

#### Adding one UUID to both lists

The blocklist wins. CrossWatch rejects the event.

#### Expecting Scrob to always have file paths

Scrob needs a path, filename, or edition field for these filters.

Media-file filters cannot match payloads with only metadata IDs and title information.
{% 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/scrobbler/filters.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.