Skip to content
Scales asset to fill viewport while maintaining aspect ratioEdges are cropped if aspect ratios differ
Scales asset to fit entirely within viewport while maintaining aspect ratioMay add letterboxing (black bars) if aspect ratios differ
Stretches asset to fill viewport, ignoring aspect ratioMay cause distortion
Preserves original pixel dimensionsNo scaling applied
x : Horizontal shift (-1.0 to 1.0)Positive values move rightNegative values move lefty : Vertical shift (-1.0 to 1.0)Positive values move downNegative values move upValues are relative to viewport dimensions
VideoDB Documentation
- Pages
Share
Explore
Fit & Position: Aspect Ratio Control
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.
crop (default)
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.
contain
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.
cover
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.
none
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.
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 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 left
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 )
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:
Example: 0) on a 1080px wide viewport moves the clip 108px to the right.
Parameter Reference
Parameter
Type
Description
fit
Fit
Scaling behavior : crop, contain, cover, none
position
Position
Anchor point : top_left, center, etc. (9 options)
offset
Offset
Fine-tuning position with x/y coordinates
There are no rows in this table
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:
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ··· in the right corner or using a keyboard shortcut (
CtrlP
) instead.