How a document is put together

A guided tour of the format. The specification is the normative version; this explains why it is shaped the way it is.

A .ov is YAML. It must declare profile: geostory at the root — that is what makes it a geographic story rather than some other kind of OpenVerb document.

Scenes reference, they do not own

Six registries live at the root of the document, and scenes point into them by id:

This is why an annotation can outlive the scene that introduced it, and why the same place can be revisited without being defined twice. A scene is a short reference list:

scenes:
  - id: sc_03_crossing
    sequence: 3
    title: "Across the Atlantic"
    place_id: pl_atlantic
    basemap: bm_ocean
    transition: fly
    annotation_ids: [ann_gulf_stream, ann_north_atlantic_drift]
    timing: { mode: derived, intended: 15 }
    content:
      caption: "North-east, then round: the Atlantic gyre."
      narration: >-
        Off Newfoundland it leaves the coast and crosses the open
        ocean as the North Atlantic Drift.

Note that caption and narration are separate. The caption is what you read; the narration is what gets spoken. They are usually different lengths for good reasons.

Time is absolute

Every at and until — on audio, on media, on camera keyframes — is measured from the start of the whole document. Time 0.0 is the beginning of the story, not the beginning of a scene.

That stops edits cascading. Lengthen scene two and a clip pinned to 0:48 is still at 0:48, instead of every later offset quietly shifting. It also lets a clip cross a scene boundary, which a scene-relative timeline cannot express at all.

Scenes have a length, not a start

A scene does not say when it begins. It says how long it runs, and the player works out the rest: a scene starts where the previous one finished, plus its own delay if it has one. That is the only way the format can express a gap.

timing:
  mode: derived
  intended: 15      # what the author estimated
  measured: 12.80   # what the narration actually took

With mode: derived, the real duration is measured when it exists and intended otherwise. That is the whole point: an estimate holds the place until something generates the narration and finds out the truth.

When a scene is retimed, unlocked camera keyframes scale with it. Keyframes marked locked: true keep their absolute timing — for the moment that has to land on a particular word.

Bounds beat zoom

Frame the camera with camera.frame.bounds wherever you can. A bounding box survives a change of aspect ratio; center and zoom do not. A zoom level that framed a country on a widescreen laptop crops it on a phone.

Center and zoom are permitted, but the spec calls them cached conveniences — non-authoritative whenever bounds are present. Players should compute the fit rather than trust the number.

Similarly, mode: 3d is a request. A renderer without 3D must not reject the document — it degrades, usually to a wide shot. A document should never be unplayable because of an effect.

Unknown fields survive

A compliant parser must preserve fields it does not recognise, and a compliant serializer must write them back exactly as found.

This is what makes the format safe to pass between tools. QGIS project settings, editor state, an AI studio’s prompts — none of it is destroyed by a renderer that has never heard of it. It is also how new features get tried: the leader-line callouts this site draws were prototyped as an unrecognised leader block that validated, round-tripped and rendered before anything was added to the specification.

Host-specific data belongs under extensions, namespaced, to keep it out of the way of future top-level fields:

extensions:
  qgis:
    project: ./katrina.qgz
    render_crs: "EPSG:3857"