Cached Video Thumbnail

cached_video_thumbnail

A high-performance video thumbnail engine for Flutter. Generates thumbnails from bundle assets, local files, and network URLs through a cached, scheduled, cancellable pipeline built for one goal: in an infinite, fast-flinging feed on a low-end device, thumbnail generation is never the reason the UI janks.

AI coding-assistant support (agent plugin)

This repo ships an installable agent plugin - package-specific skills for Claude Code and OpenAI Codex (Codex CLI and the ChatGPT desktop app). It teaches your assistant this exact engine: feed integration with physical-pixel specs, error/cache diagnosis, hermetic test setup, and migration from the video_thumbnail package family. This is developer tooling distributed from this Git repository; it is not a runtime feature and is not part of the pub.dev archive.

Claude Code:

claude plugin marketplace add omar-hanafy/cached_video_thumbnail
claude plugin install cached-video-thumbnail@cached-video-thumbnail

OpenAI Codex:

codex plugin marketplace add omar-hanafy/cached_video_thumbnail
codex plugin add cached-video-thumbnail@cached-video-thumbnail

Start a new agent session after installing, then try:

• "Add video thumbnails to my feed with cached_video_thumbnail - it must stay smooth on low-end devices."
• "My thumbnails fail instantly for a minute after one network error - why?"
• "Write hermetic widget tests for my video tiles."
• "Migrate this file from video_thumbnail to cached_video_thumbnail."

Skills also trigger explicitly: /cached-video-thumbnail:integrate-feed-thumbnails in Claude Code, $integrate-feed-thumbnails in Codex. Trust note: the plugin is instructions and reference files only - no hooks, no MCP servers, no executable scripts, no network access; the bundled Claude agent is read-only. The plugin version tracks the package version, and its skills target 0.1.x. Update with claude plugin update / codex plugin marketplace upgrade; remove with claude plugin uninstall / codex plugin remove. Details, capabilities, and troubleshooting: doc/ai/README.md.

Why another thumbnail package?

Existing packages give you a one-shot video -> image call. That is the easy 20%. The hard 80% is what happens when a feed asks for 40 thumbnails during a fling: unbounded native decoders, no caching, no deduplication, no cancellation, bytes shipped over the platform channel, and slow exact-frame seeks. This package is an engine, not a converter:

Capability	cached_video_thumbnail
Disk cache (deterministic keys, LRU, atomic writes)	yes
Cache hits without decoding (dims stored in the entry)	yes
Bounded native concurrency (default 2)	yes
Newest-first priority scheduling (visible > normal > prefetch)	yes
Identical requests coalesce into one extraction	yes
Cancellation (free pre-dispatch, native abort on iOS)	yes
Negative caching of recent failures	yes
Keyframe-fast seeks by default, exact frames opt-in	yes
Direct-to-file native encoding (no byte arrays over the channel)	yes
Typed errors, metrics, event hook	yes

Native side: Kotlin MediaMetadataRetriever with OPTION_CLOSEST_SYNC and getScaledFrameAtTime (decode-time downscaling); Swift AVAssetImageGenerator with infinite tolerances by default, a precomputed fit box, and per-request cancellation. No FFmpeg, no extra native dependencies.

Quickstart

import 'package:cached_video_thumbnail/cached_video_thumbnail.dart';

// The simplest path: drop the provider into any Image widget.
Image(
  image: VideoThumbnailImage(
    VideoSource.network(Uri.parse('https://cdn.example.com/v.mp4')),
    spec: const ThumbnailSpec(maxWidth: 480, maxHeight: 480),
  ),
  fit: BoxFit.cover,
)

Or drive the engine directly:

final engine = ThumbnailEngine.instance;

final thumb = await engine.getThumbnail(
  VideoSource.asset('assets/videos/intro.mp4'),
  spec: const ThumbnailSpec(maxWidth: 320, maxHeight: 320),
);
// thumb.filePath, thumb.width, thumb.height, thumb.wasCached

Sources

VideoSource.asset('assets/videos/intro.mp4', package: 'my_pkg'); // bundle asset
VideoSource.file('/path/to/video.mp4');                          // absolute path
VideoSource.network(url, headers: {'Authorization': 'Bearer t'}); // http(s)

• File sources embed mtime + size in the cache identity, so edited files self-invalidate.
• Network headers are passed to the platform media stack but are not part of the cache identity (tokens rotate; content does not). Call evict if a URL's content genuinely changed.

Specs