ThumbMoves logo

Music, motion and media tools

Independent DanceFlow tool

ThumbMoves

Reuse the preview that already exists.

ThumbMoves is a Python cached thumbnail library for reusing previews already stored by the operating system. Its cache-only API avoids opening the original media to make a new thumbnail and returns an explicit miss when no usable preview exists.

What you can do with it

Python cached thumbnail library

Give a media browser a quick existing preview, check a collection without decoding every source file, or let the host application decide what to do after a miss. PixelCue uses ThumbMoves, but the library installs independently and has no GUI dependency.

Cache means cache

Windows uses Shell cache-only flags; freedesktop reads the existing thumbnail store.

A clear miss

No preview returns None. A caller can choose its own separate fallback.

One small Python API

Use image results, encoded bytes or the CLI without adopting PixelCue.

Output you can inspect

Try ThumbMoves.

Open the recorded cache-hit and cache-miss outcomes. The example uses ThumbMoves' actual freedesktop backend with an existing synthetic cache entry and an undecodable original. It ran in an isolated fixture on Windows, rather than through Windows Shell.

Existing cache entry: hit

Plain mint thumbnail from the existing synthetic cache entry

cache_hit: true
size: [128, 80]
source_decoding: false
original_unchanged: true
No existing entry: miss
result: None
source_decoding: false
implicit_generation: false
Actual ThumbMoves backend output from a reproducible cache fixture. The source was unchanged and was not decoded to generate a preview.
Actual ThumbMoves backend output from a reproducible cache fixture. The source was unchanged and was not decoded to generate a preview.

Choose your route

Install and start.

For people

Use a supported Python environment. Windows installs its platform-scoped comtypes dependency. Freedesktop systems use their existing thumbnail store. macOS returns a miss because no equivalent cache-only public route is implemented.

python -m pip install thumbmoves==0.1.2
thumbmoves ./photo.jpg --size 320x240 -o preview.jpg

Call the cache API and branch on the result. CLI exit code 0 means a hit; 1 means a miss. Decide separately whether your application may decode the original or generate a replacement preview.

Checked releases and checksums · Full installation and API guide

For agents

Install the standalone package, identify the backend and preserve None as a real result. Never label a miss as an empty successful thumbnail or silently open the source. Test cache hit, stale or unavailable preview and miss with isolated fixtures; keep original files unchanged.

from thumbmoves import get_cached_thumbnail
result = get_cached_thumbnail('/absolute/path/to/photo.jpg', (320, 240))
if result is None:
    print('Cache miss')
else:
    print(result.backend, result.size)

Portable ThumbMoves agent skill · Codex and Claude installation

Install the selected component as well as any client skill. Repository marketplace installation is separate from a vendor’s curated directory.

Python environment setup

For Python routes, create a dedicated environment with a supported interpreter. Activate it before running python -m pip and the tool’s commands.

python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Linux/macOS:
source .venv/bin/activate

Versioned commands identify the checked packages used for this page on 8 October 2026. Check the release notes for newer versions and retain the checksum manifest. Third-party models and demo materials have their own terms.

A couple of useful questions.

Will ThumbMoves create a thumbnail after a cache miss?

No. Cache-only lookup stays cache-only. Any source-decoding fallback belongs to the calling application.

Is ThumbMoves a thumbnail-cache cleaner?

No. It retrieves existing previews; it does not clean the cache or provide forensic database extraction.

Choose the components your work needs. These links describe related jobs; membership does not make every pair an automatic integration.

Current capabilities and working evidence.

Verified release 0.1.2. Strict cache-only thumbnail retrieval with platform-specific hit, miss and backend evidence.

ThumbMoves maintained project example or explanatory graphic
Maintained ThumbMoves media. Follow the linked example for its exact evidence limits and version context.
Feature routes covered by the current guide
  • Windows and Linux cache backends
  • cache-only hit/miss contract
  • batch inventory and reusable API
  • no source decode on a miss

Open a working example Read every indexed capability

Check the latest stable release and the actual imported or installed identity before each new workflow. Use relevant ecosystem contracts and improve reusable gaps in their owning project.

Current capability and package audit · 23 October 2026

Current features and supported handoffs

Review the source-pinned capability inventory, package identity and working examples before choosing a route. Preserve the canonical tool owner, existing source authority and task-specific host/model acceptance.

Official stable source inspected: thumbmoves-v0.1.2. Read the complete feature, package and example reference.

Unity recording and Potbot host handoffs keep source previews, installed runtime and qualified execution separate. Existing embedded examples retain their declared versions.