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

# Clip Parameters

> The Clip object wraps an Asset and controls how it appears on screen. Complete reference for duration, geometry, visual effects, filters, transitions, and layering.

The Clip object wraps an Asset and controls how it appears on screen. Think of the Asset as your raw content (the video file, image, or text), and the Clip as all the presentation decisions - where it appears, how big it is, what color effects it has, how it fades in and out. This guide documents all available Clip parameters and their interactions.

## Editor Architecture

Asset → Clip → Track → Timeline

* Asset: Raw content (what to show)
* Clip: Presentation control (how to show it)
* Track: Layering container (for stacking multiple clips)
* Timeline: Final composition (the output video)

This separation lets you reuse the same asset in multiple clips with different visual treatments - same video, but one clip shows it full-screen while another shows it as a small picture-in-picture overlay.

## Clip Parameters

### Core Parameters

| Parameter | Type  | Description                                                                                    |
| :-------- | :---- | :--------------------------------------------------------------------------------------------- |
| asset     | Asset | The content to display (`VideoAsset`, `ImageAsset`, `AudioAsset`, `TextAsset`, `CaptionAsset`) |
| duration  | float | Clip length in seconds                                                                         |

### Geometry Parameters

| Parameter | Type     | Description                                                          |
| :-------- | :------- | :------------------------------------------------------------------- |
| fit       | Fit      | Scaling behavior: `Fit.crop`, `Fit.contain`, `Fit.cover`, `Fit.none` |
| position  | Position | Anchor point (9 zones: `top_left`, `center`, `bottom_right`, etc.)   |
| offset    | Offset   | Fine-tune position with `x`/`y` coordinates                          |
| scale     | float    | Size multiplier (`0.0` to `10.0`, default: `1.0`)                    |

### Visual Effect Parameters

| Parameter  | Type       | Description                                             |
| :--------- | :--------- | :------------------------------------------------------ |
| filter     | Filter     | Color treatment (`greyscale`, `blur`, `contrast`, etc.) |
| opacity    | float      | Transparency (`0.0` = invisible, `1.0` = opaque)        |
| transition | Transition | Fade `in_`/`out` effects                                |

## Scale Parameter

The scale parameter is a size multiplier applied after fit mode. First, the fit mode handles the aspect ratio and scales your content to match the timeline, then scale multiplies that result. This is useful for creating picture-in-picture effects (scale=0.3 for a tiny corner video) or zoom effects (scale=1.5 to enlarge).

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Clip, VideoAsset, Position

  clip = Clip(
      asset=VideoAsset(id=video.id),
      duration=10,
      scale=0.5,  # 50% of original size
      position=Position.top_left
  )
  ```

  ```javascript Node.js theme={null}
  import { Clip, EditorVideoAsset, Position } from 'videodb';

  const clip = new Clip({
      asset: new EditorVideoAsset({ id: video.id }),
      duration: 10,
      scale: 0.5,  // 50% of original size
      position: Position.topLeft
  });
  ```
</CodeGroup>

Range: `0.0` to `10.0` (default: `1.0`)

Example with `scale=0.5` and `Position.top_left`

<video controls>
  <source src="https://play.videodb.io/v1/62ec501f-b21f-4780-b4de-4dce8e2bacf1.m3u8" type="application/x-mpegURL" />
</video>

## Opacity Parameter

The opacity parameter controls transparency, letting you create semi-transparent overlays, subtle watermarks, or fade effects. At `1.0` your clip is fully solid, at `0.5` it's half-transparent, and at `0.0` it's completely invisible.

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Clip, VideoAsset

  clip = Clip(
      asset=VideoAsset(id=video.id),
      duration=10,
      opacity=0.5  # 50% transparent
  )
  ```

  ```javascript Node.js theme={null}
  import { Clip, EditorVideoAsset } from 'videodb';

  const clip = new Clip({
      asset: new EditorVideoAsset({ id: video.id }),
      duration: 10,
      opacity: 0.5  // 50% transparent
  });
  ```
</CodeGroup>

Range: `0.0` (invisible) to `1.0` (opaque)

Example with `opacity=0.3`

<video controls>
  <source src="https://play.videodb.io/v1/e25b9c92-af09-44d2-833d-c6509b89ecee.m3u8" type="application/x-mpegURL" />
</video>

## Filter Parameter

The filter parameter applies color and visual treatments to your clip. These are global effects that change the entire clip's appearance - you can make it black and white, blur it for backgrounds, adjust contrast, or create stylistic looks. Each clip can have one filter applied.

<CodeGroup>
  ```python Python theme={null}
  Filter.greyscale   # Remove color (black and white)
  Filter.blur        # Blur the video
  Filter.contrast    # Increase contrast
  Filter.boost       # Boost contrast and saturation
  Filter.muted       # Reduce saturation and contrast
  Filter.darken      # Darken the scene
  Filter.lighten     # Lighten the scene
  Filter.negative    # Invert colors
  ```

  ```javascript Node.js theme={null}
  Filter.greyscale   // Remove color (black and white)
  Filter.blur        // Blur the video
  Filter.contrast    // Increase contrast
  Filter.boost       // Boost contrast and saturation
  Filter.muted       // Reduce saturation and contrast
  Filter.darken      // Darken the scene
  Filter.lighten     // Lighten the scene
  Filter.negative    // Invert colors
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Clip, VideoAsset, Filter

  clip = Clip(
      asset=VideoAsset(id=video.id),
      duration=10,
      filter=Filter.greyscale
  )
  ```

  ```javascript Node.js theme={null}
  import { Clip, EditorVideoAsset, Filter } from 'videodb';

  const clip = new Clip({
      asset: new EditorVideoAsset({ id: video.id }),
      duration: 10,
      filter: Filter.greyscale
  });
  ```
</CodeGroup>

Example with `Filter.greyscale`

<video controls>
  <source src="https://play.videodb.io/v1/10834889-7e74-43d3-a608-b633a8c5b729.m3u8" type="application/x-mpegURL" />
</video>

## Transition Parameter

The transition parameter controls fade in/out effects, making your clips appear and disappear smoothly instead of cutting abruptly. The fade happens over the first and last N seconds of your clip - so a 2-second fade means the first 2 seconds gradually appear, and the last 2 seconds gradually disappear.

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Clip, VideoAsset, Transition

  clip = Clip(
      asset=VideoAsset(id=video.id),
      duration=10,
      transition=Transition(
          in_="fade",   # Fade in effect (note the underscore)
          out="fade",   # Fade out effect
          duration=2    # Transition duration in seconds
      )
  )
  ```

  ```javascript Node.js theme={null}
  import { Clip, EditorVideoAsset, Transition } from 'videodb';

  const clip = new Clip({
      asset: new EditorVideoAsset({ id: video.id }),
      duration: 10,
      transition: new Transition({
          in: "fade",   // Fade in effect
          out: "fade",  // Fade out effect
          duration: 2   // Transition duration in seconds
      })
  });
  ```
</CodeGroup>

Example:

<video controls>
  <source src="https://play.videodb.io/v1/acb06e75-6a52-408a-8614-c2742162188f.m3u8" type="application/x-mpegURL" />
</video>

Parameters:

* `in_`: Transition type for entry (use `in_` with underscore because `in` is a Python keyword)
* `out`: Transition type for exit
* `duration`: Length of transition in seconds

## Complete Example

Here's a clip using multiple parameters:

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Clip, VideoAsset, Position, Filter, Transition

  clip = Clip(
      asset=VideoAsset(id=video.id),
      duration=10,
      position=Position.bottom_left,
      scale=0.7,
      opacity=0.3,
      filter=Filter.greyscale,
      transition=Transition(in_="fade", out="fade", duration=3),
      fit=None
  )
  ```

  ```javascript Node.js theme={null}
  import { Clip, EditorVideoAsset, Position, Filter, Transition, Fit } from 'videodb';

  const clip = new Clip({
      asset: new EditorVideoAsset({ id: video.id }),
      duration: 10,
      position: Position.bottomLeft,
      scale: 0.7,
      opacity: 0.3,
      filter: Filter.greyscale,
      transition: new Transition({ in: "fade", out: "fade", duration: 3 }),
      fit: Fit.none
  });
  ```
</CodeGroup>

## Parameter Reference

| Parameter  | Type       | Default  | Description                    |
| :--------- | :--------- | :------- | :----------------------------- |
| asset      | Asset      | Required | Content to display             |
| duration   | float      | Required | Clip length in seconds         |
| fit        | Fit        | Fit.crop | Scaling mode                   |
| position   | Position   | None     | Anchor point (9 zones)         |
| offset     | Offset     | None     | Fine position adjustment       |
| scale      | float      | 1.0      | Size multiplier (`0.0`-`10.0`) |
| opacity    | float      | 1.0      | Transparency (`0.0`-`1.0`)     |
| filter     | Filter     | None     | Color treatment                |
| transition | Transition | None     | Fade effects                   |

## What You Can Build

<CardGroup cols={2}>
  <Card title="Intro & Outro Automation" icon="play" href="/examples-and-tutorials/programmatic-editing/intro-outro">
    Use clip positioning and transitions for seamless brand intros
  </Card>

  <Card title="Brand Elements" icon="image" href="/examples-and-tutorials/programmatic-editing/brand-elements">
    Overlay logos and watermarks with opacity and positioning
  </Card>

  <Card title="TikTok Lyric Videos" icon="music" href="/examples-and-tutorials/content-factory/tiktok-lyric-video">
    Combine clips with text overlays and visual effects
  </Card>

  <Card title="Faceless Video Creator" icon="film" href="/examples-and-tutorials/content-factory/faceless-video-creator">
    Layer multiple clips with filters and transitions
  </Card>
</CardGroup>

***

## Next Steps

<Card title="Clip Control Layer" href="https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/editor/feature/clip_control_layer.ipynb" icon="book-open">
  Hands-on experimentation with all Clip parameters, effects, and transitions.
</Card>