How soorajsprakash/mpv-seekpeek works
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 main.lua · README.md README · mpv_seekpeek.conf mpv_seekpeek.conf · helper.lua helper.lua
Components 16
mpv runtime
Interactive Lua script execution inside mpv.
- main.lua · Entry point that wires playback events, keybindings, hover handling, and preview rendering.
main.lua - helper.lua · Shared helpers for cache paths, sprite math, and support routines.
helper.lua - mpv APIs · Playback lifecycle, script options, keybindings, seekbar events, and overlay/OSD rendering.
- playback hooks · Starts work when media playback begins and keeps state aligned with the current file.
- hover input · Converts seekbar cursor position into preview requests.
- overlay render · Displays BGRA preview regions directly in mpv.
sprite pipeline
Asynchronous thumbnail sheet generation and reuse.
- FFmpeg · Generates sprite sheets from the current media file asynchronously.
- generation logic · Chooses sampling cadence, size, tiling, and output format for the sprite sheet.
- sprite cache · Stores generated BGRA sprite sheets in mpv's cache directory for reuse.
- cache lookup · Checks whether a sprite already exists before launching generation.
- cleanup · Deletes cached sprites on manual request or exit when configured.
- seek mapping · Maps hover position to timestamp, then to sprite cell coordinates.
- sprite sheet · Raw BGRA thumbnail grid consumed by mpv's overlay API.
config and docs
User-facing contract and runtime options.
- README · Documents the script workflow, controls, and mpv/FFmpeg boundary.
README.md - mpv_seekpeek.conf · Example script-options file for runtime customization.
mpv_seekpeek.conf - LICENSE · Repository license file.
LICENSE
Connections 18
- 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.