Library operations

Kometa-style operations: for this library — bulk metadata work applied to every item:

• Ratings mapping — fill Plex's rating fields from AniDB, IMDb, MyAnimeList, MDBList, OMDb, Trakt, TMDB, Letterboxd, Metacritic, Rotten Tomatoes or Serializd.
• Field locking / unlocking, and remove-and-lock.
• Content rating mapping, genre mapping and similar per-field operations.
• Metadata restore for fields an operation overwrote.

Every operation reports how many titles it would change before anything is written, so you can read the diff first. A library switched off here is skipped entirely and never appears in the worklist.

The tabs, and what each one writes

The tabs are Kometa's own, in Kometa's order. A tab with nothing behind it yet is still shown and says so rather than being hidden, so the list stays the same list you know from Kometa.

Each field is a list of sources in order, not one choice: Kustos takes the first source that has a value, and a title none of them cover is left alone. A source whose service is not connected is greyed out with the reason beside it, rather than sitting there looking selectable and quietly producing nothing.

Remember that every write here also locks the field, which is the next part.

Every write on this screen also LOCKS the field in Plex. That is the fact the rest of this section follows from. A locked field is one Plex's own agent stops correcting, so an operation that writes the wrong thing does not fix itself on the next scan, and undoing it is not a matter of asking Plex to refresh.

Back it up first — it is the only undo

Back up this library's metadata writes the current values to a YAML file and touches Plex not at all. It is the only way back from anything else on this card, precisely because the operations write to Plex and lock the field.

Run it before the first operation on a library, not after one has surprised you.

Restoring appends where it cannot prove ownership. Where Kustos cannot show it set a value, the restore adds rather than replaces. That reads cautious and is not a preference — unprovable ownership must not license a destructive write, and the alternative is the failure that once emptied and locked a whole Plex genre set. A restore that adds too much is a tidy-up; one that deletes what it did not put there is not recoverable.

Dry run everything. The setting applies to every operation on the library, and the run's step detail reports exactly how many titles each one would change — so the diff is readable before anything reaches Plex.

"Show every title" is off by default because a library of mostly-empty entries buries the ones that actually carry data. Turn it on when you want a line per title regardless.

Which tabs actually run

Every tab saves and validates what you set. Not every tab has an engine behind it yet, and configuring one that does not looks exactly like a bug when the run does nothing. The tabs that run today are Genres, Content Ratings, Ratings, Dates, Studios and Collections. The others say so on the tab itself.

Collections is the odd one out. It sets Plex's hub-visibility mode on every collection in the library rather than on your titles, and it writes to all of them rather than only the ones that differ, because Plex does not report a collection's current mode. A collection Kustos manages carries its own mode too and will reassert it on its next build.

Run an operation without losing metadata

The order here is load-bearing. Each step exists because of the one before it.

1. Turn on the library's Dry run first. It applies to every operation on this library. The run's step detail then reports exactly how many titles each one would change, and nothing is written.
2. Set up the exclusions before you look at anything else. Leave these titles alone takes Plex labels and …or leave these alone by id takes ids. Both are pickers rather than free text, deliberately: a typo in an exclusion protects nothing and says nothing, so you would find out afterwards if at all. The exclusion is applied once, before every operation, and only ever removes titles from a pass. That makes it the cheapest protection on the screen.
3. Turn on Metadata backup, on the Backup tab. It writes the library's metadata to a YAML file and runs first, so the file records the library as it was before anything changed it. Nothing is written to Plex. This is the only undo. The operations write to Plex and lock the field, so Plex's agents cannot put it back. Leave File blank unless you need a specific path. Blank is resolved when the run happens, so renaming the library or moving Kustos's data folder cannot strand the backup at an old path. Leave out is a picker of the field names the backup writer actually emits — anything you exclude here cannot be restored from the file.
4. Run it and read the diff. The step detail gives you a count per operation. A count far larger than you expected is the whole reason for this step.
5. Only then turn Dry run off. The card prints a warning while it is off, naming the lock and the backup, because that is the state in which a mistake is expensive.
6. Run it for real, and check a few titles in Plex.

Content Ratings has two settings worth knowing. Format offers 8, 10, 17 or the zero-padded 08, 10, 17 — pick padded, because Plex sorts that field as text, so "10" lands before "8" otherwise. Lookups per run exists because MDBList charges per lookup and a full library is thousands, so each run asks about that many new titles and the rest resume next time.

Restore metadata an operation overwrote

The restore lives beside the backup it reads, on the same tab, because a backup you cannot apply is a record rather than an undo.

1. Point it at the backup file.
2. Read the preview. It tells you what would be written before anything is.
3. Confirm, and restore.

Where Kustos cannot prove it set a value, the restore appends rather than syncs. That is deliberate and it is the most important sentence here. Unprovable ownership must not license a destructive restore — the alternative is a restore that empties and locks a field it did not own.

Include titles that have no metadata is off by default, because a library of mostly-empty entries buries the titles that actually carry data. Turn it on if you want a line for every title regardless.

Label Manager

Plex labels are how Kustos marks a title as belonging to a collection, as personal to one viewer, or as leaving soon. Over time a library collects labels that nothing points at any more — a collection you deleted, a person who left.

The Label Manager lists every label in the library. Open one and it breaks the count down by level — shows, seasons and episodes separately — so you can see what actually wears it before deciding.

Remove from this library strips the label from everything in that library. It asks first, naming the counts, because it writes to Plex and cannot be undone from here. A label nothing carries has no Remove button at all rather than a greyed one: there is nothing to act on.

Two things to know:

• Episode labels are invisible unless you ask for them. Plex reports zero episode labels on an ordinary read, so a label that looks unused at show level may still be on hundreds of episodes. That is exactly why the breakdown is per level here.
• Nothing in Plex deletes a label outright. A label disappears when the last item stops wearing it, so removal is a bulk edit rather than a delete.