{"id":13814662,"url":"https://github.com/po5/thumbfast","last_synced_at":"2025-10-31T08:09:25.893Z","repository":{"id":59631219,"uuid":"536318034","full_name":"po5/thumbfast","owner":"po5","description":"High-performance on-the-fly thumbnailer script for mpv","archived":false,"fork":false,"pushed_at":"2024-08-02T09:58:04.000Z","size":484,"stargazers_count":793,"open_issues_count":30,"forks_count":37,"subscribers_count":35,"default_branch":"master","last_synced_at":"2024-08-04T04:06:08.091Z","etag":null,"topics":["mpv","mpv-script","preview","thumbnails"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/po5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-13T21:43:07.000Z","updated_at":"2024-08-02T21:02:31.000Z","dependencies_parsed_at":"2023-11-11T09:20:55.280Z","dependency_job_id":"8eb1314d-ae3d-4ba9-8844-6b23f153ab95","html_url":"https://github.com/po5/thumbfast","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/po5%2Fthumbfast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/po5%2Fthumbfast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/po5%2Fthumbfast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/po5%2Fthumbfast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/po5","download_url":"https://codeload.github.com/po5/thumbfast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225326532,"owners_count":17456963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mpv","mpv-script","preview","thumbnails"],"created_at":"2024-08-04T04:02:26.545Z","updated_at":"2025-10-31T08:09:25.776Z","avatar_url":"https://github.com/po5.png","language":"Lua","funding_links":[],"categories":["Image","Lua","others"],"sub_categories":[],"readme":"# thumbfast\nHigh-performance on-the-fly thumbnailer for mpv.\n\n**The script does not display thumbnails on its own,** it is meant to be used alongside a UI script that calls thumbfast.\n\n[Preview of thumbfast on different UIs](https://user-images.githubusercontent.com/42466980/199102896-65f9e989-4189-4734-82a7-bda8ee63c7a6.webm)\n\n## Installation\nPlace thumbfast.lua in your mpv `scripts` folder.  \nDefault settings are listed in thumbfast.conf, copy it to your mpv `script-opts` folder to customize.\n\nFor 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.  \nFor third-party UIs, refer to their respective installation instructions. [See the list of supported UIs.](#ui-support)\n\n## Features\nNo dependencies, no background thumbnail generation hogging your CPU.  \nCustomizable sizes, interval between thumbnails, cropping support, respects applied video filters.  \nSupports web videos e.g. YouTube (disabled by default), mixed aspect ratio videos.\n\nThis script makes an effort to run on mpv versions as old as 0.29.0 (Windows, Linux) and 0.33.0 (Mac).  \nNote that most custom UIs will not support vintage mpv builds, update before submitting an issue and mention if behavior is the same.  \nSupport for \u003c0.33.0 on Linux requires socat.\n\n## Usage\nOnce the lua file is in your scripts directory, and you are using a UI that supports thumbfast, you are done.  \nHover on the timeline for nice thumbnails.\n\n## UI support\n- [uosc](https://github.com/tomasklaen/uosc)\n- [osc.lua](https://github.com/po5/thumbfast/blob/vanilla-osc/player/lua/osc.lua) (use this fork for vanilla UI)\n- [progressbar](https://github.com/torque/mpv-progressbar)\n- [tethys](https://github.com/Zren/mpv-osc-tethys) (PR pending, [lua](https://github.com/po5/mpv-osc-tethys/blob/thumbfast/osc_tethys.lua))\n- [modern](https://github.com/maoiscat/mpv-osc-modern/tree/with.thumbfast) (separate branch)\n- [ModernX](https://github.com/cyl0/ModernX)\n- [oscc](https://github.com/longtermfree/oscc)\n- [mfpbar](https://codeberg.org/NRK/mpv-toolbox/src/branch/master/mfpbar)\n\n## mpv frontends\n[ImPlay](https://tsl0922.github.io/ImPlay/) is auto-detected, but if you encounter issues set `mpv_path=ImPlay` in `script-opts/thumbfast.conf`.\n\n[mpv.net](https://github.com/mpvnet-player/mpv.net) is directly supported since v7, no special configuration is required.\n\nOther frontends and older versions of mpv.net 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).  \nThe easiest way is to copy standalone mpv files inside of your frontend's installation folder.\nIt will be used in the background to generate thumbnails.\n\n## MacOS\nIf 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.  \nTo 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`  \nIf you installed mpv via [Homebrew](https://brew.sh/), there are no issues.\n\n## Configuration\n`socket`: On Windows, a plain string. On Linux and Mac, a directory path for temporary files. Leave empty for auto.  \n`thumbnail`: Path for the temporary thumbnail file (must not be a directory). Leave empty for auto.  \n`max_height`, `max_width`: Maximum thumbnail generation size in pixels (scaled down to fit). Values are scaled when hidpi is enabled. Defaults to 200x200.  \n`scale_factor`: Scale factor for thumbnail display size (requires mpv 0.38+). Lower quality than increasing max_height and max_width. Defaults to 1.  \n`tone_mapping`: Apply tone-mapping, no to disable. Defaults to auto, which copies your mpv config.  \n`overlay_id`: Overlay id for thumbnails. Leave blank unless you know what you're doing.  \n`spawn_first`: Spawn thumbnailer on file load for faster initial thumbnails. Defaults to no.  \n`quit_after_inactivity`: Close thumbnailer process after an inactivity period in seconds. Defaults to 0 (disabled).  \n`network`: Enable on remote files. Defaults to no.  \n`audio`: Enable on audio files. Defaults to no.  \n`hwdec`: Enable hardware decoding. Defaults to no.  \n`direct_io`: Windows only: write directly to pipe (requires LuaJIT). Should improve performance, ymmv.  \n`mpv_path`: Custom path to the mpv executable. Defaults to mpv.\n\n## For UI developers: How to add thumbfast support to your script\nThis API usage example code is [CC0 (public domain)](https://creativecommons.org/share-your-work/public-domain/cc0/).\n\nDeclare the thumbfast state variable near the top of your script.  \n*Do not manually modify those values, they are automatically updated by the script and changes will be overwritten.*\n```lua\nlocal thumbfast = {\n    width = 0,\n    height = 0,\n    disabled = true,\n    available = false\n}\n```\nRegister the state setter near the end of your script, or near where your other script messages are.  \nYou are expected to have required `mp.utils` (for this example, into a `utils` variable).\n```lua\nmp.register_script_message(\"thumbfast-info\", function(json)\n    local data = utils.parse_json(json)\n    if type(data) ~= \"table\" or not data.width or not data.height then\n        msg.error(\"thumbfast-info: received json didn't produce a table with thumbnail information\")\n    else\n        thumbfast = data\n    end\nend)\n```\nNow 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.  \nIn this example, the thumbnail is horizontally centered on the cursor, respects a 10px margin on both sides, and displays 10px above the cursor.  \nThis 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.\n```lua\n-- below are examples of what these values may look like\n-- margin_left = 10\n-- margin_right = 10\n-- cursor_x, cursor_y = mp.get_mouse_pos()\n-- display_width = mp.get_property_number(\"osd-width\")\n-- hovered_seconds = video_duration * cursor_x / display_width\n\nif not thumbfast.disabled then\n    mp.commandv(\"script-message-to\", \"thumbfast\", \"thumb\",\n        -- hovered time in seconds\n        hovered_seconds,\n        -- x\n        math.min(display_width - thumbfast.width - margin_right, math.max(margin_left, cursor_x - thumbfast.width / 2)),\n        -- y\n        cursor_y - 10 - thumbfast.height\n    )\nend\n```\nThis code should be run when the user leaves the seekbar.\n```lua\nif thumbfast.available then\n    mp.commandv(\"script-message-to\", \"thumbfast\", \"clear\")\nend\n```\nIf you did all that, your script can now display thumbnails!  \nLook at existing integrations for more concrete examples.\n\nIf positioning isn't enough and you want complete control over rendering:  \nRegister a `thumbfast-render` script message.  \nWhen requesting the thumbnail, set x and y to empty strings and supply your script's name as the 4th argument.  \nYou will recieve a json object with the keys `width`, `height`, `x`, `y`, `socket`, `thumbnail`, `overlay_id` when the thumbnail is ready.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpo5%2Fthumbfast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpo5%2Fthumbfast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpo5%2Fthumbfast/lists"}