@capgo/capacitor-video-thumbnails
Create thumbnail images from local or remote videos in your Capacitor app, for galleries, upload previews and video lists.
Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.
➡️ Get started for free
14-day unlimited free trial. No credit card required
🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use
@capgo/capacitor-video-thumbnailsin your Capacitor app:npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-video-thumbnails to my Capacitor app and wire it up." Agent setup guides · Hosted MCP
Key features
- One call:
getThumbnail()returns an image of the video frame. - Pick the frame:
timesets the position in milliseconds. - Quality: set the image
quality. - Remote videos: pass HTTP
headersfor protected URLs on iOS and Android. - Platforms: iOS, Android and Web. iOS uses AVFoundation, Android uses
MediaMetadataRetriever, web uses a video element and canvas.
Why Capacitor Video Thumbnails?
Extract thumbnail images from videos at specific time positions:
- Local & Remote Videos - Works with both file:// paths and http(s):// URLs
- Custom Time Position - Extract frame at any millisecond timestamp
- Quality Control - Adjustable JPEG compression quality
- HTTP Headers Support - Custom headers for authenticated video sources
- Cross-platform - Consistent API across iOS, Android, and Web
Perfect for video galleries, media players, video editors, and any app that needs video preview images.
Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/video-thumbnails/
Compatibility
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
Install
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
Then use the following prompt:
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-video-thumbnails` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
npm install @capgo/capacitor-video-thumbnails
npx cap sync
Requirements
- iOS: iOS 15.0+
- Android: API 24+ (Android 7.0+)
- Web: Modern browsers with HTML5 video support
API
Capacitor Video Thumbnails Plugin interface for generating video thumbnails.
getThumbnail(...)
getThumbnail(options: VideoThumbnailsOptions) => Promise<VideoThumbnailsResult>
Generate a thumbnail image from a video file at a specific time position.
| Param | Type | Description |
|---|---|---|
options | VideoThumbnailsOptions | - Options for generating the thumbnail |
Returns: Promise<VideoThumbnailsResult>
Since: 8.0.0
getPluginVersion()
getPluginVersion() => Promise<{ version: string; }>
Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 8.0.0
Interfaces
VideoThumbnailsResult
Result of thumbnail generation.
| Prop | Type | Description |
|---|---|---|
uri | string | The local URI path to the generated thumbnail image. This can be used directly in img tags or Image components. |
width | number | Width of the generated thumbnail in pixels. |
height | number | Height of the generated thumbnail in pixels. |
VideoThumbnailsOptions
Options for generating a video thumbnail.
| Prop | Type | Description |
|---|---|---|
sourceUri | string | The URI of the video file. Can be a local file path or a remote URL. For local files, use file:// protocol or absolute path. For remote files, use http:// or https:// protocol. |
time | number | The time position in milliseconds from which to extract the thumbnail. Defaults to 0 (first frame). |
quality | number | Quality of the generated image, from 0.0 (lowest) to 1.0 (highest). Defaults to 1.0. |
headers | Record<string, string> | HTTP headers to include when fetching remote video URIs. Only applicable for remote URLs. |
Type Aliases
Record
Construct a type with a set of properties K of type T
{
[P in K]: T;
}
Credits
This was inspired from (Expo SDK)[https://docs.expo.dev/versions/latest/sdk/video-thumbnails/]