Libraries

A library is a folder plus a type. The type decides which files are picked up and how they're shown. You can have as many libraries as you like, including several of the same type. Plinthio only reads your folders. It never renames, moves or writes into them.

Adding a Library

Admins add libraries in Admin → Libraries:

1. Choose Folder and browse to it. This is the path as the server sees it. In Docker, your media is mounted at /media.
2. Give it a Name.
3. Under What's in it, pick the type: Movies, TV shows, Anime, Books, Manga & comics or Audiobooks.

The first scan starts straight away and titles appear as they're found. Each library in the list has Scan for a full rescan, and a delete button. Deleting a library removes it and its titles from Plinthio. The files on disk are untouched.

Types and Formats

Library type	Picks up	Shown as
Audiobooks	.m4b .mp3 .m4a .flac .aac .ogg	Audiobooks, played in the audio player
Manga & comics	.cbz .zip .cbr .rar .cb7 .7z	Manga, read right-to-left by default
Books	.epub .pdf, plus audiobook and comic files	Books. EPUBs open in the book reader. PDFs and comic archives open in the page reader, left-to-right
Movies	.mp4 .mkv .webm .avi .mov	Movies, grouped into collections where TMDB has one
TV shows	the same video formats	Shows, by season and episode
Anime	the same video formats	Anime, laid out like shows

Comic archives are identified by their contents, not their extension, so a .cbr that's really a zip opens fine. Pages inside archives are sorted naturally (2.jpg before 10.jpg), and __MACOSX folders are ignored.

Laying Out Folders

Plinthio follows the common media-server naming conventions, so a library already laid out for another server usually needs no changes. None of them are strictly required, but following them gets the grouping right the first time.

Manga and Comics

Manga/
  One Piece/
    One Piece v01.cbz
    One Piece v02.cbz
  Standalone One-Shot.cbz

• Series: the folder, when it holds more than one archive or the file has a number. A <Series> in ComicInfo.xml always wins.
• Volume number: from the file name (v01, Vol 1, Volume 1.5, ch 12, #3), otherwise ComicInfo's <Number>.
• From ComicInfo.xml: <Title>, <Writer>, and <Manga> (YesAndRightToLeft sets right-to-left, anything else left-to-right). <AgeRating> sets the series' age rating.
• Cover: the first page.

Books and PDFs

• EPUB: title, author and cover come from the book's own metadata.
• PDF: the page count, and the author when the PDF names one. The cover is a cover.jpg or folder.jpg next to it, otherwise its first page. Pages are rendered on the server the first time they're read, then cached.

Audiobooks

One file per book works best (.m4b with chapters). Title, author and series come from the file's tags. The album becomes the series when it differs from the title. Embedded artwork, or a cover, folder, poster or front image in the folder, becomes the cover.

Movies

Movies/
  Blade Runner (1982)/
    Blade Runner (1982).mkv
    Featurettes/
      Designing the Future.mkv
    Blade Runner-trailer.mp4
  Arrival (2016).mp4

• Title and year: from the file name, with release junk (1080p, x264, release groups) stripped.
• Collections: with a TMDB key, films are grouped into their TMDB collection (Shrek, Star Wars and so on) once the library has two or more of them. The Movies shelf has a Collections / All movies switch.
• Poster: a poster.jpg, cover.jpg or folder.jpg in the film's folder, otherwise TMDB (with a key), otherwise a frame from about 20% into the film.

Shows and Anime

Shows/
  Severance/
    Season 01/
      Severance - S01E01 - Good News About Hell.mkv
    Season 02/
      Severance - S02E01.mkv
    Specials/
      Severance - S00E01.mkv

• Episode numbers: S01E02, 1x02, Ep 02 or Episode 2 in the file name. Specials are season 0 and listed last.
• Series: the show name in the file name, otherwise the folder.
• A show split into season folders appears once, under the show.
• Episode stills are taken from the video the first time the episode list shows them, then cached.

Extras

Trailers, featurettes and similar videos are kept off the shelf, out of search and out of Continue. They appear in an Extras row on their film's or show's page. A video counts as an extra when it is:

• in a folder named Extras, Featurettes, Behind The Scenes, Making Of, Deleted Scenes, Interviews, Scenes, Shorts, Trailers, Bonus Features, Special Features or Other, or
• named with a suffix: -trailer, -featurette, -behindthescenes, -deleted, -interview, -scene, -short, -other or -extra, or
• (movies only) in a subfolder of a film's own folder, or a loose file next to the film that is less than 40% of its size.

A folder holding several full-length films isn't collapsed. They stay films.

Scanning

Libraries are scanned when they're added, when you press Scan, and automatically. Admin → Libraries → Automatic scanning has two switches:

• Re-scan on a schedule: every 15 minutes, 30 minutes, hour (the default), 6 hours or day. This is the dependable one for network shares, which often don't report changes.
• Watch folders for changes: scans about 30 seconds after a new file appears, where the filesystem reports it.

What a scan does:

• Unchanged files (same path and size) are skipped, so rescans are quick.
• Moved files: a file with the same name and size that turns up in another folder is treated as the same title, so progress, ratings, bookmarks and list entries follow it. A renamed file counts as a new title, and the old one goes missing (below).
• Artwork: every scan retries titles that still have no cover. Adding a TMDB key later fills in posters without starting over.
• Safety: if a library's folder is missing (P200), or is suddenly empty while the catalog has titles in it (P201, usually an unmounted drive), the scan stops rather than treating everything as deleted.

Missing Files

When a file disappears, its title is kept but hidden from everyone. Its progress, ratings, bookmarks and list entries stay. This covers a drive that didn't mount, a share that dropped, or a folder you're reorganising. If the file comes back, the title reappears on the next scan with everything intact.

Admin → Health → Missing files lists them by film, book, series or season. For each one, choose:

• Keep as history if you deleted the files on purpose. The title becomes offloaded (below).
• Remove for good once you're sure it isn't coming back. This deletes it from the catalog with its covers and thumbnails. If exactly the same file is scanned again later, progress and ratings re-attach.

Offloaded Titles

When space runs short, you can delete files and keep their history. For example, you've watched five seasons of a show and only want the sixth on disk. Offloaded titles are:

• Hidden from shelves, search, Continue Watching and the reading apps.
• Shown on their title page, dimmed, with an Offloaded badge and everyone's progress, ratings and watched marks. Titles the server never had (a film missing from a collection, a list entry) go grey with a dashed outline and a Not in library badge instead.
• Not playable. Up next skips them.
• Restored automatically if the files come back, even under a different file name: a new file for the same show, season and episode (or a film with the same title) takes over the offloaded entry and its history.

There are two ways to offload, both for admins:

1. Delete the files first, then in Admin → Health → Missing files choose Keep as history (or keep them all).
2. Offload first with Keep as History on the title page (the film, the season on screen, or a whole series), then delete the files.

Admin → Health → Offloaded lists everything kept as history, with Undo and Remove for good. Removing all missing files never removes offloaded titles.

Metadata and Artwork

Editors and admins can fix titles from the title page (Edit Metadata) or in bulk in Admin → Metadata.

Media	Providers
Manga	MangaDex
Books and audiobooks	Google Books, Open Library
Movies, shows and anime	TMDB (needs a key)

• TMDB key: paste your key at the top of Admin → Metadata. Get a free one at themoviedb.org → Settings → API. It's checked against TMDB when you save it. Either the "API Key" or the "API Read Access Token" works.
• Auto Match on a row matches that title and shows the result inline, so you can work down a list.
• Batch match works through the selected titles one at a time in your browser, with a running summary.
• Clean titles strips release junk from titles taken from file names.
• Search providers by hand, and apply a result to one title or a whole series.
• Cover upload: any image, for one title or a whole series.
• Series settings on the title page: display name, reading direction and age rating for a whole series.

Cast, crew, studios, tagline, backdrop, logo and TMDB facts for movies and shows are fetched the first time a title page opens (with a key) and cached for 30 days.

Without a TMDB key, video still gets titles from file names and covers from folders or video frames. Searches that need the key fail with P400.

Library Health

Admin → Health lists what needs attention:

• unreachable libraries (folder missing or unreadable)
• missing files and offloaded titles (above)
• likely duplicates (the same title twice)
• clashing volume numbers in a series
• titles with no cover, description or author
• titles with no age rating (relevant when content limits are in use)
• recent video conversion failures

Each list links to the titles, with a rescan or fix action where one applies.