visualspec.1.0 RC
GitHub
Module

Timeline

When clips and markers occur

A timeline places clips on tracks, marks moments, and describes transitions between them. It is the editorial clock: what is on screen at a given time, and how one shot hands off to the next.

Use this module when You are describing video, a narrated deck, or any sequence whose meaning depends on time.

Keep in mind. A marker is a point in time you can refer to. It is not an animation keyframe. Keyframes live in Motion.

Raw schema:/schema/1.0/modules/timeline.schema.json · https://visualspec.dev/schema/1.0/modules/timeline.schema.json

How to read a definition.The paragraphs say what to write and why. “Exact constraints” opens the schema keywords (type, pattern, bounds) for people checking a validator. A sample at the bottom of each definition is the smallest JSON that shows the required shape. Values such as $ref inside a sample point at another definition. They are not fields you copy into a document.

transition

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include type and duration.

You may omit easing and motionRef. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
typerequiredtaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

durationrequiredduration

This is not a new shape. It reuses duration from the common module. Open that definition for the fields you can write.

easingeasing

This is not a new shape. It reuses easing from the motion module. Open that definition for the fields you can write.

motionRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

transitionJSON
{  "type": {    "$ref": "common#taxonomy"  },  "duration": {    "$ref": "common#duration"  }}

clip

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id, start, and duration.

17 other fields are optional. Include one only when you have a real value for it.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

startrequiredtime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

durationrequiredduration

This is not a new shape. It reuses duration from the common module. Open that definition for the fields you can write.

sourceIntime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

sourceOuttime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

sceneRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

assetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

entityRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

motionRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

actionRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

cameraRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

lightRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

effectRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

speednumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
timeRemappingarray<object>

Write a list. Each item follows the shape described under items.

The list needs at least 2 items.

Exact constraints
type
array
min items
2
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include time and sourceTime.

Exact constraints
type
object
additional properties
forbidden
timerequiredtime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

sourceTimerequiredtime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

transitionIntransition

This is not a new shape. It reuses transition from the timeline module. Open that definition for the fields you can write.

transitionOuttransition

This is not a new shape. It reuses transition from the timeline module. Open that definition for the fields you can write.

volumenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
mutedboolean

Write true or false.

Exact constraints
type
boolean
extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

clipJSON
{  "id": {    "$ref": "common#id"  },  "start": {    "$ref": "common#time"  },  "duration": {    "$ref": "common#duration"  }}

track

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id, type, and clips.

You may omit name, muted, locked, layer, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

typerequired"visual" | "video" | "audio" | "motion" | "action" | "camera" | "lighting" | "entity" | "effect" | "caption" | "subtitle"

Pick one of the 11 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "visual"
  • "video"
  • "audio"
  • "motion"
  • "action"
  • "camera"
  • "lighting"
  • "entity"
  • "effect"
  • "caption"
  • "subtitle"
namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
clipsrequiredarray<clip>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsclip

This is not a new shape. It reuses clip from the timeline module. Open that definition for the fields you can write.

mutedboolean

Write true or false.

Exact constraints
type
boolean
lockedboolean

Write true or false.

Exact constraints
type
boolean
layerinteger

Write a whole number.

Exact constraints
type
integer
extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

trackJSON
{  "id": {    "$ref": "common#id"  },  "type": "visual",  "clips": []}

marker

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and time.

You may omit label and actionRefs. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

timerequiredtime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

labelstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
actionRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

markerJSON
{  "id": {    "$ref": "common#id"  },  "time": {    "$ref": "common#time"  }}

timeline

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id, duration, and tracks.

You may omit name, fps, markers, loop, synchronization, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
durationrequiredduration

This is not a new shape. It reuses duration from the common module. Open that definition for the fields you can write.

fpsnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
tracksrequiredarray<track>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemstrack

This is not a new shape. It reuses track from the timeline module. Open that definition for the fields you can write.

markersarray<marker>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsmarker

This is not a new shape. It reuses marker from the timeline module. Open that definition for the fields you can write.

loopboolean

Write true or false.

Exact constraints
type
boolean
synchronizationarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include sourceRef, targetRef, and mode.

You may omit offset. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
sourceRefrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

targetRefrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

moderequired"beat" | "cue" | "dialogue" | "timecode" | "marker"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "beat"
  • "cue"
  • "dialogue"
  • "timecode"
  • "marker"
offsettime

This is not a new shape. It reuses time from the common module. Open that definition for the fields you can write.

extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

timelineJSON
{  "id": {    "$ref": "common#id"  },  "duration": {    "$ref": "common#duration"  },  "tracks": []}