---
title: "Timing, duration and scenes"
canonical_url: https://docs.zvid.io/docs/concepts/timing/
source: docs/concepts/timing.md
content_revision: 6338386a1dd87e4a
---

# Timing, duration and scenes

Three different clocks appear in a video project. Use seconds for timing values unless a field's reference explicitly says otherwise.

| Clock | What zero means | Examples |
| --- | --- | --- |
| Project time | Start of the output video | Project-level visual/audio placement and subtitles |
| Scene-local time | Start of the containing scene | A visual inside `scenes[1]` starts relative to that scene, not the beginning of the entire output |
| Source time | Start of the input media file | `videoBegin`/`videoEnd` and `audioBegin`/`audioEnd` select source content |

Trimming source media and moving an element on the output timeline are separate actions. A source segment beginning at 20 seconds can still appear at time zero of a scene.

## Visual and audio placement

For visual elements, `enterBegin` and `exitEnd` bound visibility; `enterEnd` and `exitBegin` define the entrance/exit animation intervals. Keep the intervals ordered. See [common element timing](https://docs.zvid.io/docs/structure/common-properties/) and [animations](https://docs.zvid.io/docs/structure/animations/).

Audio uses `enter` and `exit` for timeline placement, plus separate source trimming fields. Playback `speed` changes how much output time a selected source segment occupies. For example, ten source seconds played at twice the normal speed occupy five output seconds. Use the supported ranges in [video](https://docs.zvid.io/docs/structure/video-elements/) and [audio](https://docs.zvid.io/docs/structure/audio-elements/).

## Fixed and automatic project duration

`durationMode: "fixed"` uses the normal explicit/default project-duration behavior. `durationMode: "auto"` derives duration from the content bounds and scene timeline, with an explicit project duration acting as a minimum. See [project structure](https://docs.zvid.io/docs/structure/) for the exact rules.

For hosted Auto-mode requests, give source media a resolvable timing bound: video/GIF needs an explicit end or source bound; audio needs an explicit bound or `matchDuration: true`. Do not assume validation has downloaded and probed every remote source. The renderer's ability to inspect intrinsic media duration is different from the submission validator's ability to prove a request is within account limits.

`matchDuration: true` marks an audio track to fit the resolved project/scene span rather than establish the length itself. Its use and interactions with trimming and looping are documented under [audio elements](https://docs.zvid.io/docs/structure/audio-elements/).

## Sequential scenes and overlap

Scenes play in array order. Each scene owns a local timeline. A transition overlaps the end of one scene with the beginning of the next; it does not add an extra segment.

For explicit scene lengths, the combined length is:

```text
sum(scene durations) - sum(actual transition overlaps)
```

For example, three four-second scenes with two one-second overlaps make ten seconds. Each overlap must fit the adjacent scenes. Use [scene transitions](https://docs.zvid.io/docs/structure/scenes/) for placement of `transition` and `transitionDuration` and [transition effects](https://docs.zvid.io/docs/structure/properties/xfade-effects/) for supported names.

Scene `duration: -1` requests auto-fit where supported. Elements that can stretch or loop do not necessarily determine a scene's end. Give text/image-only scenes explicit lengths. A default fallback is not a substitute for an intentional timeline.

## Stored templates require explicit scene durations

Stored **video templates** must use positive, explicit scene durations. Auto-fit scene duration is not accepted when saving or resolving a stored video template. When iteration repeats a scene, its explicit duration determines each repeated segment's length. Conditions and iteration affect the final scene count and duration before plan limits are checked.

Use free [template preview](https://docs.zvid.io/docs/templates/template-basics/) to inspect the resolved project and stats before rendering new data.

## Image projects have no playback timeline

Image rendering is a different branch of the project contract. Remove forbidden video timing fields and unsupported media types; do not simply change a video's `type` and submit it. `snapshotTime` can sample supported animated text content, but it does not make VIDEO/GIF elements valid in an image project. Follow [Rendering images](https://docs.zvid.io/docs/rendering-images/).

## Before rendering

Check the intended time origin for every field, source bounds after speed changes, transition overlaps, explicit template durations and the resolved output length. [Validate and estimate](https://docs.zvid.io/docs/validate-and-estimate/) the exact request, then use [job tracking](https://docs.zvid.io/docs/operations/render-lifecycle/) to inspect the result.