Previews

Preview thumbnails

What QuickView generation does, why it takes a while on big libraries, and how to speed it up.

5 min read

When you scrub the timeline, tofa shows preview thumbnails of the video. We call this QuickView. Generating those previews means decoding every file in your library once, so on a large library the first pass can take a day or more. That's expected, and it's a one-time cost: once a file has previews, tofa never regenerates them unless you change the preview settings or the file itself changes.

By default, generation runs at the lowest CPU priority, so it never gets in the way of playback or anything else on the machine. If your server has headroom and you'd rather get it done fast, you can turn it up. If you'd rather it only run at night, turn on the generation window below.

Speed it up#

Everything lives in Settings, QuickView Generation on your server's admin page. Changes apply live, including to a run that's already in progress. No restart needed.

Setting	Default	For a faster pass
Worker concurrency	4	Each worker processes one file, so more workers means roughly proportional throughput. Goes up to 8, or down to 1 for a very gentle pass.
Process priority	19 (lowest)	Lower numbers mean higher priority. 19 yields to everything; 0 competes like a normal process.
Process threads	Auto	Threads per file. Usually fine on auto; concurrency matters more.
Keyframe-only extraction	Off	The biggest single speedup. Seeks straight to keyframes instead of decoding every frame. Thumbnails can land slightly off their exact timestamp, which most people never notice.
Hardware acceleration	On	Uses your GPU to decode, following the hardware transcoding setting. Helps most with 4K and HEVC libraries, and falls back to software automatically.

Run it only at night#

Turn on Generation window in the same settings card to restrict generation to a daily time window, for example 00:00 to 06:00. Outside the window the queue simply waits; a file that is mid-generation when the window closes finishes normally. Combined with a higher worker concurrency this gives you a fast overnight pass with zero daytime impact.

Where previews are stored#

Previews live under the QuickView data path (Settings, QuickView Generation). On Docker installs this resolves to your /data volume, so previews survive container updates. If you run an older version and previews seem to regenerate after every update, update the server: earlier Docker builds kept previews inside the container by mistake, and they regenerate one final time after moving to a current build.

Moving the data path on a native Linux install#

Previews can take real space on a big library, so pointing the data path at larger storage (a NAS share, a second disk) is a common move. On a native Linux install there is one extra step: the tofa service runs sandboxed by systemd, and can only write to the locations listed in its service file. If you move the data path somewhere new, previews fail with log lines like "failed to create chapter images directory: Read-only file system" until you allow it.

Add the new location to the service file at /etc/systemd/system/tofa.service, next to the existing entries:

ReadWritePaths=/mnt/tofa

Then reload and restart:

sudo systemctl daemon-reload && sudo systemctl restart tofa

The same applies to any other writable location you configure in Settings, such as a database backup folder. Docker installs are not affected; there, the data path just needs to be inside a mounted volume.

What affects the total amount of work#

These settings change how much there is to generate, not just how fast it goes. Changing them after a library is done regenerates previews for that library:

Interval (default 10 seconds): how far apart thumbnails are. A larger interval means fewer frames per file.
Resolutions (default 320px): each extra resolution multiplies the work.
High quality previews and JPEG quality: higher quality means larger files and slightly slower encodes.

Each resolution is a separate scrub-tile track, and players pick the one that suits the connection, just like a video quality level. The small 320px track keeps scrubbing smooth over remote and relay connections, while the larger 640px track looks crisper on big screens. Keep both for the best experience; drop to a single track only when you are tight on storage. Removing a resolution just stops generating it for files scanned from then on. Previews already on disk are kept exactly as they are, so shrinking the list never deletes anything or triggers a full rebuild.

Per-library control#

Each library chooses its own preview mode under the library's settings:

Off: no previews for this library.
On demand: previews are generated only for titles people actually play, starting the moment playback begins. Nothing is generated up front, so a huge library costs no disk or CPU until someone watches something. Scrub previews for a title usually appear within a few minutes of first play.
Full library: previews are generated for everything as scans find it. Best scrubbing experience everywhere, at the cost of an upfront generation pass over the whole library.

On demand is a good fit for big archives where only a fraction gets watched. You can switch a library to Full library later and the queue picks up whatever is still missing.

Whichever mode is set, starting playback on a title without previews moves it to the front of the generation queue.

Checking progress#

The generation queue runs in the background and survives restarts. The Libraries admin page shows a live "QuickView x/y jobs" count on each library's row while a run is active, and each library's QuickView tab shows how much of it is covered. If it looks stuck, it's usually just a very long file; each file is processed start to finish before the worker moves on.