thumbfast

High-performance on-the-fly thumbnailer for mpv.

The script does not display thumbnails on its own, it is meant to be used alongside a UI script that calls thumbfast.

Preview of thumbfast on different UIs

Installation

Place thumbfast.lua in your mpv scripts folder.
Default settings are listed in thumbfast.conf, copy it to your mpv script-opts folder to customize.

For the vanilla UI, you also have to install osc.lua (identical to the mpv default, with added thumbfast support) into your scripts folder.
For third-party UIs, refer to their respective installation instructions. See the list of supported UIs.

Features

No dependencies, no background thumbnail generation hogging your CPU.
Customizable sizes, interval between thumbnails, cropping support, respects applied video filters.
Supports web videos e.g. YouTube (disabled by default), mixed aspect ratio videos.

This script makes an effort to run on mpv versions as old as 0.29.0 (Windows, Linux) and 0.33.0 (Mac).
Note that most custom UIs will not support vintage mpv builds, update before submitting an issue and mention if behavior is the same.
Support for <0.33.0 on Linux requires socat.

Usage

Once the lua file is in your scripts directory, and you are using a UI that supports thumbfast, you are done.
Hover on the timeline for nice thumbnails.

UI support

• uosc
• osc.lua (use this fork for vanilla UI)
• progressbar
• tethys (PR pending, lua)
• modern (separate branch)
• ModernX
• oscc
• mfpbar

mpv frontends

If you are using a GUI frontend such as mpv.net, you will need standalone mpv accessible within Path.
The easiest way is to copy standalone mpv files inside of your mpv.net installation folder.
It will be used in the background to generate thumbnails.

The only exception is ImPlay, which can do thumbnailing on its own.
Set mpv_path=ImPlay in script-opts/thumbfast.conf.

MacOS

If your mpv install is an app bundle (e.g. stolendata builds), the script will work but you may notice the Dock shakes when generating the first thumbnail.
To get rid of the shaking, make sure the app is in your Applications folder, then run: sudo ln -s /Applications/mpv.app/Contents/MacOS/mpv /usr/local/mpv
If you installed mpv via Homebrew, there are no issues.

Configuration

socket: On Windows, a plain string. On Linux and Mac, a directory path for temporary files. Leave empty for auto.
thumbnail: Path for the temporary thumbnail file (must not be a directory). Leave empty for auto.
max_height, max_width: Maximum thumbnail generation size in pixels (scaled down to fit). Values are scaled when hidpi is enabled. Defaults to 200x200.
scale_factor: Scale factor for thumbnail display size (requires mpv 0.38+). Lower quality than increasing max_height and max_width. Defaults to 1.
tone_mapping: Apply tone-mapping, no to disable. Defaults to auto, which copies your mpv config.
overlay_id: Overlay id for thumbnails. Leave blank unless you know what you're doing.
spawn_first: Spawn thumbnailer on file load for faster initial thumbnails. Defaults to no.
quit_after_inactivity: Close thumbnailer process after an inactivity period in seconds. Defaults to 0 (disabled).
network: Enable on remote files. Defaults to no.
audio: Enable on audio files. Defaults to no.
hwdec: Enable hardware decoding. Defaults to no.
direct_io: Windows only: write directly to pipe (requires LuaJIT). Should improve performance, ymmv.
mpv_path: Custom path to the mpv executable. Defaults to mpv.

For UI developers: How to add thumbfast support to your script

This API usage example code is CC0 (public domain).

Declare the thumbfast state variable near the top of your script.
Do not manually modify those values, they are automatically updated by the script and changes will be overwritten.

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

Register the state setter near the end of your script, or near where your other script messages are.
You are expected to have required mp.utils (for this example, into a utils variable).

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)

Now for the actual functionality. You are in charge of supplying the time hovered (in seconds), and x/y coordinates for the top-left corner of the thumbnail.
In this example, the thumbnail is horizontally centered on the cursor, respects a 10px margin on both sides, and displays 10px above the cursor.
This code should be run when the user hovers on the seekbar. Don't worry even if this is called on every render, thumbfast won't be bogged down.

-- below are examples of what these values may look like
-- margin_left = 10
-- margin_right = 10
-- cursor_x, cursor_y = mp.get_mouse_pos()
-- display_width = mp.get_property_number("osd-width")
-- hovered_seconds = video_duration * cursor_x / display_width

if not thumbfast.disabled then
    mp.commandv("script-message-to", "thumbfast", "thumb",
        -- hovered time in seconds
        hovered_seconds,
        -- x
        math.min(display_width - thumbfast.width - margin_right, math.max(margin_left, cursor_x - thumbfast.width / 2)),
        -- y
        cursor_y - 10 - thumbfast.height
    )
end

This code should be run when the user leaves the seekbar.

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

If you did all that, your script can now display thumbnails!
Look at existing integrations for more concrete examples.

If positioning isn't enough and you want complete control over rendering:
Register a thumbfast-render script message.
When requesting the thumbnail, set x and y to empty strings and supply your script's name as the 4th argument.
You will recieve a json object with the keys width, height, x, y, socket, thumbnail, overlay_id when the thumbnail is ready.