Libraries and folders

A library is one kind of content — films, say, or music — gathered from one or more folders. Each has its own type, folders and settings, and you can have as many as you like: separate libraries for the family's films and the children's, for example.

#Library types

The type decides how Collectoh reads the folders and how the library looks.

Naming and organising your files shows the layout for each, Beyond films what the less familiar types can do, and Games how games are played.

#Types of your own

Admin → Library types → New type makes a type of your own — say, "Guitar Courses" — with its own name, emoji icon, card shape and wording ("3 guitar courses"). Choose the built-in type it Behaves like, which decides how it's scanned and matched and can't be changed later. Give it extra fields on the Custom fields tab. Your types appear under Your types when you add a library.

#Add a library

1. Open Admin → Libraries (Admin is in the menu under your picture) and choose Add library.
2. Give it a Name, and an Icon if you like.
3. Choose its Type.
4. Add its Folders (see below).
5. Check the Metadata agents. The defaults suit most libraries; Metadata and artwork explains them. For a TV library, also set the Episode order.
6. Optionally, list anything to Leave out of scans.
7. Choose Save, then start the first scan: open the library's … menu in the sidebar and choose Scan library files.

Edit on a saved library shows more settings, depending on its type: when something counts as watched, emptying the trash after every scan, keeping an optimised copy of everything for devices that would otherwise need it converted, saving downloaded subtitles beside the media, playing pre-roll videos before films, and, for Memories, photo tags and face recognition. You can also switch a library off, or hide it from the sidebar.

#Folders from several drives

A library is a set of folders, and they can sit on different drives: a Films library can take a folder from each of three disks and show them as one.

• Add folder… lists the folders inside the chosen storage.
• Browse this PC… goes anywhere on the machine running Collectoh — with Docker, that means the folders you mounted into the container — and sets up the storage for you.

Each folder belongs to one library only: you can't add a folder another library already covers, or one inside or around it.

If you move a file from one drive to another within the same library, Collectoh recognises it and keeps its watch history.

#Storages

A storage is somewhere Collectoh reads media from. Admin → Storage lists them, with a green or red dot showing whether each can be reached right now.

#Local folders

A folder or drive on the machine running Collectoh. Test checks that the server can read it.

#Network shares

A shared folder on a NAS or another computer works once it's mounted on the machine running Collectoh; from then on it's read like any local folder. With Docker, mount the share on the host and add it to the container as another read-only folder (see Installing Collectoh). If a share can't be reached when a scan runs, nothing in it is marked missing (see below).

#Cloud drives and buckets

Your own cloud storage, your OneDrive, Google Drive or Dropbox, or an S3-compatible bucket, can hold a library with Plus. These are your own accounts, which you pay for yourself if they cost anything: Collectoh connects to them and reads your media from them, and doesn't provide the storage or pay for it.

#Cloud drives

OneDrive, Google Drive and Dropbox connect by signing in. Collectoh keeps only an encrypted token, never your password, and never shows the token to anyone.

1. Once per server, register an app with Microsoft, Google or Dropbox, allowing the redirect address that Admin → Storage shows. Give the server the app's ID and secret as environment variables — CLOUD_ONEDRIVE_CLIENT_ID and CLOUD_ONEDRIVE_CLIENT_SECRET, or the matching CLOUD_GOOGLEDRIVE_… or CLOUD_DROPBOX_… pair — and restart it. With Docker, add them under the server's environment: in docker-compose.yml.
2. In Admin → Storage, choose Connect OneDrive (or Google Drive, or Dropbox) and sign in.
3. Add a library and pick which of the drive's folders it shows.

Members who may upload photos can also connect their own drive from a Memories library's page, pick folders from it into that library, and disconnect it later.

#Buckets

A bucket at Backblaze B2, Cloudflare R2, Wasabi, Amazon S3, or any S3-compatible service such as a MinIO on your own network:

1. In Admin → Storage, choose Add storage, and S3-compatible bucket as its kind.
2. Choose the service, then fill in the bucket's region (or its endpoint, for another service), its name, and keys that may list and read it. Test checks them.
3. Save, then add a library and pick the bucket's folders.

The keys are kept encrypted, and never shown again: an empty box when you edit the storage keeps them.

Cloud drives and buckets don't tell Collectoh when something changes, so new files appear at the next scan. Switch on Scan periodically (below) to have that happen by itself.

#Scanning

A scan finds new, changed, moved and missing files. New items appear within seconds of being found; artwork and details follow in the background.

• The library's … menu in the sidebar has Scan library files (a quick scan) and Refresh all metadata.
• Admin → Scans runs any kind of scan, shows it live, can cancel it, and keeps a report: what was found, how long each stage took, and every file that caused a problem, with its path.

Collectoh scans only when you ask, so nothing reads your whole library while you're watching. To have it scan by itself, switch on Admin → Settings → Scan when files change: a minute after you stop copying files in, a quick scan of just the folders that changed picks them up, as Plex does, so a new film doesn't mean reading the rest of the library. Music, audiobooks and courses are scanned whole, as their albums and lessons can span folders. That works for folders on the machine running Collectoh. A network share or a cloud drive often doesn't say when something changes, so for those, switch on Scan periodically and choose how often, from every 15 minutes to once a week. Both are in the Library section of the settings, and a quick scan is quick because unchanged files are skipped.

Some work waits for the nightly window — 02:00 to 05:00 by default, in the server's time zone, set in Admin → Maintenance: finding intros and credits, making scrubbing thumbnails, and refreshing the oldest metadata. Analysis also stands aside while someone is watching.

On a small NAS, switch on Admin → Settings → Low-priority scanning. Scans take longer, but never make playback stutter.

#Leaving things out

Collectoh already skips:

• system and recycle-bin folders such as @eaDir, #recycle, $RECYCLE.BIN, .Trash-*, lost+found and @Recently-Snapshot
• hidden files (names starting with a dot), Thumbs.db and desktop.ini
• unfinished downloads ending .partial, .!ut or .tmp
• video files with "sample" in the name under 150 MB
• in Films, TV shows and Home video libraries, video files under 1 MB

To leave out more, use either or both of these:

• Leave out of scans in the library's settings: one pattern per line, up to 100, applied inside each of the library's folders.
• A .collectohignore file in any folder, with the same kind of patterns, applying to that folder and everything below it.

A pattern without a slash matches any file or folder of that name; a pattern with a slash matches a path from where the rule applies. Lines starting with # are comments, and a .collectohignore containing just * hides its whole folder.

# .collectohignore
*.part
Screeners
Old rips/**

#When files go missing

A sleeping NAS or an unplugged drive isn't the same as deleted files, so Collectoh is careful:

• A file that can't be found is marked unavailable. Only after two scans in a row without it (the SCANNER_MISSING_GRACE_SCANS setting) does its item move to the library's trash.
• If a storage can't be reached, the scan stops and nothing is marked missing. A library folder that suddenly lists empty — which is how an unmounted share looks — and a folder the server isn't allowed to read are treated the same way.
• Moved and renamed files are recognised by their contents, and keep their watch history, notes and bookmarks.
• If a missing file comes back, the next scan restores its item, history and all.

#The trash

Admin → Trash lists each library's trashed items — Missing from disk or Deleted by a user — and whether they hold anyone's watch history. You can Restore them, Delete forever one at a time, or Empty trash. Deleting and emptying remove Collectoh's records and their watch history for good; they never touch files.

A library can also Empty the trash after every scan. It's off by default: the trash is your safety net if a drive was asleep during a scan, so leave it off unless you're sure.

#Collectoh doesn't delete your files

Deleting an item in the app moves it to the trash, and removing a library removes only Collectoh's records. Your files stay where they are.

That also means an item whose file is still on disk comes back at the next scan. To get rid of something for good, delete or move the file yourself, or leave it out with a pattern.

An admin can switch on Allow media deletion in Admin → Settings, which lets files be deleted through the API only. It's off by default, and the app itself never deletes a file.