avdm

The Audiovisual Scene Data Model (AVDM-001), revision 0.2: one canonical document for one shot, and the serializers that render it into the text a video model reads.

media ──observe──▶ SceneDocument ──render──▶ caption / prompt ──generate──▶ media
                    (observed)                 to_h3, to_prose
                    SceneDocument (planned) ──render──┘

The same serializer writes a training caption from an observed document and an inference prompt from a planned one, so the two registers match by construction.

What is in 0.2

The subset is a single observed or planned shot: Asset, Shot with camera moves, Entity, Event, AudioCue, Observation, exact rational TimeRanges, and per-aspect coverage. 0.2 adds attribute claims on entities and on the shot, from a controlled vocabulary, where unclear is always an answer and never a default. When a claim is specified, the serializers write the picture from the claims, not from free prose. Intent, constraints, baselines, bindings and edits come later.

Use

import avdm

doc = avdm.assemble(avdm.SceneDocument.model_validate_json(raw))  # apply evidence rules
assert not avdm.validate(doc)
caption = avdm.to_h3(doc, trigger="ohwx")

Develop

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run ty check

To adopt AVDM in another repository, point that repository's agent at AGENTS.md.