Skip to main content

​
Video Class

The Video class represents a source video file or URL. It’s the starting point for background removal operations.

​
Loading Videos

import { Video } from '@videobgremover/sdk'

// From local file
const video = Video.open('path/to/video.mp4')

// From URL
const video = Video.open('https://example.com/video.mp4')

// From file with metadata
const video = Video.open('video.mov', {
  contentType: 'video/mov'
})

​
Background Removal

The main method for removing backgrounds using the API: 
import { VideoBGRemoverClient, RemoveBGOptions, Prefer } from '@videobgremover/sdk'

const client = new VideoBGRemoverClient('your_api_key')
const video = Video.open('input.mp4')

// Basic background removal
const transparent = await video.removeBackground({ client })

// With format preference
const options = new RemoveBGOptions(Prefer.WEBM_VP9)
const transparent = await video.removeBackground({ client, options })

// With progress tracking
const statusCallback = (status: string) => {
  console.log(`Status: ${status}`)
}
const transparent = await video.removeBackground({
  client,
  options,
  waitPollSeconds: 2.0, // Poll every 2 seconds
  onStatus: statusCallback
})

​
Parameters

ParameterTypeDescription
clientVideoBGRemoverClientAuthenticated API client
optionsRemoveBGOptionsProcessing options (optional)
pollSecondsnumberStatus polling interval (default: 2.0)
onStatusfunctionProgress callback (optional)

​
Returns

Returns a Foreground object representing the transparent video.

​
Foreground Class

The Foreground class represents a transparent video after background removal. It can be used in compositions.

​
Creating Foregrounds

import { Foreground } from '@videobgremover/sdk'

// From API background removal (most common)
const transparent = await video.removeBackground({ client })

// From existing transparent files
const webm = Foreground.fromWebmVp9('transparent.webm')
const prores = Foreground.fromMovProres('transparent.mov')
const stacked = Foreground.fromStackedVideo('stacked.mp4')
const bundle = Foreground.fromProBundleZip('bundle.zip')

// Auto-detect format from file extension
const auto = Foreground.fromFile('transparent.webm') // Detects WebM VP9

// From URL with format specification
const url = Foreground.fromUrl('https://example.com/transparent.webm', {
  format: 'webm_vp9'
})

​
Foreground Properties

// Get format information
console.log('Format:', transparent.getFormat()) // 'webm_vp9', 'mov_prores', etc.
console.log('Primary path:', transparent.primaryPath)
console.log('Mask path:', transparent.maskPath) // For pro_bundle format
console.log('Audio path:', transparent.audioPath) // For pro_bundle format

// Check if it's a URL
console.log('Is URL:', transparent.isUrl())

​
Source Trimming

Use only specific parts of your transparent videos: 
// Use seconds 5-15 of the transparent video
const trimmed = transparent.subclip(5, 15)

// Use from 10 seconds to end
const fromMiddle = transparent.subclip(10)

// Original remains unchanged
console.log('Original trim:', transparent.sourceTrim) // undefined
console.log('Trimmed:', trimmed.sourceTrim) // [5, 15]

​
RemoveBGOptions

Configure background removal processing: 
import { RemoveBGOptions, Prefer, Model } from '@videobgremover/sdk'

// Default options (uses videobgremover-original model)
const options = new RemoveBGOptions()

// Prefer specific format
const webmOptions = new RemoveBGOptions(Prefer.WEBM_VP9)
const proResOptions = new RemoveBGOptions(Prefer.MOV_PRORES)
const stackedOptions = new RemoveBGOptions(Prefer.STACKED_VIDEO)

// Using factory methods
const autoOptions = RemoveBGOptions.default()
const specificOptions = RemoveBGOptions.withPrefer(Prefer.WEBM_VP9)

​
Format Preferences

PreferBest ForFile SizeCompatibility
WEBM_VP9Web apps, APIsSmallGood
MOV_PRORESProfessional editingLargeExcellent
STACKED_VIDEOUniversal compatibilityMediumUniversal
PRO_BUNDLEAdvanced workflowsMediumUniversal
AUTOLet system chooseVariesGood

​
Complete Example

Here’s a complete example showing video loading, background removal, and basic composition: 
import { 
  VideoBGRemoverClient, 
  Video, 
  Background, 
  Composition, 
  EncoderProfile,
  RemoveBGOptions,
  Prefer,
  Anchor,
  SizeMode 
} from '@videobgremover/sdk'

async function completeExample() {
  // 1. Initialize client
  const client = new VideoBGRemoverClient(process.env.VIDEOBGREMOVER_API_KEY!)
  
  // 2. Check credits
  const credits = await client.credits()
  console.log(`Credits available: ${credits.remainingCredits}`)
  
  // 3. Load and process video
  const video = Video.open('https://example.com/input.mp4')
  const options = new RemoveBGOptions(Prefer.WEBM_VP9)
  
  console.log('Removing background...')
  const transparent = await video.removeBackground({ client, options })
  
  // 4. Create composition
  const background = Background.fromColor('#00FF00', 1920, 1080, 30)
  const comp = new Composition(background)
  comp.add(transparent, 'main').at(Anchor.CENTER).size(SizeMode.CONTAIN)
  
  // 5. Export
  await comp.toFile('output.mp4', EncoderProfile.h264())
  console.log('✅ Complete workflow finished!')
}