Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/po5/thumbfast

High-performance on-the-fly thumbnailer script for mpv
https://github.com/po5/thumbfast

mpv mpv-script preview thumbnails

Last synced: 2 days ago
JSON representation

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

Lists

README 

        
# 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](https://user-images.githubusercontent.com/42466980/199102896-65f9e989-4189-4734-82a7-bda8ee63c7a6.webm)



## 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](https://github.com/po5/thumbfast/blob/vanilla-osc/player/lua/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.](#ui-support)



## 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](https://github.com/tomasklaen/uosc)

- [osc.lua](https://github.com/po5/thumbfast/blob/vanilla-osc/player/lua/osc.lua) (use this fork for vanilla UI)

- [progressbar](https://github.com/torque/mpv-progressbar)

- [tethys](https://github.com/Zren/mpv-osc-tethys) (PR pending, [lua](https://github.com/po5/mpv-osc-tethys/blob/thumbfast/osc_tethys.lua))

- [modern](https://github.com/maoiscat/mpv-osc-modern/tree/with.thumbfast) (separate branch)

- [ModernX](https://github.com/cyl0/ModernX)

- [oscc](https://github.com/longtermfree/oscc)

- [mfpbar](https://codeberg.org/NRK/mpv-toolbox/src/branch/master/mfpbar)



## mpv frontends

If you are using a GUI frontend such as [mpv.net](https://github.com/mpvnet-player/mpv.net), you will need [standalone mpv](https://mpv.io/installation/) accessible within [Path](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)#to-add-a-path-to-the-path-environment-variable).  

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](https://tsl0922.github.io/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](https://brew.sh/), 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)](https://creativecommons.org/share-your-work/public-domain/cc0/).



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.*

```lua

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).

```lua

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.

```lua

-- 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.

```lua

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.