> ## 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

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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')
    ```
  </Tab>
</Tabs>

### Background Removal

The main method for removing backgrounds using the API:

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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
    )
    ```
  </Tab>
</Tabs>

#### 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

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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
    ```
  </Tab>
</Tabs>

### Foreground Properties

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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
    ```
  </Tab>
</Tabs>

### Source Trimming

Use only specific parts of your transparent videos:

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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)
    ```
  </Tab>
</Tabs>

## RemoveBGOptions

Configure background removal processing:

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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)
    ```
  </Tab>
</Tabs>

### 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:

<Tabs group="code-examples">
  <Tab title="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>

  <Tab title="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!')
    ```
  </Tab>
</Tabs>

## Related Classes

* **[VideoBGRemoverClient](/api-reference/sdk-reference/client)**: API client for authentication and job management
* **[Composition](/api-reference/sdk-reference/composition)**: Video composition and layering
* **[Background](/video-composition/backgrounds)**: Background creation guide
* **[EncoderProfile](/api-reference/sdk-reference/encoders)**: Export format configuration