Skip to content
videodb
VideoDB Documentation
Share
Explore

Fit & Position: Aspect Ratio Control

⁠
Open in Collab
⁠
When your asset’s dimensions don’t match the timeline resolution, you run into the classic aspect ratio problem - like trying to fit a vertical phone video into a horizontal landscape frame, or vice versa. The fit parameter determines how to handle this mismatch (crop it? add black bars? stretch it?), while position and offset let you control exactly where the content sits on screen.
⁠

Fit Modes

The fit parameter determines how an asset scales to match the timeline resolution.

Fit.crop (default)

Scales asset to fill viewport while maintaining aspect ratio
Edges are cropped if aspect ratios differ
This is the default because it creates clean, full-frame compositions without black bars. The tradeoff is you might lose some content at the edges, but everything stays proportional and the frame stays filled.
⁠
This embedded link can't be shown.
⁠

Fit.contain

Scales asset to fit entirely within viewport while maintaining aspect ratio
May add letterboxing (black bars) if aspect ratios differ
Use this when you need to guarantee that all of your content is visible, even if it means having black bars on the sides or top and bottom. Nothing gets cropped, but you sacrifice the full-frame look.
⁠
This embedded link can't be shown.
⁠

Fit.cover

Stretches asset to fill viewport, ignoring aspect ratio
May cause distortion
This mode stretches the content to fill the frame regardless of proportions. You’ll rarely need this unless you specifically want the stretched effect, or you’re working with content that already matches your timeline’s aspect ratio exactly.
⁠
This embedded link can't be shown.
⁠

Fit.none

Preserves original pixel dimensions
No scaling applied
This keeps your asset at its exact original size, which is useful for things like logos, overlays, or picture-in-picture effects where you want pixel-perfect control. The content appears at its native resolution regardless of timeline size.
⁠
This embedded link can't be shown.
⁠

Code Example

from videodb.editor import Fit

clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
fit=Fit.crop # or Fit.contain, Fit.cover, Fit.none
)
Note: You can also use fit=None (Python None) which is equivalent to Fit.none.
⁠

Position

The position parameter places the asset in one of 9 preset zones on the viewport. Think of your screen divided into a 3x3 grid - you can anchor your content to any of these zones, from corners to edges to dead center.
Position.top_left Position.top Position.top_right
Position.left Position.center Position.right
Position.bottom_left Position.bottom Position.bottom_right
Example with Position.left
This embedded link can't be shown.
⁠

Code Example

from videodb.editor import Position

clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
position=Position.top_right,
fit=None
)
⁠

Offset

The offset parameter provides fine-grained position control using relative coordinates. Sometimes the 9 preset zones aren’t quite right - maybe you want something centered but nudged slightly to the left, or positioned with a specific margin. That’s where offset comes in, letting you tweak positions with precision.
Example Offset(x=-0.25)
⁠
This embedded link can't be shown.
⁠

Code Example

from videodb.editor import Offset

clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
position=Position.center,
offset=Offset(x=0.15, y=0.1) # x: horizontal, y: vertical
)
Coordinate System:
x : Horizontal shift (-1.0 to 1.0)
Positive values move right
Negative values move left
y : Vertical shift (-1.0 to 1.0)
Positive values move down
Negative values move up
Values are relative to viewport dimensions
⁠
image.png
⁠
⁠
Example: offset=Offset(x=0.1, y=0) on a 1080px wide viewport moves the clip 108px to the right.
⁠

Parameter Reference

Parameter
Type
Description
fit
Fit
Scaling behavior : Fit.crop, Fit.contain, Fit.cover, Fit.none
position
Position
Anchor point : Position.top_left, Position.center, etc. (9 options)
offset
Offset
Fine-tuning position with x/y coordinates
⁠
from videodb.editor import Clip, VideoAsset, Fit, Position, Offset

clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
fit=Fit.crop,
position=Position.right,
offset=Offset(x=-0.1, y=0)
)
⁠

Next Steps:

For hands-on experimentation with all fit modes and position options, see:
Fit, Position & Aspect Ratios
⁠
⁠

Fit Modes
Fit.crop (default)
Fit.contain
Fit.cover
Fit.none
Code Example
Position
Code Example
Offset
Code Example
Parameter Reference
Next Steps:
Gallery
 
Want to print your doc?
This is not the way.
Try clicking the ··· in the right corner or using a keyboard shortcut (
CtrlP
) instead.