---
name: timelapse_hyperlapse
description: Plan and assemble timelapse and hyperlapse videos end to end: interval math for the subject, exposure smoothing, hyperlapse shooting discipline, and ffmpeg assembly with deflicker and stabilization. Triggers on timelapse, hyperlapse, interval timer, frame sequence assembly, or deflicker requests.
---

# Timelapse and Hyperlapse

## Purpose
Turn a photo sequence (or a plan for one) into a polished timelapse or hyperlapse clip: pick the right interval, keep exposure smooth, stabilize the result, assemble with ffmpeg.

## Workflow

### 1. Plan the interval
Run `bin/timelapse_plan.py --clip 10 --fps 24 --shoot 3600` (clip seconds, playback fps, shoot duration in seconds) to get the frame count and interval. Or solve by hand:

- frames needed = clip_seconds x fps
- interval = shoot_seconds / frames needed
- real-time compression = shoot_seconds / clip_seconds

Starting intervals by subject (details in `references/interval_subjects.md`):

| Subject | Interval |
|---|---|
| Fast clouds, crowds, traffic | 1-3s |
| Sunset, moderate clouds | 3-8s |
| Stars | exposure time + write margin |
| Construction, plants, slow change | 30s to minutes |

Set shutter to about half the interval for smooth motion (the timelapse version of the 180-degree rule). A 5s interval with a 2.5s exposure needs an ND filter in daylight. Short exposures give crisp, choppy motion; long exposures give creamy blur.

For a hyperlapse, also pick a step distance: 1-2 steps between frames is the common starting point, wider apart in open ground, inches apart in tight spaces. More ground covered per step = faster apparent travel.

### 2. Shoot (or prep) with discipline
Lock everything manual: focus, aperture, shutter, ISO, white balance. Auto anything flickers.

Hyperlapse only: pick one fixed reference point in the subject (a window corner, the tip of a tower) and keep the center crosshair or a viewfinder dot on it for every shot. Walk a straight line; ground lines or two tripod legs on a line keep geometry consistent. Take test frames first and reshoot early mistakes. Never pause mid-shoot under moving clouds (they jump in the final clip).

### 3. Smooth exposure
Flicker has two causes: camera settings that drifted (fix in step 2 next time) and natural light change. Order of operations:

1. Deflicker BEFORE heavy edits. Non-linear adjustments (dehaze, clarity) baked in early can create contrast flicker that no deflicker can undo.
2. For day-to-night ramps: keyframe the exposure at turning points (first frame, last frame, anywhere light changes direction) and interpolate between them, or use LRTimelapse's Visual Deflicker: drag the smoothing slider until the smoothed curve follows the real light trend while flattening frame-to-frame jumps. Repeat with Refine if needed. Clipped highlights cannot be recovered.
3. Quick ffmpeg-only path: `deflicker=mode=pm:size=10` in the build script's filter chain. Keep it conservative; over-correction looks plasticky.

### 4. Assemble
`bin/timelapse_build.py frames_dir out.mp4` does the full build:

1. Validates the frames (counts images, checks they sort in sequence).
2. Applies optional `deflicker` and `tblend=average` (cheap motion smoothing between frames).
3. Assembles at the chosen fps with `-framerate`, `libx264`, `-crf 18`, `-pix_fmt yuv420p`.
4. Optional stabilization pass (`--stabilize`): two-pass `vidstabdetect`/`vidstabtransform` with `optzoom=1` and an `unsharp` cleanup, or single-pass `deshake` if vidstab is missing.
5. Optional `--fps 60 --interpolate` adds `minterpolate` for smoother playback (slow on long sequences).

For a hyperlapse the shooting discipline (step 2) is the stabilizer; the post pass only removes residue. Run the stabilize pass on the assembled clip.

Full command reference lives in `references/ffmpeg_recipes.md`.

## Output Contract
- A `timelapse_plan` report: frames needed, interval in seconds, total shoot time, suggested shutter speed.
- A finished MP4: H.264, yuv420p, CRF 18 by default, at 24 fps minimum (choppiness below 24 is noticeable).
- No over-processed look: deflicker and smoothing kept conservative, and the build logs which filters ran.

## Operating Rules
1. Never invent numbers, dates, quotes, or specs. Every factual claim in output text must trace to a searched source or be framed as opinion.
2. Interval math first, always. A beautiful render of the wrong interval is a wasted shoot.
3. Manual camera settings are non-negotiable advice; if the user cannot lock exposure, say what will flicker and why.
4. Deflicker before creative grading, both in the pipeline and in advice.
5. Test the build script on the actual frame set before announcing the clip is done; if frames are missing or misnumbered, report it instead of guessing.
6. Prefer glob input (`-pattern_type glob`) when filenames are irregular; use `%05d` sequences only when numbering is clean.