Libraries

A library is a folder, or a set of folders, that Aviato scans on a schedule and presents as one browsable collection. You pick the type when you create the library (Movies, TV Shows, Music, Audiobooks, Photos, Books), and that choice tells Aviato how to interpret what it finds.

This page is the contract between you and Aviato. If your files follow the conventions below, Aviato will pick the right primary file, fold trailers and featurettes into the same item, and pair sidecar files like subtitles, artwork, and NFO files with the right media. If your layout drifts from these conventions, Aviato will do its best, but you may end up with a movie that appears three times because its trailer landed in a sibling folder.

How Aviato thinks about files

Aviato has two ways of grouping files into items:

1. One item per folder. Every folder under the library root becomes one item. Everything inside that folder, including subfolders, belongs to the same item. Movies work this way. So do audiobooks shipped as a folder of MP3 chapters.
2. One item per file. Each playable file is its own item. TV episodes work this way (one episode per file), and so do music tracks and standalone audiobook files (a single .m4b).

Inside a one item per folder library, Aviato also looks at each file's name and the subfolder it sits in. Files end up in one of four buckets:

• Primary. The main playable file. Most movies have exactly one primary file per folder.
• Trailer, behind the scenes, deleted scene, extra. Bonus videos that appear in the Extras row on the item page.
• Companion. Subtitles, NFO files, artwork, trickplay sprites. Not playable on their own, but attached to whatever primary they belong to.

The rules that decide what is what are built in for each library type, so they match common conventions out of the box. You do not configure anything — you only need to put files in folders the way Plex or Jellyfin users already do.

Recommended layout: Movies

One folder per movie, under the library root. Aviato treats the folder as the item, so a folder named Inception (2010) becomes one library item even if it contains a dozen files.

/movies
└── Inception (2010)
    ├── Inception (2010).mkv             ← primary
    ├── Inception (2010).en.srt          ← subtitle
    ├── poster.jpg                       ← artwork
    ├── backdrop.jpg
    ├── fanart.jpg
    ├── logo.png
    ├── movie.nfo                        ← metadata sidecar
    ├── Inception (2010).trickplay       ← trickplay sprites
    │   ├── 0.jpg
    │   └── 1.jpg
    ├── trailers
    │   └── Inception Teaser.mkv         ← extra (trailer)
    ├── featurettes
    │   └── Dream Architecture.mkv       ← extra (behind the scenes)
    ├── deleted scenes
    │   └── Original Ending.mkv          ← extra (deleted scene)
    └── other
        └── Director Commentary.mkv      ← extra

Year in the folder name

Putting the release year in parentheses (Inception (2010)) is recommended. It helps Aviato pick the right film when two movies share a title, and it leaves room for sequels later.

External IDs

If you want to lock a folder to a specific TMDb, IMDb, or TVDB entry, append the ID in curly braces on the primary file:

Inception (2010) {tmdb-27205}.mkv
Inception (2010) {imdb-tt1375666}.mkv

Aviato uses these directly instead of guessing from the title.

Multiple editions in the same folder

A director's cut and a theatrical cut of the same movie share one folder. Put the edition tag in curly braces on each primary file:

Blade Runner (1982)
├── Blade Runner (1982) {edition-Theatrical}.mkv
├── Blade Runner (1982) {edition-Final Cut}.mkv
└── Blade Runner (1982) {edition-Director's Cut}.mkv

All three end up as one library item with three versions. The Versions selector on the item page lets you pick which cut to play.

Multiple resolutions of the same cut

If you keep both a 1080p and a 4K copy of the same movie, name them so they share a stem:

Inception (2010)
├── Inception (2010) - 1080p.mkv
└── Inception (2010) - 2160p.mkv

Both become versions of one item. Avoid putting them in separate folders, since that splits them into two library items.

Stacked parts (multi disc rips)

For movies that are physically split across files (a long film, a multi disc Blu ray rip), name the parts with a part, cd, or disc suffix:

The Lord of the Rings - The Return of the King
├── The Return of the King - part1.mkv
├── The Return of the King - part2.mkv
└── The Return of the King - part3.mkv

Aviato plays them back to back as a single video.

Extras subfolders

These subfolder names are recognised inside any movie folder, and their contents are folded into the parent item as extras:

Filename based extras (a video that sits next to the primary, named Movie-trailer.mkv or Movie.trailer.mkv) are also recognised. Either approach works.

Companion files

Aviato pairs sidecar files with the right media by looking at the filename.

Files that cannot be matched by name (a generic poster, an NFO without a matching media name) attach to whichever movie shares their folder.

Recommended layout: TV Shows

One folder per show, with subfolders per season. Each episode file is one library item.

/tv
└── Ted Lasso
    ├── tvshow.nfo
    ├── poster.jpg
    ├── backdrop.jpg
    ├── Season 01
    │   ├── Ted Lasso S01E01.mkv
    │   ├── Ted Lasso S01E01.en.srt
    │   ├── Ted Lasso S01E01.trickplay
    │   │   └── 0.jpg
    │   ├── Ted Lasso S01E02.mkv
    │   └── Ted Lasso S01E03.mkv
    └── Season 02
        └── Ted Lasso S02E01.mkv

Episode naming

Aviato expects the season and episode to appear as S01E01 (or s01e01, case does not matter) anywhere in the filename. Both of these work:

Ted Lasso S01E01 Pilot.mkv
S01E01 - Pilot - 1080p.mkv

Aviato uses the combination of season, episode, and folder as the identity, so two files named Show S01E01.mkv in different season folders are treated as different episodes.

Multiple resolutions per episode

Same rule as movies. Keep them in the same folder with a shared name prefix:

Season 01
├── Ted Lasso S01E01 Pilot - 1080p.mkv
└── Ted Lasso S01E01 Pilot - 4k.mkv

Both become versions of one episode.

Episode subtitles and sidecars

Episode sidecars pair by filename, the same way movie sidecars do. Ted Lasso S01E01.en.srt attaches to Ted Lasso S01E01.mkv. Trickplay folders (Ted Lasso S01E01.trickplay/) attach the same way.

Show level and season level extras

Shows have no per episode "parent" for show wide trailers. A trailers folder at the show level (a season teaser, for example) is not currently folded into a show level extras section. For now those videos appear as their own items in the library. Future versions of Aviato will surface them at the show level.

Recommended layout: Books

One file per book, one folder per author. Each book file is one library item, with optional companion files alongside it.

/books
└── Frank Herbert
    ├── Dune.epub                  ← primary book
    ├── Dune.opf                   ← optional metadata sidecar
    ├── Dune.jpg                   ← optional cover image
    ├── Children of Dune.epub
    └── Children of Dune.jpg

Companion files attach to the book whose filename they share. Dune.jpg attaches to Dune.epub. If a cover image has a generic name like cover.jpg it will not attach automatically; rename it to match the book.

Recommended layout: Audiobooks

Two shapes work, and Aviato handles both.

A single file audiobook (one .m4b):

/audiobooks
├── Dune.m4b
└── Dune.pdf            ← optional companion (artwork, transcript)

A multi file audiobook (one folder of MP3 chapters):

/audiobooks
└── Dune
    ├── 01 - Part One.mp3
    ├── 02 - Part Two.mp3
    ├── 03 - Part Three.mp3
    ├── cover.jpg
    └── booklet.pdf

An .m4b is always one item per file. Loose MP3s are grouped per folder.

Recommended layout: Music

One folder per album. Each track is its own library item, and Aviato assembles the album view from the tracks via metadata.

/music
└── Artist
    └── Album Name
        ├── 01 - Track One.flac
        ├── 02 - Track Two.flac
        ├── 03 - Track Three.flac
        └── cover.jpg

Supported file types

Each library type picks up a different set of file extensions. The full list is defined by the library plugin you chose; the common defaults are below.

Files with an unrecognised extension are skipped during a scan.

Excluding files

Aviato automatically ignores filesystem cruft you almost certainly do not want indexed:

• macOS: .DS_Store, ._* resource forks, __MACOSX, .AppleDouble, .AppleDB
• Windows: Thumbs.db, desktop.ini
• Synology: @eaDir, .@__thumb
• NAS recycle bins: .Trash, .Trash-*, @Recycle, #recycle, lost+found
• In-flight downloads: *.partial, *.crdownload, *.tmp, *.swp

You can add your own patterns per library. Open the library in Settings → Libraries, edit the library, and add entries to Ignore patterns. Patterns follow gitignore-style globs:

• *.bak — match any file ending in .bak anywhere in the library
• samples/** — match every file under any samples folder
• Old Stuff/** — exclude a specific folder by name

Ignored files are skipped at scan time. They do not appear in the library, do not consume scan time, and never trigger plugin work.

Triggering a rescan

Aviato scans on a schedule, but you can force one from Settings.

• Quick rescan. Open Settings → Library to trigger a quick rescan of every library. Aviato checks each scan root for new or removed files and updates only what changed.
• Full reprocess. Open Settings → Libraries, edit the library you want to refresh, and scroll to the Danger Zone. The Full Reprocess button drops cached metadata, re-bundles every file, and re-runs the full indexing pipeline. Use this when you change a layout (rename folders, move extras into recognised subfolders) and want the change reflected immediately, or when a library plugin update changes the parsing rules.

If you enabled Watch for Changes on the library and your filesystem plugin supports it, you usually do not need to trigger rescans manually — adds, removes, and renames flow in as events.

Renaming and moving files

If a file is renamed or moved within a library, Aviato detects the new path on the next scan (or immediately, if watch is enabled). Today the new path is treated as a new file and the old path is marked as missing. A future release will use content hashes to detect renames automatically and preserve watch history through the rename.

Common pitfalls

A movie shows up multiple times in my library. Check whether the trailers, featurettes, or clips live next to the primary file rather than inside one of the recognised subfolder names (trailers, featurettes, other, and the rest in the table above). Filename based extras need the -trailer, -deleted, or -sample suffix on the primary's name.

The wrong file is the primary. Aviato picks any video in the folder that does not match an extras rule. If a behind the scenes clip is named like a regular movie file (Inception Making Of.mkv, with no featurettes parent and no -behind-the-scenes suffix), it competes for the primary slot. Move it into a featurettes folder or rename it.

Subtitles do not attach. Subtitles pair by filename. Inception (2010).en.srt works; subtitles.srt does not. Rename so the subtitle name starts with the primary's name.

My folder contains two unrelated movies. Aviato treats every primary video in a folder as part of the same item. Split unrelated movies into separate folders.

A wrapper folder from a release group contains the primary. A layout like Inception (2010)/Inception.2010.1080p.WEB-DL.GROUP/Inception.mkv works fine on its own: Aviato treats the deepest folder containing the primary as the item folder. But if you also have a sibling trailers folder at the outer level (next to the wrapper, not inside it), those trailers will not fold into the inner item. Either flatten the wrapper folder, or move the trailers inside it.