# soorajsprakash/mpv-seekpeek architecture

> Architecture diagram of the GitHub repository soorajsprakash/mpv-seekpeek, 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/soorajsprakash/mpv-seekpeek
- Repository: https://github.com/soorajsprakash/mpv-seekpeek

## Overview

This repository is a small, single-purpose mpv extension built around two Lua files:

- `main.lua`: the mpv-facing entry point that wires the feature into playback, seekbar interaction, keybindings, and OSD/overlay rendering.
- `helper.lua`: shared utility logic used by `main.lua` for tasks like path handling, cache-file naming, sprite math, and other support routines.

The architecture is intentionally lightweight and sits entirely inside mpv’s Lua scripting runtime, with FFmpeg used as an external generator process.

Main subsystems

1. mpv integration layer
   - Runs inside mpv as a Lua script.
   - Hooks into playback lifecycle events so sprite generation can start when a file begins playing.
   - Registers script bindings for manual generation, regeneration, preview toggling, and sprite deletion.
   - Receives hover/seekbar input from mpv’s UI and translates cursor position into preview requests.
   - Uses mpv’s overlay/OSD capabilities to display preview thumbnails directly in the player.

2. Sprite generation pipeline
   - Uses FFmpeg as an external process to generate a thumbnail sprite sheet for the current media file.
   - Generation is asynchronous so playback is not blocked.
   - The sprite is not generated frame-by-frame at hover time; it is precomputed once and cached.
   - The generated artifact is a raw BGRA sprite sheet, chosen because mpv’s overlay API can consume BGRA directly.

3. Cache and file-management layer
   - Stores generated sprite sheets in mpv’s cache directory.
   - Before launching FFmpeg, the script checks whether a sprite for the current video already exists.
   - If present, generation is skipped and previews become available immediately.
   - Supports optional cleanup behavior, including deleting the current file’s sprite on exit or on manual request.

4. Preview rendering and seek mapping
   - On hover, the script maps seekbar cursor position to a playback timestamp.
   - That timestamp is converted into a thumbnail index within the sprite grid.
   - The corresponding BGRA frame region is read from the sprite file and pushed to mpv’s overlay API.
   - This avoids extra image decoding and keeps hover preview rendering fast.

Data flow

1. Playback starts in mpv.
2. `main.lua` decides whether to auto-generate sprites based on config.
3. If needed, `main.lua` invokes FFmpeg asynchronously.
4. FFmpeg samples the video at a fixed interval, scales frames to the configured preview size, tiles them into a grid, and writes a raw BGRA sprite file.
5. The file is stored in mpv’s cache directory and reused on future plays of the same media.
6. When the user hovers over the seekbar, `main.lua` converts hover position to time, resolves the correct sprite cell, and extracts the matching BGRA region.
7. mpv renders that region as an overlay preview.

Important boundaries

- mpv boundary: Everything interactive happens through mpv’s Lua scripting APIs, keybinding system, overlay/OSD, and script options.
- external process boundary: FFmpeg is the only external computation engine; the Lua script does not decode video frames itself.
- cache boundary: Generated artifacts live outside the source tree in mpv’s cache directory, making previews persistent across sessions.
- configuration boundary: Behavior is controlled via `mpv_seekpeek.conf` or `--script-opts`, allowing runtime customization without code changes.

Configuration and control surface

The repository exposes several behavioral knobs that shape architecture:

- startup behavior: auto-start sprite generation or wait for a manual trigger
- cleanup behavior: delete sprites on exit or keep them cached
- UI behavior: enable/disable preview overlay and force fullscreen
- preview geometry: width, height, grid rows, grid columns
- sampling cadence: thumbnail interval controls how many source frames are sampled
- keybindings: configurable trigger keys for generate/regenerate/toggle/delete actions

These options make the system adaptable without changing the core pipeline.

Repository layout implications

- `README.md` is not just documentation; it effectively defines the contract between mpv, FFmpeg, and the script.
- `mpv_seekpeek.conf` is the sample configuration artifact that mirrors mpv’s script-options mechanism.
- `helper.lua` and `main.lua` are the only runtime code units, so the architecture is a compact two-module script rather than a multi-package application.

Overall architecture summary

This is an event-driven mpv plugin that precomputes seekbar thumbnails as a cached FFmpeg-generated BGRA sprite sheet, then uses mpv’s overlay API to render hover previews by mapping cursor position to sprite coordinates. The design is optimized for low runtime overhead: heavy work is done once in the background, while hover-time work is limited to simple coordinate math and direct overlay display.

Main entry points: [`main.lua`](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/main.lua) (main.lua), [`README.md`](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/README.md) (README), [`mpv_seekpeek.conf`](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/mpv_seekpeek.conf) (mpv_seekpeek.conf), [`helper.lua`](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/helper.lua) (helper.lua)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "mpv runtime"
  n_main["main.lua<br/>mpv script<br/>[main.lua]"]
  n_helper["helper.lua<br/>utility module<br/>[helper.lua]"]
  n_mpv_api(("mpv APIs<br/>host runtime"))
  n_playback(("playback hooks<br/>event layer"))
  n_input(("hover input<br/>ui events"))
  n_overlay(("overlay render<br/>display layer"))
end

subgraph "sprite pipeline"
  n_ffmpeg["FFmpeg<br/>external process"]
  n_gen["generation logic<br/>pipeline stage"]
  n_cache[("sprite cache<br/>storage layer")]
  n_lookup(("cache lookup<br/>reuse logic"))
  n_delete(("cleanup<br/>maintenance"))
  n_seekmap{{"seek mapping<br/>math layer"}}
  n_sprite["sprite sheet<br/>artifact"]
end

subgraph "config and docs"
  n_readme["README<br/>contract doc<br/>[README.md]"]
  n_conf["mpv_seekpeek.conf<br/>sample config<br/>[mpv_seekpeek.conf]"]
  n_license["LICENSE"]
end

n_main -->|"uses"| n_mpv_api
n_main -->|"delegates to"| n_helper
n_main -->|"starts on"| n_playback
n_playback -->|"checks"| n_lookup
n_lookup -->|"reads"| n_cache
n_playback -->|"spawns"| n_ffmpeg
n_ffmpeg -->|"executes"| n_gen
n_gen -->|"writes"| n_sprite
n_sprite -->|"stored in"| n_cache
n_main -->|"handles"| n_input
n_input -->|"maps to"| n_seekmap
n_seekmap -->|"indexes"| n_sprite
n_main -->|"renders via"| n_overlay
n_main -->|"controls"| n_delete
n_delete -->|"removes from"| n_cache
n_conf -->|"configures"| n_main
n_readme -->|"documents"| n_main
n_readme -->|"documents"| n_ffmpeg

click n_main "https://github.com/soorajsprakash/mpv-seekpeek/blob/main/main.lua"
click n_helper "https://github.com/soorajsprakash/mpv-seekpeek/blob/main/helper.lua"
click n_readme "https://github.com/soorajsprakash/mpv-seekpeek/blob/main/README.md"
click n_conf "https://github.com/soorajsprakash/mpv-seekpeek/blob/main/mpv_seekpeek.conf"
click n_license "https://github.com/soorajsprakash/mpv-seekpeek/tree/main/LICENSE"

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 n_main,n_helper,n_mpv_api,n_playback,n_input,n_overlay toneBlue
class n_ffmpeg,n_gen,n_cache,n_lookup,n_delete,n_seekmap,n_sprite toneAmber
class n_readme,n_conf,n_license toneMint
```

## Components

### mpv runtime

Interactive Lua script execution inside mpv.

- [main.lua](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/main.lua): mpv script · Entry point that wires playback events, keybindings, hover handling, and preview rendering. · `main.lua`
- [helper.lua](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/helper.lua): utility module · Shared helpers for cache paths, sprite math, and support routines. · `helper.lua`
- **mpv APIs**: host runtime · Playback lifecycle, script options, keybindings, seekbar events, and overlay/OSD rendering.
- **playback hooks**: event layer · Starts work when media playback begins and keeps state aligned with the current file.
- **hover input**: ui events · Converts seekbar cursor position into preview requests.
- **overlay render**: display layer · Displays BGRA preview regions directly in mpv.

### sprite pipeline

Asynchronous thumbnail sheet generation and reuse.

- **FFmpeg**: external process · Generates sprite sheets from the current media file asynchronously.
- **generation logic**: pipeline stage · Chooses sampling cadence, size, tiling, and output format for the sprite sheet.
- **sprite cache**: storage layer · Stores generated BGRA sprite sheets in mpv's cache directory for reuse.
- **cache lookup**: reuse logic · Checks whether a sprite already exists before launching generation.
- **cleanup**: maintenance · Deletes cached sprites on manual request or exit when configured.
- **seek mapping**: math layer · Maps hover position to timestamp, then to sprite cell coordinates.
- **sprite sheet**: artifact · Raw BGRA thumbnail grid consumed by mpv's overlay API.

### config and docs

User-facing contract and runtime options.

- [README](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/README.md): contract doc · Documents the script workflow, controls, and mpv/FFmpeg boundary. · `README.md`
- [mpv_seekpeek.conf](https://github.com/soorajsprakash/mpv-seekpeek/blob/HEAD/mpv_seekpeek.conf): sample config · Example script-options file for runtime customization. · `mpv_seekpeek.conf`
- [LICENSE](https://github.com/soorajsprakash/mpv-seekpeek/tree/HEAD/LICENSE): license · Repository license file. · `LICENSE`

## Connections

- main.lua → mpv APIs: uses · Calls into mpv's Lua, keybinding, and overlay interfaces.
- main.lua → helper.lua: delegates to · Relies on shared helpers for path and sprite calculations.
- main.lua → playback hooks: starts on · Initiates generation when playback begins.
- playback hooks → cache lookup: checks · Skips work if a cached sprite already exists.
- cache lookup → sprite cache: reads · Looks for an existing cached sprite file.
- playback hooks → FFmpeg: spawns · Launches asynchronous sprite generation when needed.
- FFmpeg → generation logic: executes · Performs frame sampling, scaling, tiling, and raw BGRA output.
- generation logic → sprite sheet: writes · Produces the sprite sheet artifact.
- sprite sheet → sprite cache: stored in · Persists under mpv's cache directory.
- main.lua → hover input: handles · Receives hover and seekbar interaction events.
- hover input → seek mapping: maps to · Converts cursor position into time and sprite coordinates.
- seek mapping → sprite sheet: indexes · Selects the correct BGRA region within the sheet.
- main.lua → overlay render: renders via · Pushes preview regions to mpv's overlay display.
- main.lua → cleanup: controls · Exposes manual and on-exit sprite cleanup behavior.
- cleanup → sprite cache: removes from · Deletes cached artifacts when requested.
- mpv_seekpeek.conf → main.lua: configures · Sets startup behavior, geometry, sampling, and keybindings.
- README → main.lua: documents · Explains the runtime entry point and control surface.
- README → FFmpeg: documents · Describes the external generation boundary.
