> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videobgremover.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Video & Foreground Classes - Video Background Removal SDK

> Complete guide to Video and Foreground classes in VideoBGRemover SDK. Learn video loading, AI-powered background removal, and transparent video handling.

## Video Class

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

### Loading Videos

> [tab] Node.js
>
> ```typescript theme={"dark"}
> 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'
> })
> ```

> [tab] Python
>
> ```python theme={"dark"}
> 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:

> [tab] Node.js
>
> ```typescript theme={"dark"}
> 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
> })
> ```

> [tab] Python
>
> ```python theme={"dark"}
> 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 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

> [tab] Node.js
>
> ```typescript theme={"dark"}
> 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'
> })
> ```

> [tab] Python
>
> ```python theme={"dark"}
> 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

> [tab] Node.js
>
> ```typescript theme={"dark"}
> // 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())
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # 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:

> [tab] Node.js
>
> ```typescript theme={"dark"}
> // 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]
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # 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:

> [tab] Node.js
>
> ```typescript theme={"dark"}
> 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)
> ```

> [tab] Python
>
> ```python theme={"dark"}
> 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:

> [tab] Node.js
>
> ```typescript theme={"dark"}
> 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!')
> }
> ```

> [tab] Python
>
> ```python theme={"dark"}
> 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](https://docs.videobgremover.com/sdk-reference/client.md)**: API client for authentication and job management
* **[Composition](https://docs.videobgremover.com/sdk-reference/composition.md)**: Video composition and layering
* **[Background](https://docs.videobgremover.com/video-composition/backgrounds.md)**: Background creation guide
* **[EncoderProfile](https://docs.videobgremover.com/sdk-reference/encoders.md)**: Export format configuration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.