{"id":13713528,"url":"https://github.com/TheAMM/mpv_thumbnail_script","last_synced_at":"2025-05-06T23:32:18.077Z","repository":{"id":44665803,"uuid":"113217673","full_name":"TheAMM/mpv_thumbnail_script","owner":"TheAMM","description":"A Lua script to show preview thumbnails in mpv's OSC seekbar, sans external dependencies","archived":false,"fork":false,"pushed_at":"2023-08-07T06:43:15.000Z","size":2754,"stargazers_count":679,"open_issues_count":55,"forks_count":68,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-11-14T00:33:57.813Z","etag":null,"topics":["ffmpeg","lua","mpv","mpv-script","osc","preview","previewer","thumbnails"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheAMM.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}},"created_at":"2017-12-05T18:21:47.000Z","updated_at":"2024-11-12T15:43:18.000Z","dependencies_parsed_at":"2024-01-15T19:43:19.896Z","dependency_job_id":"ba55e60e-8031-46c7-bf1d-4843480d9b30","html_url":"https://github.com/TheAMM/mpv_thumbnail_script","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAMM%2Fmpv_thumbnail_script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAMM%2Fmpv_thumbnail_script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAMM%2Fmpv_thumbnail_script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAMM%2Fmpv_thumbnail_script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheAMM","download_url":"https://codeload.github.com/TheAMM/mpv_thumbnail_script/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252787531,"owners_count":21804277,"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":["ffmpeg","lua","mpv","mpv-script","osc","preview","previewer","thumbnails"],"created_at":"2024-08-02T23:01:38.771Z","updated_at":"2025-05-06T23:32:17.477Z","avatar_url":"https://github.com/TheAMM.png","language":"Lua","readme":"# `mpv_thumbnail_script.lua`\n\n[![](docs/mpv_thumbnail_script.gif \"Thumbnail preview for Sintel (2010) on mpv's seekbar\")](https://www.youtube.com/watch?v=a9cmt176WDI)\n[*Click the image (or here) to view a YouTube video of the script in action*](https://www.youtube.com/watch?v=a9cmt176WDI)\n\n*(You might also be interested in [`mpv_crop_script.lua`](https://github.com/TheAMM/mpv_crop_script))*\n\n----\n\n## What is it?\n\n`mpv_thumbnail_script.lua` is a script/replacement OSC for [mpv](https://github.com/mpv-player/mpv) to display preview thumbnails when hovering over the seekbar, without any external dependencies[\u003csup\u003e1\u003c/sup\u003e](#footnotes), cross-platform-ly[\u003csup\u003e2\u003c/sup\u003e](#footnotes)!\n\nThe script supports all four built-in OSC layouts, [as seen in this Youtube video](https://www.youtube.com/watch?v=WsfWmO41p8A).  \nThe script will also do multiple passes over the video, generating thumbnails with increasing frequency until the target is reached.\nThis allows you to preview the end of the file before every thumbnail has been generated.\n\n## How do I install it?\n\nGrab both the two `.lua`s from the [**releases page**](https://github.com/TheAMM/mpv_thumbnail_script/releases) and place them both to your mpv's `scripts` directory.\n\nFor example:\n  * Linux/Unix/Mac: `~/.config/mpv/scripts/mpv_thumbnail_script_server.lua` \u0026 `~/.config/mpv/scripts/mpv_thumbnail_script_client_osc.lua`\n  * Windows: `%APPDATA%\\mpv\\scripts\\mpv_thumbnail_script_server.lua` \u0026 `%APPDATA%\\mpv\\scripts\\mpv_thumbnail_script_client_osc.lua`\n\n(See the [Files section](https://mpv.io/manual/master/#files) in mpv's manual for more info.)\n\nYou should also read the [Configuration](#configuration) section.\n\nWhile the script doesn't need external dependencies and can work with mpv alone, it can also use FFmpeg for *slightly* faster thumbnail generation; just make sure `ffmpeg[.exe]` is in your `PATH` and `prefer_mpv` is set to `no` in your configuration.\n\n***However,*** FFmpeg does not support \"ordered chapters\" in MKVs (segment linking, ie. an `.mkv` references another `.mkv`), which can break the thumbnailing process. You have been warned.\n\nIn general, you should just use multiple worker scripts ([Configuration](#configuration)) instead of taking the FFmpeg-risk.\n\n**Note:** You will need a rather new version of mpv due to [the new binds](https://github.com/mpv-player/mpv/commit/957e9a37db6611fe0879bd2097131df5e09afd47#diff-5d10e79e2d65d30d34f98349f4ed08e4) used in the patched `osc.lua`.\n\n## How do I use it?\n\nJust open a file and hover over the seekbar!  \nAlthough by default, videos over an hour will require you to press the `T` (that's `shift+t`) keybind.\nYou may change this duration check in the configuration (`autogenerate_max_duration`).\n\n**Also of note:** the script does not manage the thumbnails in any way, you should clear the directory from time to time.\n\n## Configuration\n\n**Note!** Because this script replaces the built-in OSC, you will have to set `osc=no` in your mpv's [main config file](https://mpv.io/manual/master/#files).\n\n\n**Multithreading:**  \nThis script can use multiple concurrent thumbnailing jobs.  \nSimply copy the `mpv_thumbnail_script_server.lua` once or twice (`mpv_thumbnail_script_server-1.lua`, `mpv_thumbnail_script_server-2.lua`) and the workers will automatically register themselves with the core.  \nThis improves thumbnailing speed a bunch, but you will quickly max out your CPU - I recommend only having two or three copies of the script.  \n(Why multiple copies of the same file? mpv gives each script their own thread - easy multithreading!)\n\nTo adjust the script's options, create a file called `mpv_thumbnail_script.conf` inside your mpv's `lua-settings` directory.\n\nFor example:\n  * Linux/Unix/Mac: `~/.config/mpv/lua-settings/mpv_thumbnail_script.conf`\n  * Windows: `%APPDATA%\\mpv\\lua-settings\\mpv_thumbnail_script.conf`\n\n(See the [Files section](https://mpv.io/manual/master/#files) in mpv's manual for more info.)\n\n\n\nIn this file you may set the following options:\n```ini\n# The thumbnail cache directory.\n# On Windows this defaults to %TEMP%\\mpv_thumbs_cache,\n# and on other platforms to /tmp/mpv_thumbs_cache.\n# The directory will be created automatically, but must be writeable!\n# Use absolute paths, and take note that environment variables like %TEMP% are unsupported (despite the default)!\ncache_directory=/tmp/my_mpv_thumbnails\n# THIS IS NOT A WINDOWS PATH. COMMENT IT OUT OR ADJUST IT YOURSELF.\n\n# Whether to generate thumbnails automatically on video load, without a keypress\n# Defaults to yes\nautogenerate=[yes/no]\n\n# Only automatically thumbnail videos shorter than this (in seconds)\n# You will have to press T (or your own keybind) to enable the thumbnail previews\n# Set to 0 to disable the check, ie. thumbnail videos no matter how long they are\n# Defaults to 3600 (one hour)\nautogenerate_max_duration=3600\n\n# Use mpv to generate thumbnail even if ffmpeg is found in PATH\n# ffmpeg is slightly faster than mpv but lacks support for ordered chapters in MKVs,\n# which can break the resulting thumbnails. You have been warned.\n# Defaults to yes (don't use ffmpeg)\nprefer_mpv=[yes/no]\n\n# Explicitly disable subtitles on the mpv sub-calls\n# mpv can and will by default render subtitles into the thumbnails.\n# If this is not what you wish, set mpv_no_sub to yes\n# Defaults to no\nmpv_no_sub=[yes/no]\n\n# Enable to disable the built-in keybind (\"T\") to add your own, see after the block\ndisable_keybinds=[yes/no]\n\n# The maximum dimensions of the thumbnails, in pixels\n# Defaults to 200 and 200\nthumbnail_width=200\nthumbnail_height=200\n\n# The thumbnail count target\n# (This will result in a thumbnail every ~10 seconds for a 25 minute video)\nthumbnail_count=150\n\n# The above target count will be adjusted by the minimum and\n# maximum time difference between thumbnails.\n# The thumbnail_count will be used to calculate a target separation,\n# and min/max_delta will be used to constrict it.\n\n# In other words, thumbnails will be:\n# - at least min_delta seconds apart (limiting the amount)\n# - at most max_delta seconds apart (raising the amount if needed)\n# Defaults to 5 and 90, values are seconds\nmin_delta=5\nmax_delta=90\n# 120 seconds aka 2 minutes will add more thumbnails only when the video is over 5 hours long!\n\n# Below are overrides for remote urls (you generally want less thumbnails, because it's slow!)\n# Thumbnailing network paths will be done with mpv (leveraging youtube-dl)\n\n# Allow thumbnailing network paths (naive check for \"://\")\n# Defaults to no\nthumbnail_network=[yes/no]\n# Override thumbnail count, min/max delta, as above\nremote_thumbnail_count=60\nremote_min_delta=15\nremote_max_delta=120\n\n# Try to grab the raw stream and disable ytdl for the mpv subcalls\n# Much faster than passing the url to ytdl again, but may cause problems with some sites\n# Defaults to yes\nremote_direct_stream=[yes/no]\n```\n(see [`src/options.lua`](/src/options.lua) for all possible options)\n\nWith `disable_keybind=yes`, you can add your own keybind to [`input.conf`](https://mpv.io/manual/master/#input-conf) with `script-binding generate-thumbnails`, for example:\n```ini\nshift+alt+s script-binding generate-thumbnails\n```\n\n## Development\n\nIncluded in the repository is the `concat_files.py` tool I use for automatically concatenating files upon their change, and also mapping changes to the output file back to the source files. It's really handy on stack traces when mpv gives you a line and column on the output file - no need to hunt down the right place in the source files!\n\nThe script requires Python 3, so install that. Nothing more, though. Call it with `concat_files.py cat_osc.json`.\n\nYou may also, of course, just `cat` the files together yourself. See the [`cat_osc.json`](cat_osc.json)/[`cat_server.json`](cat_server.json) for the order.\n\n### Donation\n\nIf you *really* get a kick out of this (weirdo), you can [paypal me](https://www.paypal.me/TheAMM) or send bitcoins to `1K9FH7J3YuC9EnQjjDZJtM4EFUudHQr52d`. Just having the option there, is all.\n\n#### Footnotes\n\u003csup\u003e1\u003c/sup\u003eYou *may* need to add `mpv[.exe]` to your `PATH` (and *will* have to add `ffmpeg[.exe]` if you want faster generation).\n\n\u003csup\u003e2\u003c/sup\u003eDeveloped \u0026 tested on Windows and Linux (Ubuntu), but it *should* work on Mac and whatnot as well, if \u003csup\u003e1\u003c/sup\u003e has been taken care of.\n","funding_links":["https://www.paypal.me/TheAMM"],"categories":["Lua","On Screen Controller"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheAMM%2Fmpv_thumbnail_script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheAMM%2Fmpv_thumbnail_script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheAMM%2Fmpv_thumbnail_script/lists"}