Z-Keeper

Z-Keeper · how it fits together

Three layers, two doors,
one way back

Z-Keeper keeps three records of your library. Two of them describe a player — what it says now, and what it should say. The third describes your files, and it exists whether or not you own a Zidoo at all.

Where everything lives

Your files sit above; your Zidoos each index a slice of them. Down in Z-Keeper's database, every Zidoo gets its own pair of layers — and underneath them all sits one Master Catalog that knows nothing about devices at all.

Your library every video file on your network — each one gets a row in the Master Catalog WHICH FILES EACH ZIDOO HAS INDEXED Zidoo 1 Zidoo 2 Zidoo 3 no Zidoo has indexed this file — the Master Catalog still holds it Zidoo 1 keeps its own matches, art and collections Zidoo 2 Zidoo 3 Z-KEEPER'S DATABASE Sync Sync Sync Zidoo copy what Zidoo 1 said at the last sync replaced every sync Zidoo copy Zidoo copy Blueprint what Zidoo 1 should look like changes only when you approve something Blueprint Blueprint Master Catalog what is true about each film and each file — with no Zidoo in the picture one row per file, covering the whole library above, shared by every device Identify — reads your files, never a Zidoo · needs a free TMDB API key
What a Zidoo says What it should say What's true, whatever the device
Look at the gold line. It leaves your files and reaches the Master Catalog without touching a single Zidoo — that is Identify, reading the source folders you set in Settings. It needs no player, and no sync to have ever run. The green lines are Sync, which only ever asks a device what it currently holds, and can only ever describe what a device has seen.

The same three layers, in words

The quickest way to tell them apart is to ask where each one's rows come from. Two are built from what a player reported. One is built from your files.

Zidoo copy

One per device

Answers
What does this Zidoo hold right now?
Changes when
Every sync. It is replaced, not merged — it is a snapshot, not a record.
Survives a factory reset
No. It follows the device down and comes back rebuilt.

Blueprint

One per device

Answers
What should this Zidoo look like once everything is right?
Really it is
The Master Catalog as it applies to one player — the titles that player holds, in that player's own id numbering, plus any settings that are unique to this device, such as a different poster than the Master Catalog's cemented poster.
Changes when
Only when you approve or change something. Nothing a device does moves it.
Survives a factory reset
No — not usefully. Its rows are keyed on the device's own entry ids, which a rebuild discards wholesale, so it describes a vanished player exactly as the mirror does. Recovery is to clear it along with the mirror, then rebuild the device from the Master Catalog. What that costs is only what this device held differently: its watched and favorite history.

Master Catalog

One, shared by every device

Answers
What is in your library, and what each file is — with or without a player attached.
Changes when
Only when you approve or change something.
Survives a factory reset
Yes. It never referred to the player in the first place, so re-issued ids mean nothing to it.
Built from
Your source folders, read straight off disk. A row exists because a file exists — not because a Zidoo mentioned it.

One file, three answers

Suppose you rebuilt a Zidoo's sources, and its own scraper matched a film to the wrong title. Nothing is broken — the three layers simply disagree, which is exactly what they are for.

The file Predator Badlands_t03.mkv is on the shelf, and the Zidoo has just re-scraped it.

What is

The Zidoo copy says it is a different film entirely.

Not a lie — just what the player reported at the last sync.

What should be, here

The Blueprint says this Zidoo should show Predator: Badlands.

Because you approved that once, on this device.

What's true, anywhere

The Master Catalog says the file is Predator: Badlands.

Keyed to the file and its TMDB identity. No device involved, so a reset cannot touch it.

Push fixes closes the gap. It compares one of the two right-hand layers against the Zidoo copy and sends only the differences back to the player — matches, collections, categories, artwork and metadata, each ticked one row at a time.

Two ways in, one way out

Sync and Identify are often confused because both fill the database. They ask completely different things, of completely different sources — and neither of them ever writes to your player.

Only one of them requires you to own a Zidoo.

Your Zidoo the player itself Your video files on your NAS or drives Sync asks the player what it holds Identify reads the files themselves asks TMDB for the title needs a free TMDB API key Zidoo copy what it said at the last sync replaced every sync Master Catalog what is true about each file no device ids anywhere you approve it for the titles this Zidoo has Blueprint what this Zidoo should look like one per player Push fixes — the only thing that writes to your Zidoo
Sync asks the player; Identify reads the shelf. That is the whole difference — and it is why a wiped Zidoo can be put back, and why the Master Catalog is worth building before you own one. Push fixes runs the other way, and you choose which layer it argues from: the Master Catalog, or that device's Blueprint.

One approval, three writes

This is the rule that keeps the layers from drifting apart. Change anything, anywhere, on any Zidoo — and Z-Keeper treats it as curated and cements it in all three places at once.

You approve a match, a poster, a collection… The Zidoo you changed it on it looks right immediately That Zidoo's Blueprint this device's own curation, kept apart The Master Catalog so every other Zidoo can be held to it too
A decision you made once should not have to be made again — not after a rescan, not after a reset, and not separately for each player you own.

What survives a factory reset

This is the moment the three layers earn their keep. A reset wipes the player's own database and re-issues every id it hands out.

Zidoo copy

Goes with it. The next sync simply records the new, emptier truth.

Blueprint

Cleared too. Keyed on the ids the reset threw away, so it is wiped with the mirror — you lose only this device's watched and favorite history.

Master Catalog

Untouched. Keyed to files and films, so the new ids don't matter.

The player remembers more than you would expect, too: re-adding your sources brings back things it had learned about a title — custom collection membership, for instance — as soon as its scraper matches that title again. What it does not bring back is a correct match; it repeats its original mistakes. So the order of recovery is always the same — fix the matches first, and a great deal of the rest follows on its own.