Admin Guide

• 1: Scanner
  • 1.1: How the Scanner Works
  • 1.2: File Structure

1 - Scanner

Stashix scans your library folders on demand and in the background whenever files change. This section explains what it expects from your folder structure, how it parses filenames, and what happens during each phase of a scan.

1.1 - How the Scanner Works

Supported formats

Stashix reads the following file types:

All other extensions are silently ignored. Files are matched case-insensitively (.CBZ and .cbz are equivalent).

EPUB support is image-only. Stashix opens an EPUB like a .cbz: the images inside become its pages and the chapter text is ignored. Fixed-layout manga and comic EPUBs read normally. Text ebooks such as novels are imported into the library, but the reader shows only their images (often just the cover). A reader for text EPUBs is not available yet.

Scan phases

A full library scan runs through four sequential phases. You can watch progress in Admin → Libraries.

1. Collecting

Stashix walks the library root recursively and lists every file whose extension is in the supported set. The walk is parallelised so even very large libraries (tens of thousands of files) collect quickly.

2. Parsing

Each new or modified file is parsed concurrently (up to 16 at a time). Parsing extracts:

• Embedded MetronInfo.xml or ComicInfo.xml from ZIP/RAR/7z archives
• A sidecar <filename>.xml placed next to the file (takes highest precedence)
• PDF info-dict fields (title, author, creation date) for .pdf files
• Filename heuristics for anything not covered by embedded metadata

Files whose path and modification time have not changed since the last scan are skipped entirely.

3. Importing

Parsed files are upserted into the database:

• A new file that shares a hash with an existing record is treated as a move — the book record is preserved and its path updated.
• A file at a known path whose modification time has advanced is updated in place.
• A file at an unknown path with an unknown hash creates a new book.

4. Thumbnails

After all books are imported, cover thumbnails are generated (up to 4 at a time). The scanner looks for a sidecar image first:

Batman 001.cbz
Batman 001.jpg   ← used as cover if present

Supported sidecar extensions: .jpg, .jpeg, .png, .webp.

If no sidecar exists, the first image inside the archive becomes the cover. Thumbnails are stored as JPEG in the configured thumbnail directory and a BlurHash is computed for smooth loading placeholders.

Orphan detection

After importing, Stashix compares the files found on disk with the database. Any book whose file no longer exists is soft-deleted (marked with a deletion timestamp). It is hidden from all library views but its metadata and reading progress are retained. Re-adding the file restores it.

Series with no remaining books are also soft-deleted.

Folder watching

Stashix watches your library folders for filesystem events using the OS native API (inotify on Linux, FSEvents on macOS). When a supported file or its sidecar is created, modified, or moved into a watched folder, the scanner queues a single-file scan after a 5-second debounce — rapid saves (e.g. a download in progress) do not trigger repeated scans.

Events for files Stashix itself just wrote (metadata write-back) are suppressed for 30 seconds to avoid re-importing its own output.

Forcing a rescan

A normal scan skips files whose path and modification time are unchanged. To re-parse everything regardless:

1. Go to Admin → Libraries
2. Click the ⋯ menu next to a library
3. Choose Force rescan

You can also trigger a rescan on a single series from the series detail page.

1.2 - File Structure

The scanner uses folder structure as its primary grouping signal — a subfolder becomes a series, the files inside become its issues. Metadata embedded in the files or their names enriches that grouping but does not override it.

The two patterns

Series in a subfolder (recommended)

Place all issues of a series in one folder named after the series. The folder name becomes the series name.

/comics/
└── Batman (1940-2011)/
    ├── Batman 001 (1940).cbz
    ├── Batman 002 (1940).cbz
    └── Batman 500 (1993).cbz

Stashix strips common year and date suffixes from the folder name and stores them as start_year / end_year on the series record. Supported patterns:

Standalone books at the library root

A file placed directly in the library root (not inside any subfolder) is imported as a standalone book with no series.

/books/
├── The Complete Persepolis.cbz   ← standalone
└── Watchmen.cbz                  ← standalone

Standalone folders

You can also designate a folder as a standalone container — every file inside is treated as a standalone book. Configure additional folder names in Admin → Libraries → Standalone folders. The built-in defaults are:

• one-shot
• one shot
• oneshot

/comics/
└── one-shot/
    ├── Batman Noel.cbz      ← standalone
    └── Superman Smashes.cbz ← standalone

Optional: publisher folder

If your library has a three-level hierarchy (publisher → series → issues), Stashix infers the publisher from the grandparent folder for new books:

/comics/
└── DC Comics/           ← inferred publisher
    └── Batman (1940)/
        ├── Batman 001.cbz
        └── Batman 002.cbz

The publisher is only inferred at import time for new books. Renaming the folder later does not automatically update existing books.

Metadata precedence

Within a single file, Stashix merges metadata from multiple sources. The order of precedence, highest first:

1. Sidecar XML — <filename>.xml next to the file (MetronInfo or ComicInfo format)
2. Embedded MetronInfo.xml — inside the archive
3. Embedded ComicInfo.xml — inside the archive (or the PDF info-dict for .pdf)
4. Filename parsing — series name, issue number, volume, year

Later sources fill in gaps; earlier sources win on any field they provide. Exception: ComicInfo.Year beats a year derived from MetronInfo’s cover-date fields.

Filename patterns

When no embedded metadata is present, Stashix extracts the series name, issue number, volume, and year from the filename. The parser tries the following patterns in order and stops at the first match:

Noise tags — (Digital), (HQ), (Webrip), (c2c), (Retail), (FIXED), (v2), etc. — are stripped before parsing. The (of N) suffix is also removed.

Tips and common mistakes

Do keep each series in its own folder, named consistently. The scanner detects folder renames by comparing file hashes, so your reading progress survives renaming a series folder.

Do not mix multiple series in one folder. Stashix uses one folder = one series, so all files in the same directory end up in the same series.

Do not nest series inside each other more than one level below the library root unless you use the publisher pattern. Deep nesting is supported by the recursive walker but only one folder level above the file becomes the series.

Do use a sidecar XML (Batman 001.xml) when you want reliable metadata that overrides filename guesses. The ComicInfo.xml or MetronInfo.xml format is both accepted.