VideoBGRemover Node.js SDK

The official Node.js SDK for VideoBGRemover - Remove video backgrounds with AI and compose videos with FFmpeg.

📖 Full Documentation | 🐙 GitHub Repository

Goal

This SDK simplifies using the VideoBGRemover API and abstracts the complexity of transparent video formats. It handles all the difficult parts of video composition, format conversion, and FFmpeg integration so you can focus on your application.

Features

🎥 Video Background Removal: Remove backgrounds from videos using state-of-the-art AI models
🎨 Video Composition: Layer videos with custom backgrounds, effects, and positioning
⚡ Multiple Formats: Support for WebM (with alpha), ProRes, stacked videos, and more
🛠️ FFmpeg Integration: Professional video processing and encoding capabilities
📱 Easy to Use: Simple, TypeScript-first API with full type safety
🔧 Flexible: From simple background replacement to complex multi-layer compositions

Installation

npm install @videobgremover/sdk

Requirements

• Node.js 16+
• FFmpeg - Required binary for video processing operations
• VideoBGRemover API key

Note: FFmpeg must be available in your system PATH. The SDK automatically detects and uses your FFmpeg installation for video composition, format conversion, and metadata extraction.

Quick Start

import { VideoBGRemoverClient, Video, Background, Composition, EncoderProfile, Anchor, SizeMode } from '@videobgremover/sdk'

// Initialize client
const client = new VideoBGRemoverClient(process.env.VIDEOBGREMOVER_API_KEY!)

// Remove background from video
const video = Video.open('https://example.com/video.mp4')

try {
  const foreground = await video.removeBackground(client)
} catch (error) {
  if (error.message.includes('credits')) {
    console.log('Not enough credits. Please top up your account.')
    process.exit(1)
  }
}

// Create composition with custom background
const background = Background.fromColor('#00FF00', 1920, 1080, 30.0)
const composition = new Composition(background)
composition.add(foreground).at(Anchor.CENTER).size(SizeMode.CONTAIN)

// Export final video
await composition.toFile('output.mp4', EncoderProfile.h264())

API Key Setup

Get your API key from VideoBGRemover Dashboard and set it as an environment variable:

export VIDEOBGREMOVER_API_KEY="vbr_your_api_key_here"

Or pass it directly to the client:

const client = new VideoBGRemoverClient('vbr_your_api_key_here')

Cost & Credits

• Each video processing consumes credits based on video length
• Check your balance: (await client.credits()).remainingCredits
• Processing typically takes 1-3 minutes depending on video length
• Failed jobs don't consume credits

Usage Examples

Basic Background Removal

import { VideoBGRemoverClient, Video, RemoveBGOptions, Prefer } from '@videobgremover/sdk'

const client = new VideoBGRemoverClient('your_api_key')

// Load video from file or URL
const video = Video.open('path/to/video.mp4')

// Configure processing options
const options = new RemoveBGOptions(Prefer.WEBM_VP9) // Output format preference

// Remove background
const foreground = await video.removeBackground(client, options)

Complete Workflow Example

import {
  VideoBGRemoverClient, Video, Background, Composition, 
  EncoderProfile, Anchor, SizeMode, RemoveBGOptions, Prefer
} from '@videobgremover/sdk'

// Initialize client
const client = new VideoBGRemoverClient('your_api_key')

// Check credits first
const credits = await client.credits()
console.log(`Remaining credits: ${credits.remainingCredits}`)

// Process video
const video = Video.open('input.mp4')
const options = new RemoveBGOptions(Prefer.WEBM_VP9)

const statusCallback = (status: string) => {
  console.log(`Status: ${status}`)
}

const foreground = await video.removeBackground(client, options, 2.0, statusCallback)

// Create composition
const background = Background.fromImage('background.jpg', 30.0)
const comp = new Composition(background)

// Add main video
const layer = comp.add(foreground, 'main_video')
layer.at(Anchor.CENTER).size(SizeMode.CONTAIN).opacity(0.9)

// Export
await comp.toFile('final_output.mp4', EncoderProfile.h264({ crf: 20 }))

Video-on-Video Composition

// Process foreground video
const foregroundVideo = Video.open('person_talking.mp4')
const foreground = await foregroundVideo.removeBackground(client)

// Create composition with video background
const backgroundVideo = Background.fromVideo('nature_scene.mp4')
const comp = new Composition(backgroundVideo)

// Add foreground video on top
comp.add(foreground, 'person').at(Anchor.CENTER).size(SizeMode.CONTAIN)

// Export final video
await comp.toFile('person_on_nature.mp4', EncoderProfile.h264({ crf: 20 }))

Multiple Output Formats

// High-quality H.264
await comp.toFile('output_hq.mp4', EncoderProfile.h264({ crf: 18, preset: 'slow' }))

// Transparent WebM for web use
await comp.toFile('output.webm', EncoderProfile.transparentWebm({ crf: 25 }))

// ProRes for professional editing  
await comp.toFile('output.mov', EncoderProfile.prores4444())

// PNG sequence for frame-by-frame work
await comp.toFile('frames/frame_%04d.png', EncoderProfile.pngSequence())

Layer Positioning & Effects

// Add a layer with positioning
const layer = comp.add(foreground, 'main')

// Positioning options
layer.at(Anchor.CENTER)                    // Center
layer.at(Anchor.TOP_LEFT, 100, 50)         // Top-left with offset

// Sizing options
layer.size(SizeMode.CONTAIN)                              // Fit within canvas
layer.size(SizeMode.PX, { width: 800, height: 600 })     // Exact pixels
layer.size(SizeMode.CANVAS_PERCENT, { percent: 50 })     // 50% of canvas size

// Visual effects
layer.opacity(0.8)                            // 80% opacity
layer.rotate(15.0)                            // Rotate 15 degrees
layer.crop(10, 20, 100, 200)                 // Crop rectangle

// Timing control
layer.start(2.0)                              // Start at 2 seconds
layer.end(10.0)                               // End at 10 seconds
layer.duration(5.0)                           // Show for 5 seconds

// Audio control
layer.audio(true, 0.8)                        // Enable audio at 80% volume

Transparent Video Formats

The SDK supports multiple transparent video formats:

| Format | File Size | Quality | Compatibility | Best For | |--------|-----------|---------|---------------|----------| | WebM VP9 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | Web applications, small files | | Stacked Video | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Universal compatibility | | ProRes 4444 | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | Professional video editing | | PNG Sequence | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Frame-by-frame work, GIFs |

WebM VP9 is excellent for video composition workflows due to its small file sizes and native alpha channel support. The SDK automatically chooses WebM VP9 as the default format when you don't specify a preference, making it ideal for most use cases including web applications and API integrations.

Recommendation: Use WebM VP9 for most applications. Fall back to stacked video for maximum compatibility.

// Choose format when processing
const options1 = new RemoveBGOptions(Prefer.WEBM_VP9)      // Small files
const options2 = new RemoveBGOptions(Prefer.STACKED_VIDEO) // Universal
const options3 = new RemoveBGOptions(Prefer.MOV_PRORES)    // Professional

Canvas and Sizing

The composition system automatically determines canvas size:

1. Background dimensions (if background is set)
2. Explicit canvas size (if .canvas() or .setCanvas() called)
3. Auto-computed from layers (with warning)

// Explicit canvas using static method
const comp = Composition.canvas(1920, 1080, 30.0)

// Or set canvas dimensions later (returns new composition)
const comp2 = comp.setCanvas(3840, 2160, 60.0)  // 4K 60fps

Error Handling

import { InsufficientCreditsError, ProcessingError } from '@videobgremover/sdk'

try {
  const foreground = await video.removeBackground(client)
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    console.log('Not enough credits. Please top up your account.')
  } else if (error instanceof ProcessingError) {
    console.log(`Video processing failed: ${error.message}`)
  } else {
    console.log(`Unexpected error: ${error.message}`)
  }
}

Troubleshooting

FFmpeg Issues

• WebM transparency not working: Ensure FFmpeg has libvpx-vp9 support
• Large file sizes: Use WebM format instead of ProRes for smaller files

API Issues

• 401 Unauthorized: Check your API key
• 402 Payment Required: Top up your credits
• Processing timeout: Increase timeout or check video file size limits

API Reference

Core Classes

• VideoBGRemoverClient: API client for background removal
• Video: Video loader (file or URL)
• Background: Background sources (color, image, video)
• Foreground: Transparent video representation
• Composition: Multi-layer video composition
• EncoderProfile: Video encoding settings

Processing Options

• RemoveBGOptions: Background removal configuration
• Prefer: Output format preferences (WEBM_VP9, STACKED_VIDEO, etc.)

Layout & Effects

• Anchor: Positioning anchors (CENTER, TOP_LEFT, etc.)
• SizeMode: Sizing modes (CONTAIN, COVER, PX, CANVAS_PERCENT)
• LayerHandle: Layer manipulation methods

Development

Setup

git clone https://github.com/videobgremover/videobgremover-node.git
cd videobgremover-node
npm install

Scripts

npm run build        # Build the package
npm run dev          # Watch mode for development
npm test             # Run all tests
npm run test:unit    # Run unit tests only
npm run lint         # Check code style
npm run format       # Format code

Testing

# Unit tests (fast, no API calls)
npm run test:unit

# Functional tests (mock API + real FFmpeg)
npm run test:functional

# Integration tests (real API, consumes credits)
npm run test:integration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Full Documentation
• 🐙 GitHub Repository
• 📧 Email Support
• 🐛 Issue Tracker