> ## 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.
# Aspect Ratio Control
> Control how assets scale when dimensions don't match the timeline. The fit parameter handles the mismatch (crop, letterbox, stretch), while position and offset control placement.
## 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.
### `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.
### `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.
### `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.
### Code Example
```python Python theme={null}
from videodb.editor import Fit
clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
fit=Fit.crop # or Fit.contain, Fit.cover, Fit.none
)
```
```javascript Node.js theme={null}
import { Fit, Clip, VideoAsset } from 'videodb';
const clip = new Clip({
asset: new VideoAsset(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`**
### Code Example
```python Python theme={null}
from videodb.editor import Position
clip = Clip(
asset=VideoAsset(id=video.id),
duration=10,
position=Position.top_left,
fit=None
)
```
```javascript Node.js theme={null}
import { Position, Clip, VideoAsset } from 'videodb';
const clip = new Clip({
asset: new VideoAsset(video.id),
duration: 10,
position: Position.topLeft,
fit: null
});
```
## 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)`**
### Code Example
```python Python theme={null}
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
)
```
```javascript Node.js theme={null}
import { Offset, Clip, VideoAsset, Position } from 'videodb';
const clip = new Clip({
asset: new VideoAsset(video.id),
duration: 10,
position: Position.center,
offset: new 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
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 |
```python Python theme={null}
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)
)
```
```javascript Node.js theme={null}
import { Clip, VideoAsset, Fit, Position, Offset } from 'videodb';
const clip = new Clip({
asset: new VideoAsset(video.id),
duration: 10,
fit: Fit.crop,
position: Position.right,
offset: new Offset({ x: -0.1, y: 0 })
});
```
## What You Can Build
Create vertical 9:16 videos optimized for TikTok and Reels
Position logos and overlays precisely using fit and offset
Control aspect ratios for multi-platform content
***
## Next Steps
Hands-on experimentation with all fit modes, 9-zone positioning, and aspect ratio handling.
