react-native-video-overlay

A lightweight and native Android-only React Native TurboModule for applying image and text overlays on videos using FFmpeg. Ideal for branding, watermarking, or offline field use cases.

⚠️ Experimental Notice

This library is currently under testing and may not be fully stable for production. Use at your own risk. We do not guarantee correctness or provide support at this stage. External contributions are not being accepted currently.

✨ Features

• ⚡ Fast FFmpeg-based video overlay processing
• 🖼️ Add multiple image and text overlays
• 🎯 Define predefined or custom positions per overlay
• 🖏️ Control width, height, font size, opacity, and more
• ✂️ Text truncation support based on space
• 🎮 Frame-safe overlay rendering
• 📱 Android only, offline-ready

📦 Installation

yarn add react-native-video-overlay
# or
npm install react-native-video-overlay

🛠️ Setup

1. Android Permissions

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

2. FFmpeg Binary Bundled

FFmpeg is included in the native module — no extra download or setup needed.

🚀 Usage Example

import { applyOverlay } from 'react-native-video-overlay';

const options = {
  inputPath: '/storage/emulated/0/DCIM/input.mp4',
  outputPath: '/storage/emulated/0/DCIM/output.mp4',
  overlays: [
    {
      type: 'image',
      source: '/storage/emulated/0/DCIM/logo.png',
      position: 'top-left',
      width: 100,
      height: 100,
      opacity: 0.9,
    },
    {
      type: 'text',
      text: 'ReviewDekho - Hyderabad',
      position: 'bottom-center',
      fontSize: 28,
      fontColor: 'white',
      opacity: 1.0,
    },
  ],
  onProgress: (line: string) => {
    console.log('[FFmpeg]', line);
  },
};

const resultPath = await applyOverlay(options);
console.log('Video saved at:', resultPath);

🎯 Overlay Position Options

Use predefined string positions or custom coordinates:

• 'top-left'
• 'top-center'
• 'top-right'
• 'center-left'
• 'center'
• 'center-right'
• 'bottom-left'
• 'bottom-center'
• 'bottom-right'
• { x: number, y: number } – Custom absolute position

🔤 Text Overlay Options

| Property | Type | Description | | ----------- | ------------- | ------------------------------ | | text | string | Required. The overlay text | | fontSize | number | Optional. Defaults to 24 | | fontColor | string | Optional. Defaults to white | | opacity | number | Optional. Range: 0 to 1 | | position | string/object | Predefined or custom position |

Text is automatically truncated if it exceeds layout bounds.

🖼️ Image Overlay Options

| Property | Type | Description | | ---------- | ------------- | ----------------------------- | | source | string | Required. Image file path | | width | number | Optional. Image width | | height | number | Optional. Image height | | opacity | number | Optional. Range: 0 to 1 | | position | string/object | Predefined or custom position |

📞 Progress Callback

To stream FFmpeg output lines (for loading state, logging, etc.):

onProgress?: (logLine: string) => void;

🧪 Requirements

• React Native >= 0.71
• Android only (no iOS support)

👨‍💻 Author

ALN Labs GitHub: @alnlabs Email: [email protected]

📄 License

MIT © ALN Labs

🌐 Links

• NPM Package
• GitHub Repository