# Library Whitelisting

Whitelisting limits which libraries CrossWatch (CW) reads and writes. It also controls which libraries generate scrobbles.

Use it to:

* speed up runs
* reduce API calls
* avoid syncing noise libraries (music, photos, live TV)
* block scrobbling from specific libraries

### Two whitelist layers

1. **Server-level** (provider settings)\
   Applies to every pair using that provider.
2. **Pair-level** (pair settings)\
   Applies only to one pair.

If you do not configure whitelisting, CW uses **all visible libraries**.

{% hint style="info" %}
Server-level filtering is used by the orchestrator. Pair-level filtering is applied by adapters.

Some UI dashboards use orchestrator state. If you rely heavily on pair-level filtering, dashboards can look too big.
{% endhint %}

### Server-level whitelisting (recommended)

Available for Plex, Jellyfin, and Emby under **Settings → Authentication**.

{% hint style="warning" %}
If you use **Profiles** (Instances), whitelisting is configured **per profile**.

Each profile has its own server/user connection and its own H/R/S library selections.
{% endhint %}

You can whitelist per feature:

* **History** (H)
* **Ratings** (R)
* **Scrobble** (S)

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

#### Scrobble whitelist

Scrobble whitelisting controls which libraries generate real-time scrobbles:

* Watchers
* Webhooks

If scrobble libraries are empty, CW scrobbles **everything**.

#### Set server-level whitelists

{% stepper %}
{% step %}

### Open provider whitelisting

Go to **Settings → Authentication**.

Open **Plex**, **Jellyfin**, or **Emby**.

Select the profile you want to edit.

Open **Whitelisting**.
{% endstep %}

{% step %}

### Load libraries

Click **Load Libraries**.
{% endstep %}

{% step %}

### Select H / R / S

Select libraries under:

* **H** (History)
* **R** (Ratings)
* **S** (Scrobble)
  {% endstep %}

{% step %}

### Save

Click **Save**.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Emby and Jellyfin expose "Views".

CW resolves items to the correct view first.
{% endhint %}

### Pair-level whitelisting (per pair)

Pair-level whitelisting lives in the pair editor. It is used mainly for **History** and **Ratings**.

Pair-level selection:

* overrides the pair's scope
* does not affect other pairs

{% hint style="info" %}
Scrobble whitelisting is **server-level only**. Scrobbling is event-driven, not pair-driven.
{% endhint %}

#### Set pair-level whitelists

{% stepper %}
{% step %}

### Open a pair

Go to **Pairs**.

Edit a pair.
{% endstep %}

{% step %}

### Load libraries

Open the provider settings (Plex/Jellyfin/Emby).

Click **Load Libraries** if needed.
{% endstep %}

{% step %}

### Select libraries

Select libraries for History and/or Ratings.
{% endstep %}

{% step %}

### Save

Save the pair.
{% endstep %}
{% endstepper %}

### How the two layers interact

Think of it like:

* Server-level = maximum allowed scope
* Pair-level = per-pair subset

### Troubleshooting

**Insights dashboard shows too much data**

* Dashboards are based on orchestrator state.
* Prefer server-level whitelisting for global scoping.
* Keep pair-level whitelisting for exceptions.

**Pair-level whitelisting doesn’t work**

* Confirm the pair provider section has libraries selected for the feature.
* Re-run the pair once to refresh state.

**Scrobble ignores my library selection**

* Scrobble filtering is server-level only.
* Verify **S** libraries are selected in provider whitelisting.

**Reset and allow everything**

* Clear selected libraries at server-level (H/R/S).
* Clear selected libraries in the pair.
* Save and re-run.


---

# Agent Instructions: 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/library-whitelisting.md?ask=<question>
```

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.