🎬 react-native-nitro-thumbnail

Generate a thumbnail from any video — local or remote — with one async call.

The same API on iOS, Android, and Web. Powered by Nitro: pure Swift & Kotlin, New Architecture, no bridge.

import { createThumbnail } from 'react-native-nitro-thumbnail';
 
const thumb = await createThumbnail({ url: 'https://media.example.com/clip.mp4' });
// → { path: 'file:///…/thumb.jpg', size: 19856, mime: 'image/jpeg', width: 512, height: 288 }
 
<Image source={{ uri: thumb.path }} />

One call, one frame. Here’s a real thumbnail the library extracts from the bundled demo clip:

A thumbnail extracted by createThumbnail() — the Sintel cliff/sunset shot

Demo: Sintel © Blender Foundation, CC-BY 3.0.

📦

Already published. npm install react-native-nitro-thumbnail react-native-nitro-modules — then head to Installation.

Why this library?

iOS (AVFoundation), Android (MediaMetadataRetriever), and Web (<video> + <canvas>) behind a single typed function. Your call sites never branch on platform.

🧩One API, three engines

Pass a file:// path or an http(s) URL. Remote videos are streamed and decoded directly. Custom request headers supported.

🌐Local & remote, no download step

Pure Swift & Kotlin over JSI — no Objective-C/Java bridge. The native contract is generated from one TypeScript spec, so it can’t drift.

⚡Built on Nitro

Every failure rejects with a ThumbnailError carrying a typed .code you can switch on — never an opaque string.

🎯Typed errors

Deterministic filenames skip re-decoding; a size cap evicts old thumbnails (LRU) so the cache never grows unbounded.

💾Built-in caching

Matches react-native-create-thumbnail’s options, result, and defaults — migrating is usually a one-line import change.

🔀Drop-in replacement

Built to avoid the reported failure modes of older wrappers — build breakage, remote-URL crashes, UI jank, content:// videos, gallery pollution.

🛡️Solves the known issues

How it works

One TypeScript function validates your input and applies defaults, then calls a Nitro HybridObject implemented natively per platform. The box labelled “your app” never changes — only the engine behind it does.

The complete request lifecycle — cache check, decode, encode, write, evict — is in the Architecture guide.

Get started

Install

npm install react-native-nitro-thumbnail react-native-nitro-modules
cd ios && pod install

Call it

const thumb = await createThumbnail({ url, timeStamp: 2000 });

Render it

<Image source={{ uri: thumb.path }} style={{ width: thumb.width, height: thumb.height }} />

Install, pods, Expo, and the New Architecture requirement.

🚀Installation

Every option and result field, with recipes.

📖API Reference

The TS → Nitro → native flow, end to end.

🏛️Architecture

Installation