▶VIDEO.md

Open format · version 1

Every skill has a SKILL.md.
Every video gets a VIDEO.md.

VIDEO.md describes one video for AI agents and programs: what it shows and says, shot by shot, and how it was made. It starts with a small card and opens up level by level, so a model reads only what the question needs.

Read the spec Use it in an agent Write packages 
pip install videomd
videomd check path/to/package

A card first

The front matter of VIDEO.md is all an agent needs to decide whether to open a package. Keep the cards of a whole library in context; open a package only when a question needs it.

---
videomd: 1
name: coffee-ad
description: >-
  A 10-second coffee ad: a hand pours coffee
  into a glass, then a card shows the price.
  Filmed (70%) + code-rendered card (30%).
source: {file: coffee-ad.mp4, sha256: 9f86d0…, duration: 10.0}
shots: 2
lang: en
---

One line per shot

The timeline is the spine of a package. A key ending in ~ is inferred; the others are seen or measured. Flags point at the shots that need a second look.

#01 0.0-7.0 | seen hand pours coffee into a glass
  | camera handheld | made~ filmed 92%
#02 7.0-10.0 | seen beige card with the price
  | overlay title | made~ code render 61%
  · runner-up screen capture 30%
  | flag low confidence

Read only what the question needs

  1. L0
    Card 100–300 tokens

    What the video is about, and whether to open it.

  2. L1
    Overview and map 1–2k

    The verdict, the open questions, and every file with its size in tokens.

  3. L2
    Timeline and topics a few thousand

    One line per shot; sound, cast, packaging, remake each in their own file.

  4. L3
    One shot hundreds + frames

    What is seen, what is inferred and why, with images to check it.

  5. L4
    Raw data any

    For programs. A model does not need it.

Many videos in context

Cards cost a few hundred tokens each, as skills do. An agent can know a whole library and still answer from a few thousand tokens.

Seen apart from inferred

In the syntax (made~) and in the data (inferred, with a probability and who decided). Guesses are not passed on as facts.

Cost before reading

Every file states its size in tokens, so a model can decide what is worth opening.

A stable surface for programs

Front matter with a JSON Schema, a small line grammar, fixed ids. Unknown fields are ignored, so the format can grow.

From an ad to a feature film

Scenes and a split timeline for long videos, takes and beats for one-take streams, layers for split screens and reactions, camera moves and transitions for whip pans, orbits and match cuts.

Starts small

Six fields make a valid card. Judging how a video was made is an optional module.

Plain files

A package is a folder of Markdown. Copy it, zip it, commit it, read it without any tool.

Go further