RembgTS

Client-side AI background removal for images and videos in the browser.

RembgTS is a TypeScript library that provides high-quality background removal directly in the browser using ONNX Runtime Web and FFmpeg.wasm. No server required - all processing happens client-side with GPU acceleration when available.

Features

• 🎯 Multiple AI Models: U2-Net, U2-Net-P, and MODNet for different use cases
• 🚀 GPU Acceleration: WebGPU support with WebAssembly fallback
• 📸 Image Processing: Single images and batch processing
• 🎬 Video Processing: Full video background removal with audio preservation
• 💾 Smart Caching: IndexedDB-based model and file caching
• 🧠 Memory Efficient: Intelligent memory management for browser constraints
• 📱 Cross-Platform: Works on desktop and mobile browsers
• 🔧 TypeScript: Full type safety and IntelliSense support

Installation

npm install rembgts

Quick Start

import { Rembg } from 'rembgts';

// Create instance
const rembg = new Rembg({
  model: 'u2netp', // Fast model
  executionProvider: 'auto' // Auto-detect WebGPU/WASM
});

// Remove background from image
const imageFile = // ... your File or Blob
const [resultBlob] = await rembg.removeBackgroundBatch([imageFile]);

// Convert to data URL for display
const resultUrl = URL.createObjectURL(resultBlob);

API Reference

Main Class

Rembg

The main class for background removal operations.

class Rembg {
  constructor(options?: RembgWebOptions);
  
  // Remove background from images
  removeBackgroundBatch(images: (File | Blob)[]): Promise<Blob[]>;
  
  // Remove background from video
  removeBackgroundFromVideo(video: File | Blob): Promise<Blob>;
  
  // Update configuration
  updateOptions(newOptions: Partial<RembgWebOptions>): Promise<void>;
  
  // Get current configuration
  getConfig(): RembgWebConfig;
  
  // Check if ready for processing
  isReady(): boolean;
  
  // Clean up resources
  cleanup(): void;
}

Types and Interfaces

RembgWebOptions

Configuration options when creating a Rembg instance.

interface RembgWebOptions {
  /** AI model to use for background removal */
  model?: 'u2net' | 'u2netp' | 'modnet';
  
  /** Execution provider for ONNX Runtime */
  executionProvider?: ExecutionProvider;
  
  /** Return only the mask without applying it */
  onlyMask?: boolean;
  
  /** Background color to use instead of transparency [R, G, B, A] */
  backgroundColor?: [number, number, number, number];
  
  /** Maximum number of threads for WASM execution */
  numThreads?: number;
  
  /** Batch size for processing (1-50 images per batch) */
  batchSize?: number;
  
  /** Progress callback for operations */
  onProgress?: (stage: string, progress: number) => void;
  
  /** Enable verbose logging */
  verbose?: boolean;
}

RembgWebConfig

Current configuration state (all required fields).

interface RembgWebConfig {
  /** AI model being used */
  model: 'u2net' | 'u2netp' | 'modnet';
  
  /** Execution provider being used */
  executionProvider: ExecutionProvider;
  
  /** Maximum number of threads for WASM execution */
  numThreads: number;
  
  /** Batch size for processing */
  batchSize: number;
}

ExecutionProvider

Execution provider options for ONNX Runtime.

type ExecutionProvider = 'webgpu' | 'wasm' | 'auto';

RembgWebError

Error type with additional context.

interface RembgWebError extends Error {
  code: string;
  stage?: string;
}

Utility Functions

getDefaultExecutionProvider()

Detects the best available execution provider.

function getDefaultExecutionProvider(): ExecutionProvider;

Returns 'webgpu' if WebGPU is available, otherwise 'wasm'.

Supported Models

U2-Net (176MB)

• Best quality background removal
• Use case: High-quality production work
• Memory: High memory usage
• Speed: Slower processing

const rembg = new Rembg({ model: 'u2net' });

U2-Net-P (4.7MB) ⭐ Recommended

• Balanced quality and performance
• Use case: General purpose, mobile devices
• Memory: Low memory usage
• Speed: Fast processing

const rembg = new Rembg({ model: 'u2netp' });

MODNet (24MB)

• Portrait-focused for people
• Use case: Profile pictures, portraits
• Memory: Medium memory usage
• Speed: Medium processing speed

const rembg = new Rembg({ model: 'modnet' });

Usage Examples

Basic Image Processing

import { Rembg } from 'rembgts';

const rembg = new Rembg({
  model: 'u2netp',
  verbose: true,
  onProgress: (stage, progress) => {
    console.log(`${stage}: ${progress}%`);
  }
});

// Single image
const file = document.querySelector('input[type="file"]').files[0];
const [result] = await rembg.removeBackgroundBatch([file]);

// Display result
const img = document.createElement('img');
img.src = URL.createObjectURL(result);
document.body.appendChild(img);

Batch Image Processing

// Process multiple images efficiently
const files = Array.from(document.querySelector('input[type="file"]').files);
const results = await rembg.removeBackgroundBatch(files);

results.forEach((blob, index) => {
  const img = document.createElement('img');
  img.src = URL.createObjectURL(blob);
  img.alt = `Result ${index + 1}`;
  document.body.appendChild(img);
});

Video Processing

const rembg = new Rembg({
  model: 'u2netp',
  batchSize: 15, // Process 15 frames at once
  onProgress: (stage, progress) => {
    console.log(`Video processing: ${stage} (${progress}%)`);
  }
});

const videoFile = document.querySelector('input[type="file"]').files[0];
const resultVideo = await rembg.removeBackgroundFromVideo(videoFile);

// Display result video
const video = document.createElement('video');
video.src = URL.createObjectURL(resultVideo);
video.controls = true;
document.body.appendChild(video);

Advanced Configuration

const rembg = new Rembg({
  model: 'modnet',
  executionProvider: 'webgpu', // Force GPU acceleration
  numThreads: 4, // Use 4 threads for WASM fallback
  batchSize: 20, // Larger batch size for better performance
  onlyMask: false, // Return full cutout, not just mask
  backgroundColor: [255, 255, 255, 255], // White background instead of transparent
  verbose: true
});

// Update configuration later
await rembg.updateOptions({
  model: 'u2net', // Switch to high-quality model
  batchSize: 10 // Reduce batch size for memory
});

Error Handling

try {
  const results = await rembg.removeBackgroundBatch([imageFile]);
  console.log('Success!', results);
} catch (error) {
  if (error.message.includes('WebGPU')) {
    // Handle WebGPU issues
    console.log('WebGPU failed, trying WASM...');
    await rembg.updateOptions({ executionProvider: 'wasm' });
    const results = await rembg.removeBackgroundBatch([imageFile]);
  } else {
    console.error('Processing failed:', error);
  }
}

Memory Management

// For long-running applications
const rembg = new Rembg({ model: 'u2netp' });

try {
  // Process images
  const results = await rembg.removeBackgroundBatch(images);
  
  // Use results...
  
} finally {
  // Clean up resources when done
  rembg.cleanup();
}

Browser Requirements

Minimum Requirements

• ES2020 support
• WebAssembly support
• Canvas API support
• IndexedDB support

Recommended

• WebGPU support for GPU acceleration
• SharedArrayBuffer for better performance
• HTTPS required for WebGPU and some features

HTTPS Headers

For optimal performance, serve your application with these headers:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Performance Tips

Memory Optimization

// For mobile devices or limited memory
const rembg = new Rembg({
  model: 'u2netp', // Smaller model
  batchSize: 5, // Smaller batches
  numThreads: 1 // Single thread
});

Speed Optimization

// For desktop with good hardware
const rembg = new Rembg({
  model: 'u2netp', // Still fast but good quality
  executionProvider: 'webgpu', // Force GPU
  batchSize: 25, // Larger batches
  numThreads: 8 // More threads for WASM fallback
});

Video Processing Tips

• Use smaller batch sizes (5-15) for long videos
• Monitor memory usage during processing
• Consider reducing video resolution for very long videos

Integration Examples

React

import React, { useState } from 'react';
import { Rembg } from 'rembgts';

function BackgroundRemover() {
  const [rembg] = useState(() => new Rembg({ model: 'u2netp' }));
  const [result, setResult] = useState<string>('');
  const [loading, setLoading] = useState(false);

  const handleFile = async (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (!file) return;

    setLoading(true);
    try {
      const [blob] = await rembg.removeBackgroundBatch([file]);
      setResult(URL.createObjectURL(blob));
    } catch (error) {
      console.error('Failed to process image:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={handleFile} />
      {loading && <p>Processing...</p>}
      {result && <img src={result} alt="Result" />}
    </div>
  );
}

Vue 3

<template>
  <div>
    <input type="file" @change="handleFile" accept="image/*" />
    <div v-if="loading">Processing...</div>
    <img v-if="result" :src="result" alt="Result" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Rembg } from 'rembgts';

const rembg = new Rembg({ model: 'u2netp' });
const result = ref<string>('');
const loading = ref(false);

const handleFile = async (event: Event) => {
  const target = event.target as HTMLInputElement;
  const file = target.files?.[0];
  if (!file) return;

  loading.value = true;
  try {
    const [blob] = await rembg.removeBackgroundBatch([file]);
    result.value = URL.createObjectURL(blob);
  } catch (error) {
    console.error('Failed to process image:', error);
  } finally {
    loading.value = false;
  }
};
</script>

Build Configuration

Vite

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
  optimizeDeps: {
    exclude: ['@ffmpeg/ffmpeg', '@ffmpeg/util'],
  },
  worker: {
    format: 'es',
  },
});

Webpack

// webpack.config.js
module.exports = {
  // ... other config
  devServer: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
  module: {
    rules: [
      {
        test: /\.wasm$/,
        type: 'asset/resource',
      },
    ],
  },
};

Troubleshooting

Common Issues

WebGPU Not Available

// Check WebGPU availability
import { getDefaultExecutionProvider } from 'rembgts';

if (getDefaultExecutionProvider() === 'wasm') {
  console.log('WebGPU not available, using WebAssembly');
}

Memory Issues

// Reduce memory usage
const rembg = new Rembg({
  model: 'u2netp', // Smaller model
  batchSize: 3, // Smaller batches
  numThreads: 1 // Single thread
});

HTTPS Required

• WebGPU requires HTTPS in production
• Use vite --https for local development
• Deploy with SSL certificate

Slow Processing

• Try WebGPU if available
• Increase batch size on powerful hardware
• Use U2-Net-P model for speed
• Enable verbose logging to identify bottlenecks

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the JavaScript community