How scanning works

When ZiiX.TV scans your libraries, what a scan does with new, changed and removed files, and the work that follows: metadata, seek-bar pictures and intro detection.

ZiiX.TV keeps your libraries in step with your folders by itself. You can also start a scan by hand.

When libraries are scanned

  • When the server starts, since files may have changed while it was off.
  • Every 15 minutes after that. Set ZIIX_SCAN_INTERVAL to change it, for example 30m or 1h; 0 turns automatic scans off.
  • When you add a library, at once.
  • By hand: Scan next to the library under Settings → Libraries.
  • When you change a library’s type between Movies and Shows, since the names are then read with other rules.

Only one scan runs per library at a time.

What a scan does

  1. Finds what changed. ZiiX.TV remembers each file’s size and modification time. Files that are unchanged are not read again, so a scan of a big library that has not changed takes seconds.
  2. Reads new and changed files with ffprobe: length, container, video and audio codecs, resolution, HDR, Dolby Vision and Atmos. Four files are read at a time.
  3. Removes files that are gone, with their watch history. A title with no files left is removed.
  4. Groups files into titles from their names; see how to name files.
  5. Looks up new titles in TMDB or TheTVDB; see metadata.

During a long first scan, titles start to appear within about 15 seconds; you do not have to wait for the scan to end. The web app and the apps update by themselves while it runs.

When the media folder is missing

If a library that had files suddenly has none (a network share that is not mounted, a disk that is off), the scan stops and removes nothing. The library shows the error, and the next scan carries on as normal once the folder is back.

Files that could not be read

If ffprobe cannot read a file, it is still added and can be played, but without length and codec details. The library shows how many files could not be read.

What happens after a scan

Each scan wakes up three jobs in the background:

  • Metadata for new titles.
  • Seek-bar pictures: one picture every 10 seconds of each video, so you can see where you are going when you drag the seek bar. They are kept in /previews. A file you start playing goes first.
  • Intro and credits detection: ZiiX.TV listens to the episodes of each season, and the stretch of sound they share near the start is the intro (15 seconds to 2½ minutes). The end credits are found the same way. This gives Skip intro and the Next episode countdown.

The seek-bar pictures and intro detection use the CPU and can each be turned off under Settings → Server. They are then made when a file or season is first played instead.

Watching it happen

  • Settings → Libraries shows each library’s state: Scanning… N files found, the time of the last scan, or the error.
  • Settings → System shows the server’s log and what it is running now.