thumbfast: On-demand mpv timeline thumbnails

Why thumbfast sits behind an mpv user interface

thumbfast solves a specific problem in mpv: creating a preview image for the point being hovered on a seekbar without first generating thumbnails for the entire file. It is intended for mpv users who want timeline previews and for UI developers who maintain seekbars capable of sending mouse positions to a thumbnail backend.

The script is not a complete user interface. The README states plainly that it does not display thumbnails on its own. A compatible UI supplies the hovered time in seconds and the top-left coordinates for the preview, while thumbfast maintains a separate overlay. This division matters during setup. Installing only `thumbfast.lua` does not make an ordinary timeline show previews by itself.

The documented integrations include uosc, a thumbfast-compatible fork of osc.lua, progressbar, tethys, modern, ModernX, oscc, and mfpbar. Tethys is marked as having a pull request pending, while modern uses a separate branch. These qualifiers make the support list operational rather than a blanket compatibility guarantee. A UI must actually call thumbfast through its messages.

thumbfast also targets mixed aspect ratios and respects applied video filters. That makes it more relevant than a simple fixed-size screen capture for filtered or unusual video sources. However, remote media is disabled by default through the `network` option, so YouTube support described by the project is opt-in rather than an automatic benefit.

How hover requests become an overlay preview

The UI integration follows an explicit message flow. A UI declares a state table, listens for `thumbfast-info`, and sends either `thumbfast` or `clear` with `mp.commandv`. The state contains automatic values that the UI developer should not modify.

A supported UI can begin with this public-domain API example:

local thumbfast = {
    width = 0,
    height = 0,
    disabled = true,
    available = false
}

The UI then registers a handler for updates from thumbfast. The handler parses the JSON message and replaces its local state when thumbnail dimensions are present.

mp.register_script_message("thumbfast-info", function(json)
    local data = utils.parse_json(json)
    if type(data) ~= "table" or not data.width or not data.height then
        msg.error("thumbfast-info: received json didn't produce a table with thumbnail information")
    else
        thumbfast = data
    end
end)

When the pointer enters the seekbar, the UI sends the hovered media time plus x and y coordinates to the `thumbfast` script. The README says it is safe for this call to occur on every render because thumbfast will not be burdened by every invocation. The UI also decides how to center the image, preserve margins, and place it above the cursor.

When the pointer leaves, a UI can remove the overlay by sending `clear`, but only when `thumbfast.available` is true:

if thumbfast.available then
    mp.commandv("script-message-to", "thumbfast", "clear")
end

This protocol is why thumbfast is a backend library rather than a drop-in preview package. It gives the UI control over pointer input and placement, while thumbfast handles thumbnail state and overlay output.

Installing thumbfast for the first seekbar preview

The installation is filesystem-based because this repository is an mpv Lua script, not a package with a documented package-manager installation command. Place `thumbfast.lua` in the mpv `scripts` folder. Copy `thumbfast.conf` into the `script-opts` folder only if you want to change the defaults.

A vanilla UI needs one additional file. The README directs users to the repository's `vanilla-osc` version of `osc.lua` and says it should be placed in the same mpv `scripts` folder. For a third-party interface, follow that interface's own installation instructions and confirm that it supports thumbfast.

After the required files are present, start or reload mpv through its normal frontend, place the pointer over the timeline, and move it along the seekbar. A working setup should request previews only when the pointer reaches a seekbar handled by a compatible UI. The README does not document a thumbfast-specific reload command, so no such command should be inferred.

ImPlay is automatically detected according to the README. If detection fails, the documented workaround is to place `mpv_path=ImPlay` in `script-opts/thumbfast.conf`. mpv.net version 7 or later is directly supported without special configuration. Older mpv.net versions and other frontends require a standalone mpv executable available through `Path`; the README also says that copying standalone mpv files into the frontend installation folder is the easiest approach.

On macOS, an application-bundle installation may shake in the Dock when the first thumbnail is generated. The README says Homebrew installations do not have this issue. For affected app-bundle setups, it gives this specific symlink command:

sudo ln -s /Applications/mpv.app/Contents/MacOS/mpv /usr/local/mpv

The project says placing the app in the Applications folder and creating that link removes the shaking behavior.

Configuration boundaries for size, filters, and remote files

The defaults prioritize small previews and conservative process use. `max_height` and `max_width` limit generated thumbnail dimensions and default to 200 by 200 pixels. When hidpi is active, those values are scaled. `scale_factor` changes display size but requires mpv 0.38 or later, and the README explicitly rates that route as lower quality than increasing `max_height` and `max_width`.

`tone_mapping` defaults to `auto`, which copies the mpv configuration, and can be disabled. Applied video filters are respected according to the feature list. `overlay_id` exists but should remain blank unless its behavior is known, which makes it a poor setting to change experimentally during first setup.

Several options control when the thumbnailer process appears. `spawn_first` defaults to `no`; setting it to `yes` starts generation on file load to reduce the wait for initial thumbnails. `quit_after_inactivity` defaults to `0`, meaning the process is not closed after inactivity. These choices trade startup responsiveness against process lifetime.

`network` controls remote files and defaults to `no`, despite the README identifying web videos such as YouTube as a supported use case. `audio` also defaults to `no`. `hwdec` defaults to `no`. On Windows, `direct_io` writes directly to a pipe and requires LuaJIT, with performance described conditionally rather than guaranteed for every installation.

The `socket` and `thumbnail` paths can be left empty for automatic selection. On Windows, `socket` is a plain string; on Linux and Mac, it is a temporary-file directory path. `thumbnail` must identify a file rather than a directory. These platform distinctions are important when placing the script in managed frontend environments, where the automatic path may not be available.

mpv versions, frontends, and the external-process constraint

thumbfast attempts compatibility with old mpv releases: 0.29.0 or newer on Windows and Linux, and 0.33.0 or newer on macOS. Linux versions below 0.33.0 require socat. That is a stated compatibility goal, not a claim that every UI works with every vintage build. The README specifically warns that custom UIs may not support old mpv versions.

A frontend can affect how thumbnails are generated. ImPlay has automatic detection and a documented `mpv_path` override. mpv.net 7 and later has direct support. Other frontends, including older mpv.net releases, need standalone mpv accessible in `Path`; thumbfast uses it in the background to generate thumbnails.

This external dependency is the main operational distinction from a UI that already runs inside a sufficiently capable mpv installation. It creates more moving parts for packaged frontends, portable installations, and restricted environments. The README does not document a portable path format, a package-manager recipe, or a universal process-discovery strategy beyond `mpv_path`, so deployment behavior still depends on the host.

The documented `mpv_path` default is `mpv`. Changing it may therefore be necessary in a frontend that bundles a player under another name or location. However, the README does not provide an explicit path-discovery tutorial beyond the ImPlay override and the recommendation to expose standalone mpv through `Path`. Engineers integrating thumbfast should inspect the frontend's launch environment rather than assume that a desktop `PATH` entry is present.

Maintenance, releases, and MPL-2.0 obligations

The repository is not archived, and its last push was on 2026-08-12. The repository has no GitHub releases, so the README does not provide a tagged-release channel, upgrade note, or compatibility matrix tied to release versions. Updates are tied to repository commits and branches, including the separate `vanilla-osc` fork and the separate `with.thumbfast` branch used by modern.

That branch-based delivery increases upgrade work for UI integrations. A user may need to compare changes in `thumbfast.lua`, update the UI adapter, and account for frontend or mpv changes separately. The project offers no migration notes for those branches in the README.

The repository is licensed under MPL-2.0. The API usage example is identified by its author as CC0 public domain, so that example can be reused without following the repository license for the snippet itself. For the rest of the repository, file-level license obligations should be checked in the `LICENSE`. This article does not provide legal advice, but MPL-2.0 licensing is relevant to distributors that modify or redistribute covered files.

No package dependencies are required, according to the README, except for the platform conditions already noted, such as socat for older Linux mpv versions and LuaJIT for Windows `direct_io`. That keeps normal installation small, while optional compatibility paths introduce operating-system checks.

thumbfast versus a self-contained cached thumbnail generator

thumbfast differs from a self-contained generator that precomputes thumbnails and exposes them directly to its own UI. thumbfast does not own the seekbar, does not display previews independently, and explicitly avoids background generation that continuously consumes CPU. It generates what the compatible UI asks for at the hovered time.

That approach favors storage simplicity and responsiveness for ordinary local seeking. It also transfers responsibility for hover detection, coordinate calculation, overlay positioning, and clear behavior to the UI. A custom UI developer must implement the documented state and message protocol rather than install thumbfast and expect automatic integration.

A cached generator may better fit workflows that repeatedly revisit the same long file, but the README does not document such a competing project or establish comparative performance. The grounded comparison is architectural: thumbfast is request-driven and UI-integrated, whereas a pre-generation approach would spend resources and storage before requests arrive. thumbfast may be the wrong choice when the interface cannot send script messages, when no supported UI integration is available, or when a custom frontend cannot expose the required mpv executable.

Editorial conclusion

Adopt thumbfast if your mpv interface already supports its message API and you want timeline previews without generating a full thumbnail cache. Do not choose it as a standalone preview feature, for older mpv.net releases, or for unsupported frontends unless you can provide standalone mpv through Path. Verify UI compatibility, the required mpv version, frontend discovery, network thumbnail settings, and platform-specific process or socket behavior before replacing a working setup. For Linux releases older than 0.33.0, also confirm that socat is available.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. po5/thumbfast on GitHub
4. README