# po5/thumbfast architecture

> Architecture diagram of the GitHub repository po5/thumbfast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/po5/thumbfast
- Repository: https://github.com/po5/thumbfast

## Overview

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`](https://github.com/po5/thumbfast/blob/HEAD/thumbfast.lua) (thumbfast.lua), [`thumbfast.conf`](https://github.com/po5/thumbfast/blob/HEAD/thumbfast.conf) (thumbfast.conf)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Integration"
  ui_script(("UI script<br/>external ui"))
  script_api{{"Script API<br/>message api"}}
  info_channel{{"thumbfast-info<br/>state channel"}}
  render_payload["Render data<br/>render contract"]
end

subgraph "Runtime"
  thumbfast_lua["thumbfast.lua<br/>mpv lua<br/>[thumbfast.lua]"]
  orchestrator["Orchestrator<br/>state coordinator"]
  host_mpv[("Host mpv<br/>playback process")]
end

subgraph "Backend"
  thumb_mpv[("Thumb mpv<br/>background mpv")]
  ipc["Temp IPC<br/>local ipc"]
  thumb_file["Thumb file<br/>temp output"]
end

subgraph "Config"
  thumbfast_conf["thumbfast.conf<br/>script opts<br/>[thumbfast.conf]"]
  options["Options<br/>runtime settings"]
end

ui_script -->|"hover request"| script_api
script_api -->|"invoke"| thumbfast_lua
thumbfast_lua -->|"coordinate"| orchestrator
orchestrator -->|"read opts"| thumbfast_conf
thumbfast_conf -->|"defines"| options
orchestrator -->|"runs in"| host_mpv
host_mpv -->|"spawn or connect"| thumb_mpv
thumb_mpv -->|"exchange"| ipc
ipc -->|"writes"| thumb_file
thumbfast_lua -->|"publish state"| info_channel
thumbfast_lua -->|"advanced reply"| render_payload
ui_script -->|"render overlay"| render_payload

click thumbfast_lua "https://github.com/po5/thumbfast/blob/master/thumbfast.lua"
click thumbfast_conf "https://github.com/po5/thumbfast/blob/master/thumbfast.conf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class ui_script,script_api,info_channel,render_payload toneBlue
class thumbfast_lua,orchestrator,host_mpv toneAmber
class thumb_mpv,ipc,thumb_file toneMint
class thumbfast_conf,options toneRose
```

## Components

### Integration

External UI scripts and the on-demand rendering boundary.

- **UI script**: external ui · A seekbar or frontend script that detects hover position and requests thumbnails.
- **Script API**: message api · The small script-message surface used by UIs to request, clear, or render thumbnails.
- **thumbfast-info**: state channel · JSON-encoded status published back to the UI with width, height, disabled, and available flags.
- **Render data**: render contract · Advanced render-oriented response containing dimensions, coordinates, socket, path, and overlay id.

### Runtime

thumbfast running inside mpv and coordinating thumbnail requests.

- [thumbfast.lua](https://github.com/po5/thumbfast/blob/HEAD/thumbfast.lua): mpv lua · Main runtime script loaded by mpv; manages state, requests, and backend coordination. · `thumbfast.lua`
- **Orchestrator**: state coordinator · Tracks availability, request state, lifecycle behavior, and integration-specific response data.
- **Host mpv**: playback process · 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**: background mpv · A separate mpv instance used for thumbnail extraction so playback stays responsive.
- **Temp IPC**: local ipc · Temporary socket and filesystem coordination between the two mpv instances.
- **Thumb file**: temp output · Temporary file path where the generated thumbnail image is written.

### Config

User-tunable script options that shape the pipeline.

- [thumbfast.conf](https://github.com/po5/thumbfast/blob/HEAD/thumbfast.conf): script opts · Configuration file copied into mpv’s script-opts directory to override defaults. · `thumbfast.conf`
- **Options**: runtime settings · Controls thumbnail size, scaling, tone mapping, lifecycle, decoding, and environment paths.

## Connections

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