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 and 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 and audio.
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 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.
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:
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 for placement of transition and transitionDuration and transition 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 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.
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 the exact request, then use job tracking to inspect the result.