A virtual camera for auto-edited video that moves the way a person would operate it.
Automatic reframing — turning a wide two-person shot into a vertical clip that follows whoever is talking — almost always cuts the crop straight to the new speaker. The frame teleports.
That happens because the crop for each shot is computed independently of the one before it. Nothing connects shot N to shot N-1, so every speaker change is a discontinuity. Viewers cannot usually name what is wrong, but they read it instantly as machine-made.
Easing each individual move does not fix it. The move still starts from wherever the previous segment happened to end, and each segment restarts its own clock, so the same slide replays and snaps back at every cut.
Compute the camera position as one continuous function of time for the whole clip, then ask that function where the camera is on each output frame.
The camera chases the active speaker as a first-order damped follow with a velocity ceiling:
- it eases out of rest instead of starting at full speed
- it never exceeds a speed a human operator could manage
- it lags slightly, which reads as intent rather than lateness
- it holds still for small target movement, so a head shifting in frame is not treated as a new shot
- it holds the previous target through gaps where nobody was identified, rather than pulling to centre and back for no visible reason
Because the path is continuous by construction, whatever a segment starts at is exactly what the previous segment ended at. There is nothing left to snap.
from damped_camera import path, position_at, stillness
# cx is the horizontal centre of interest as a fraction of frame width.
# cx may be None for stretches where nobody was identified.
turns = [
{"t0": 0.0, "t1": 4.0, "cx": 0.32}, # left speaker holds the floor
{"t0": 4.0, "t1": 9.0, "cx": 0.68}, # right speaker takes over
{"t0": 9.0, "t1": 14.0, "cx": 0.30}, # back to the left
]
pts = path(turns, fps=30)
position_at(pts, 4.2) # where the camera is 0.2s after the handover
stillness(pts) # fraction of frames the camera is effectively stillPositions are fractions of frame width, so the path is resolution-independent. Multiply by frame width for pixels, or generate an ffmpeg crop expression directly:
from damped_camera.camera import crop_expression
expr = crop_expression(pts, frame_width=1920, crop_width=1080, fps=30)
# -> ffmpeg -vf "crop=1080:1080:'<expr>':0"The failure mode of a follow camera is not jerkiness — it is never settling. A camera that drifts continuously is as wrong as one that teleports.
On the three-turn example above:
| measure | value |
|---|---|
| frames effectively still | 89% |
| largest single-frame move | 0.0185 frame-widths |
| an instant cut between those targets would be | 0.36 frame-widths (19× larger) |
The camera is still for the great majority of the clip and moves decisively only when the floor actually changes hands.
| constant | default | meaning |
|---|---|---|
MAX_VELOCITY |
0.55 |
frame-widths per second; faster reads as a whip, not a follow |
DAMPING |
3.2 |
how hard it chases; higher catches up sooner, lower lags more |
DEAD_ZONE |
0.045 |
target movement below this is ignored entirely |
All three are arguments to path(), so they can be tuned per clip without touching the module.
This library takes speaker positions as input; it does not detect them. Anything that yields a
horizontal centre per time range works — face detection with mouth-landmark activity, diarisation
plus face tracking, or hand-authored turns. cx = None is a first-class value meaning "nobody
identified", and is handled by holding position rather than guessing.
pip install -e .
No dependencies. Python 3.9+.
MIT