doc.json

doc.json is the editable document: every effect the video carries, as plain JSON. Edit it and re-render; nothing re-runs the browser. The full JSON Schema ships in the npm package at schema/doc.schema.json, and vos validate <dir> lints the semantics before you spend a render.

A doc.json is one of two documents, told apart by its anchor. A recording document (a take) carries source and everything on this page. A program document carries program and the shared layers only: overlays, objects, audio, speed, export, plus program.tweenEdits (retimes over the config's recorded tweens, keyed by spec index) and program.duration (the program's own length when the config's is a placeholder). In a program directory doc.json omits program.config, because config.json is the config; a bare program with no layers has no document at all. The reference tables list the program document's own fields under program.

Camera

"zoom": [{ "id": "z1", "in": 4.0, "out": 8.5, "level": 2.2,
           "cx": 0.62, "cy": 0.4, "source": "manual" }]

• level is 1 to 5; 1.4 to 2.8 reads well, and anything past 3 is for genuine detail, briefly.
• A camera span (zoom, speed, tilt) may carry "anchor": { "step": "cta", "offset": -0.2 }, tying it to an actions.json step so vos plan --reuse re-times it exactly onto a re-recording. in/out stay authoritative; rendering never reads it.
• cx/cy are the focus point as normalized fractions of the video frame, 0 to 1, where 0.5, 0.5 is center. Never pixels; pixel values are the single most common mistake.
• focusMode: "auto" makes the camera follow the cursor through the span.
• source is the wand contract: "auto" spans are planner suggestions and regenerate on re-plan; set "manual" on any span you add or edit and it is never touched. Auto ids say their origin: z0 and up are click clusters, k0 and up are typing sessions (a frame held on the field being typed into), d0 and up are dwells.
• A deleted proposal stays deleted. Removing an "auto" span in the studio writes rejected: [{ id, lane, in, out }] at the top of the document (the lane and the source extent of what you removed, its step anchor with it), and no re-plan proposes that beat again: vos plan, plan --reuse on a re-recording, the studio's own re-plans. Write one by hand the same way when you delete an auto span in doc.json; a manual span never needs it.
• transition sets the speed of a span's ramps as named steps: instant | fast | smooth | slow, where smooth (the default) is the stock motion and instant is a hard cut. Zoom, tilt and camMotion spans all take it; the same control sits in each span's panel.

zoomStyle names the camera personality: glide (default) | focus | cinema | snappy | cut | none. Every style times the tilt track to its own zoom tempo, so a lean lands with its zoom; how far the card leans is tiltStyle. keynote and drift are retired names that still read as glide plus a medium tilt and cinema plus a subtle one.

Trims and pacing

"segments": [{ "in": 0.8, "out": 14.2 }],
"speed":    [{ "id": "s1", "in": 6, "out": 9, "rate": 2 }],
"freeze":   [{ "id": "f0", "at": 11.5, "seconds": 2 }]

segments are the kept footage spans; cut dead time here. speed rates run 0.1 to 16; 2x through typing is the classic use. freeze holds the frame just before a source moment for these output seconds, anywhere in the take: a pause on a state while a caption reads, a beat before a cut, the rest a poster ends on. Both are footage-anchored (they follow their frames through trims). The still, the frame that stands for the take (the shelf's cover, the frame a kit's card destinations render), is still in output seconds when you set it (drag the studio's Cover mark on the time ruler, vos plan --still <t>), else where the take's own last freeze begins (a template's freeze never counts), else the hero moment after the card and the opening words have entered. The card is on screen exactly while its clip runs, freezes included, and gone after it: clips that outlast the footage play over the ground alone, so a card under an end card is a freeze of its last frame.

Many media

"media":    [{ "id": "m1", "videoKey": "media/second.webm", "cursor": [], "meta": { "durationMs": 6000, "width": 1600, "height": 900 } }],
"segments": [{ "in": 0.8, "out": 14.2 }, { "in": 0, "out": 6, "media": "m1" }],
"zoom":     [{ "id": "u1", "in": 1, "out": 3, "level": 1.6, "cx": 0.5, "cy": 0.5, "media": "m1" }]

A take may hold several recordings or uploads: media lists the others, each the source shape with an id, and a segment on one plays it wherever it sits in the sequence. A source-anchored span names the media its seconds belong to; absent means the primary, source. A recording is media plus the facts only a capture has, so a file with no cursor track gets no dot and no auto-zoom. A media wears its own card: media[].frame carries the card-owned fields (inset for its placement and size, browserBar, radius, shadow, shadowContact, shadowColor, border, borderWidth, borderColor, fit, focus, focusFollow) over the take's frame while it plays. Absent fields fall to the take's; the bar names the media's recorded page, and an upload with no page wears none. The frame-wide fields (the aspect, the padding, the ground, the backdrop, the card's anim) stay the take's. Many cards: an image or video overlay may show a document media by reference ("key": "media:m1", media: alone the primary), with its cursor track and recorded page, and wear a card (frame: browserBar, a lean in degrees, shadow, shadowContact, shadowColor, cursor), drawn on its own plane above the primary card with the media's cursor and clicks inside it; a layer without frame is the flat picture. The primary card stays primary. The primary's sound plays at its own moments; another media's audio is not spliced into the cut yet.

A footage clip meets the clip beside it by a TRANSITION: segments[].anim carries exit (how it leaves at the boundary after it) and enter (how it arrives at the one before), by slide, fade, scale or none; a slide names its side (left | right | up | down: where an enter comes from, where an exit goes to; in from the right and out to the left by default), a step its seconds (0.15 to 2, never longer than half the shorter clip). An exit and the next clip's enter at one boundary run together as a push: the incoming clip plays live while the outgoing, frozen on its last frame, moves away; the camera rests through the window and one cursor dot crosses from the outgoing card's last point to the incoming's. The first clip's enter and the last clip's exit are the card's own (frame.anim). A page change inside one recording is the same thing: two clips of one media with the load between them cut, which vos plan proposes at every step the recorder marked navigated.

Tilt

"tilt": [{ "id": "u0", "in": 4, "out": 8, "rx": 6, "ry": -9, "source": "manual" }]

Source-anchored, non-overlapping regions where the 3D card leans to a pose and returns to flat rest. rx/ry are degrees (±45 hard, ±5 to 18 reads premium): positive rx brings the top edge toward the camera, positive ry the left edge, so leaning toward a right-side focus takes negative ry. Tilt is punctuation: at most one pose change per 5 second beat, paired with zoom moments. tiltStyle (off | subtle | medium | strong) records the Dynamic-tilt wand intensity that derives auto spans from the zoom plan.

Webcam

"cam": { "visible": true, "position": "bottom-left", "size": 0.25,
         "shape": "circle", "mirror": true },
"camMotion": [{ "id": "m1", "in": 3, "out": 8,
                "x": 0.5, "y": 0.55, "size": 0.45 }]

cam is the bubble's rest pose (it only applies when the take has a cam track): x/y place the bubble center as frame fractions and win over the position corner anchor, size is the diameter as a fraction of frame height, and window is a source-time visibility span.

camMotion animates the layout: source-anchored, non-overlapping spans where the bubble holds a pose and morphs there over about 0.65 seconds, settled at the span start. Outside spans it returns to the rest pose; spans close together morph pose-to-pose without returning to rest. Absent pose fields inherit the rest pose, so a span can move without resizing. The signature move is a bubble parked small in a corner that comes front-and-center (x: 0.5, y: 0.55, size: 0.45) while you talk to camera, then returns on its own.

Audio

"audio": [{ "id": "a1", "key": "https://assets.vos.so/music/ember-glow.mp3",
            "start": 0, "gain": 0.5, "duck": true, "loop": true }]

Output-anchored music and SFX, mixed and muxed on full renders. key is a file dropped into the take dir ("/music.mp3") or a hosted catalog track; the CC0 catalog with slugs, moods and durations is at GET vos.so/api/music. A music bed: start 0, gain around 0.5, duck: true under a voiced recording, loop to fill. micGain and systemGain (0 to 1) are the voice and system-audio master gains on recordings that carry them.

Frame and background

"frame": { "padding": 96, "radius": 12, "shadow": 0.5,
           "browserBar": { "kind": "mac" },
           "backgroundMedia": { "kind": "video",
             "key": "https://assets.vos.so/backgrounds/ember-drift-1080p.webm",
             "duration": 10, "dim": 0.2 } }

The card chrome: padding, corner radius, shadow, border, aspect ratio and the browser-bar mock. backgroundMedia puts a vos animation or a still behind the card; a video needs duration (its loop length; time is output-anchored modulo it, so trims never retime the ambience), and dim is a black scrim for legibility. The hand-picked set is GET vos.so/api/backdrops: write key from urls["1080p"], duration from the row, and frame.background from its ground so the frame before the first decoded frame is the loop's own colour. A loop's length is a fact of the asset, never a number you choose. Depth dials: frame.parallax (0 to 1) makes the media counter-pan with the zoom, and backgroundMedia.blur is design px. The card stroke is three fields: frame.border is the switch and its alpha (0 turns it off), frame.borderWidth its width in design px (absent = 1.5) and frame.borderColor any CSS colour (absent = white). The stroke grows outward from the card's edge, so it never covers the recording.

Overlays

"overlays": [{ "id": "t0", "kind": "text", "start": 1, "duration": 3,
               "text": "Ship it", "preset": "title",
               "transform": { "x": 0.5, "y": 0.82, "scale": 1, "rotation": 0 },
               "fx": { "fx": "typewriter", "unit": "char" } }]

Screen-space clips above the card, outside the zoom, output-anchored. Text presets: title (Lexend 600, 64px), caption (Lexend 400, 32px), label (JetBrains Mono, 22px), overridable with size, color, a hosted catalog family (GET vos.so/api/fonts), weight, align, letterSpacing, lineHeight, stroke, a box pill, and maxWidth as a wrap budget. transform.x/y are fractions of the frame, the zoom convention: 0.5/0.5 is center at any aspect ratio and a caption's lower third sits at y around 0.82. A layer about something on the page names it with pin ({ step | press | rect, side?, gap?, mark?, leader?, color? }) and is placed beside that thing, following it as the camera moves; transform is then the fallback for a pin that cannot resolve. The HTML layers guide has the fields. anim is how the clip enters and leaves, pure f(t), the one vocabulary every visual thing shares (the card's frame.anim, a prop's anim.idle): enter and exit take a kind (fade | rise | none; words also pop | blur | typewriter) or a step { kind, seconds, unit: block | line | word | char, direction, stagger }. The card's own frame.anim.enter also takes slide, and a footage clip's segments[].anim takes slide | fade | scale at its boundaries (see the transitions above).

Media kinds (image | video) ride the same lane: key (take-dir file or URL), width as a fraction of the frame width, radius, opacity, loop. Overlay video is clip-local in time and muted by design; soundtracks belong to audio.

Any overlay can move: motion is a list of pose keyframes over clip-local time, [{ "at": 0 }, { "at": 2, "x": 0.8, "scale": 1.4 }] slides and grows the element over its first two seconds. Values interpolate between poses with a smooth in-out ease, absent fields inherit the base transform, a hold is two identical poses, and opacity is a 0 to 1 multiplier on the clip's own alpha. In the studio, poses render as diamonds on the clip and dragging the element on the paused preview sets the pose at the playhead.

3D objects

"objects": [{ "id": "p0",
              "asset": { "kind": "primitive", "shape": "knot", "color": "#ffb03a" },
              "span": { "start": 1, "duration": 3 },
              "transform3d": { "x": 0.8, "y": 0.28, "z": 0.5,
                               "rx": 0, "ry": 40, "rz": 0, "scale": 0.18 },
              "animation": "spin" }]

World-space props between the card and the overlays. Assets are curated primitives (cube | sphere | torus | knot), a real GLB ({ "kind": "gltf", "key": "/model.glb" }, bbox-normalized so scale means the same thing), or extruded 3D text (kind: "text3d" with a catalog typeface and a fleet-audited material: standard | metal | glass | neon). x/y are frame fractions, z is world units in front of the card plane, scale is a fraction of frame height, animations (spin | float) are deterministic, and span gates visibility with soft fades. Props take the same motion pose keyframes as overlays, over the full 3D transform (x, y, z, rx, ry, rz, scale); the spin and float presets compose on top, so a prop can fly in on poses while it spins.

Cursor and export

cursor controls the drawn dot and click effects: visible, hideWhenIdle (fades out after about a second parked, always back at full opacity on a click), smoothing, size and click-effect styling. visible: false hides the dot only; the track still drives cursor-follow zoom.

export declares the intent: resolution (720p | 1080p | 2k | 4k), fps (30 or 60), format. Never set resolution above the footage; vos validate warns which preset matches the recording.

Field reference

Every field, generated from schema/doc.schema.json (the schema vos validate enforces), so this table cannot drift from the CLI. A * marks a required field.

Related

• Verbs for the --set overrides that test any of these fields from the CLI.
• The take directory for where this document lives.