How po5/thumbfast works
This repository is a single-purpose mpv Lua extension that provides an on-demand thumbnail service for other UI scripts. The key architectural idea is that thumbfast does not draw any thumbnails by itself; it acts as a backend service inside mpv that UI scripts call when the user hovers over the seek bar.
Main components
1. thumbfast.lua
• The core runtime script loaded by mpv.
• It exposes a small script-message API that UI scripts can call.
• It manages thumbnail generation, state tracking, and the communication boundary between the UI and the thumbnail backend.
• It is designed to work with mpv’s Lua scripting environment, not as a standalone application.
2. thumbfast.conf
• The configuration surface for the script.
• Copied into mpv’s script-opts directory to override defaults.
• Defines the operational limits and environment-specific settings that shape the thumbnail pipeline.
Architectural boundaries
1. UI layer vs thumbnail backend
• The UI layer is external to this repo’s core logic. Examples include uosc, osc.lua, progressbar, ModernX, mpv.net frontends, and others.
• Those UIs compute the hovered playback time and cursor position, then request thumbnails from thumbfast.
• thumbfast is responsible for producing the thumbnail data, not deciding when or where the UI should render it.
2. Host mpv process vs background mpv process
• The script can launch or communicate with a separate mpv instance to do the actual thumbnail extraction.
• This is the main performance boundary: thumbnail generation is isolated from the main playback process so it does not block playback or UI responsiveness.
• The README explicitly calls out that a standalone mpv executable may be used in the background, especially for frontends like mpv.net or ImPlay.
3. Local temporary IPC/filesystem boundary
• On Linux and macOS, the script uses a temporary directory path for socket and file coordination.
• On Windows, the socket setting is a plain string.
• The thumbnail itself is written to a temporary file path.
• This means the thumbnail pipeline relies on local IPC and temporary filesystem artifacts rather than a remote service or persistent cache.
Data flow
1. User interaction
• The user hovers over the timeline in a compatible UI.
2. UI script computes request parameters
• The UI determines:
- the hovered timestamp in seconds
- the x/y position where the thumbnail should appear
• The UI then sends a script message to thumbfast.
3. thumbfast receives the request
• The script processes the incoming message and decides whether thumbnails are enabled and available.
• It may spawn the thumbnailer early if configured with spawn_first, or keep it alive depending on inactivity settings.
4. Thumbnail generation
• The backend generates a thumbnail for the requested timestamp.
• Generation can respect:
- maximum thumbnail dimensions
- scaling factor
- tone mapping
- cropping
- applied video filters
- hardware decoding, if enabled
- network/audio source handling, if allowed
5. Thumbnail availability and display metadata
• thumbfast maintains and publishes state such as thumbnail width, height, and availability.
• For standard UI integrations, the UI uses this state to place an overlay or image at the requested position.
• For advanced integrations, the UI can use the thumbfast-render path to take full control of rendering once the thumbnail is ready.
Messaging/API shape
• UI to thumbfast:
- request thumbnail for a specific time and position
- clear thumbnail when leaving the seek bar
- optionally request render-oriented behavior
• thumbfast to UI:
- sends JSON-encoded state via thumbfast-info
- state includes width, height, disabled, and available flags
- advanced render flow returns a richer object with dimensions, coordinates, socket, thumbnail path, and overlay identifier
Configuration-driven behavior
The config file is important because it controls how thumbfast fits into different environments:
• socket and thumbnail: local coordination paths
• max_height, max_width: output size constraints
• scale_factor: display scaling
• tone_mapping: whether generated thumbnails match mpv’s tone-mapping behavior
• overlay_id: integration detail for UI rendering
• spawn_first, quit_after_inactivity: process lifecycle behavior
• network, audio, hwdec: whether thumbnails can be generated for streams, audio files, and with hardware decoding
• direct_io: Windows performance optimization
• mpv_path: which mpv binary the thumbnailer should use
External dependencies and environment
• Primary runtime: mpv with Lua scripting enabled.
• No third-party library dependencies are required by the script itself.
• The actual thumbnailer may depend on a separate mpv executable being available in the environment or bundled with the frontend.
• Older mpv versions are supported with some caveats; Linux versions before 0.33.0 may require socat.
• The script is intended to integrate with desktop mpv frontends and UI scripts rather than serve as a standalone service.
How to think about the architecture diagram
A good diagram would show:
• A user hovering over the seek bar in a UI script
• The UI script sending script messages into thumbfast.lua inside mpv
• thumbfast.lua coordinating with a background mpv thumbnailer process
• Temporary socket/file IPC between the two mpv instances
• thumbfast.lua returning thumbnail state/data back to the UI
• The UI rendering the thumbnail overlay at the requested screen position
The essential architectural theme is “event-driven, on-demand thumbnail generation with a clean split between UI rendering and thumbnail extraction.”
Main entry points: thumbfast.lua thumbfast.lua · thumbfast.conf thumbfast.conf
Components 12
Integration
External UI scripts and the on-demand rendering boundary.
- UI script · A seekbar or frontend script that detects hover position and requests thumbnails.
- Script API · The small script-message surface used by UIs to request, clear, or render thumbnails.
- thumbfast-info · JSON-encoded status published back to the UI with width, height, disabled, and available flags.
- Render data · Advanced render-oriented response containing dimensions, coordinates, socket, path, and overlay id.
Runtime
thumbfast running inside mpv and coordinating thumbnail requests.
- thumbfast.lua · Main runtime script loaded by mpv; manages state, requests, and backend coordination.
thumbfast.lua - Orchestrator · Tracks availability, request state, lifecycle behavior, and integration-specific response data.
- Host mpv · The main mpv process where thumbfast is loaded and where UI-facing state is exposed.
Backend
Background thumbnail generation and local coordination artifacts.
- Thumb mpv · A separate mpv instance used for thumbnail extraction so playback stays responsive.
- Temp IPC · Temporary socket and filesystem coordination between the two mpv instances.
- Thumb file · Temporary file path where the generated thumbnail image is written.
Config
User-tunable script options that shape the pipeline.
- thumbfast.conf · Configuration file copied into mpv’s script-opts directory to override defaults.
thumbfast.conf - Options · Controls thumbnail size, scaling, tone mapping, lifecycle, decoding, and environment paths.
Connections 12
- UI script → Script API: hover request · The UI computes timestamp and position, then asks thumbfast for a thumbnail.
- Script API → thumbfast.lua: invoke · Incoming script messages enter the mpv Lua runtime.
- thumbfast.lua → Orchestrator: coordinate · The main script delegates request handling, state tracking, and lifecycle decisions.
- Orchestrator → thumbfast.conf: read opts · Configuration values shape how the runtime behaves.
- thumbfast.conf → Options: defines · The config file supplies overridable operational limits and environment settings.
- Orchestrator → Host mpv: runs in · thumbfast executes inside the main playback process.
- Host mpv → Thumb mpv: spawn or connect · A separate mpv instance performs thumbnail extraction when needed.
- Thumb mpv → Temp IPC: exchange · The two mpv instances communicate through local sockets and temporary coordination paths.
- Temp IPC → Thumb file: writes · The thumbnail backend emits the image to a temporary file.
- thumbfast.lua → thumbfast-info: publish state · thumbfast sends JSON status back to the UI for availability and sizing.
- thumbfast.lua → Render data: advanced reply · The render-oriented flow returns richer placement and path data for custom UI drawing.
- UI script → Render data: render overlay · Advanced integrations consume the payload to place the thumbnail at the hovered position.