Video Class
TheVideo class represents a source video file or URL. It’s the starting point for background removal operations.
Loading Videos
- Node.js
- Python
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'
})
from videobgremover import Video
# From local file
video = Video.open('path/to/video.mp4')
# From URL
video = Video.open('https://example.com/video.mp4')
# From file with metadata
video = Video.open('video.mov', content_type='video/mov')
Background Removal
The main method for removing backgrounds using the API:- Node.js
- Python
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
})
from videobgremover import VideoBGRemoverClient, RemoveBGOptions, Prefer
client = VideoBGRemoverClient('your_api_key')
video = Video.open('input.mp4')
# Basic background removal
transparent = video.remove_background(client)
# With format preference
options = RemoveBGOptions(prefer=Prefer.WEBM_VP9)
transparent = video.remove_background(client, options)
# With progress tracking
def status_callback(status):
print(f'Status: {status}')
transparent = video.remove_background(
client,
options,
poll_seconds=2.0,
on_status=status_callback
)
Parameters
| Parameter | Type | Description |
|---|---|---|
client | VideoBGRemoverClient | Authenticated API client |
options | RemoveBGOptions | Processing options (optional) |
pollSeconds | number | Status polling interval (default: 2.0) |
onStatus | function | Progress callback (optional) |
Returns
Returns aForeground object representing the transparent video.
Foreground Class
TheForeground class represents a transparent video after background removal. It can be used in compositions.
Creating Foregrounds
- Node.js
- Python
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'
})
from videobgremover import Foreground
# From API background removal (most common)
transparent = video.remove_background(client)
# From existing transparent files
webm = Foreground.from_webm_vp9('transparent.webm')
prores = Foreground.from_mov_prores('transparent.mov')
stacked = Foreground.from_stacked_video('stacked.mp4')
bundle = Foreground.from_pro_bundle_zip('bundle.zip')
# Auto-detect format from file extension
auto = Foreground.from_file('transparent.webm') # Detects WebM VP9
Foreground Properties
- Node.js
- Python
// 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())
# Get format information
print(f'Format: {transparent.format}') # 'webm_vp9', 'mov_prores', etc.
print(f'Primary path: {transparent.primary_path}')
print(f'Mask path: {transparent.mask_path}') # For pro_bundle format
print(f'Audio path: {transparent.audio_path}') # For pro_bundle format
Source Trimming
Use only specific parts of your transparent videos:- Node.js
- Python
// 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]
# Use seconds 5-15 of the transparent video
trimmed = transparent.subclip(5, 15)
# Use from 10 seconds to end
from_middle = transparent.subclip(10)
# Original remains unchanged
print(f'Original trim: {transparent.source_trim}') # None
print(f'Trimmed: {trimmed.source_trim}') # (5, 15)
RemoveBGOptions
Configure background removal processing:- Node.js
- Python
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)
from videobgremover import RemoveBGOptions, Prefer, Model
# Default options (uses videobgremover-original model)
options = RemoveBGOptions()
# Prefer specific format
webm_options = RemoveBGOptions(prefer=Prefer.WEBM_VP9)
prores_options = RemoveBGOptions(prefer=Prefer.MOV_PRORES)
stacked_options = RemoveBGOptions(prefer=Prefer.STACKED_VIDEO)
Format Preferences
| Prefer | Best For | File Size | Compatibility |
|---|---|---|---|
WEBM_VP9 | Web apps, APIs | Small | Good |
MOV_PRORES | Professional editing | Large | Excellent |
STACKED_VIDEO | Universal compatibility | Medium | Universal |
PRO_BUNDLE | Advanced workflows | Medium | Universal |
AUTO | Let system choose | Varies | Good |
Complete Example
Here’s a complete example showing video loading, background removal, and basic composition:- Node.js
- Python
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!')
}
from videobgremover import (
VideoBGRemoverClient, Video, Background, Composition,
EncoderProfile, RemoveBGOptions, Prefer, Anchor, SizeMode
)
import os
def complete_example():
# 1. Initialize client
client = VideoBGRemoverClient(os.getenv('VIDEOBGREMOVER_API_KEY'))
# 2. Check credits
credits = client.credits()
print(f'Credits available: {credits.remaining_credits}')
# 3. Load and process video
video = Video.open('https://example.com/input.mp4')
options = RemoveBGOptions(prefer=Prefer.WEBM_VP9)
print('Removing background...')
transparent = video.remove_background(client, options)
# 4. Create composition
background = Background.from_color('#00FF00', 1920, 1080, 30)
comp = Composition(background)
comp.add(transparent, 'main').at(Anchor.CENTER).size(SizeMode.CONTAIN)
# 5. Export
comp.to_file('output.mp4', EncoderProfile.h264())
print('✅ Complete workflow finished!')
Related Classes
- VideoBGRemoverClient: API client for authentication and job management
- Composition: Video composition and layering
- Background: Background creation guide
- EncoderProfile: Export format configuration