For developers and AI agents

The Prewatch folder

Everything Prewatch learns about your footage is written as plain files in a folder called Prewatch. People, scripts and AI agents can read it without Prewatch, and without opening a single video.

Start with INDEX.md How agents read it

Layout

Plain files, next to the footage

Markdown and TSV to read, JSON to parse, WebVTT and SubRip to import, JPEG to look at. Nothing is locked in a database.

Iceland 2026 / Prewatch412 clips

Prewatch/
  INDEX.md             start here
  scenes.md            one block per scene
  clips.tsv            one line per clip
  moments.tsv          ranges to cut, q 1–5
  transcripts.md       every line said
  summaries.md         every description
  paths.tsv            stem, clip id, path
  catalog.md           the full catalogue
  catalog.jsonl        the same, as JSON
  transcripts.jsonl    every line, as JSON
  groups.json          days and scenes
  prewatch.json        the descriptor
  writer.json          who is indexing now
  README.md            the guide for agents
  clips/
    c_3f9a1c2e7b04d815/
      manifest.json      the clip's record
      sheet_overview.jpg contact sheet
      kf/                keyframes, 3 sizes
      transcript.json    words with times
      transcript.vtt     subtitles
      transcript.srt     subtitles

Where it livesBy default in a Prewatch folder inside the footage folder, so the index travels with the media to another drive, a NAS or a synced folder, and the next Mac doesn't index it again. Or in a library on your Mac, which stays readable while the footage drive is unplugged. The layout is the same.
Clips are known by contentA clip id is a hash of the file's bytes, never its path. The same clip on a NAS, an SSD and a laptop is one record, whatever the mount point.
Times are exactManifests store every time as seconds, the native frame and the timecode together. The folder-level files use seconds.
One writer, many readersOne Mac indexes a folder. Any number of Macs and agents can read it at the same time.
It explains itselfEvery Prewatch folder carries a README.md with the whole format, for the agent that finds it.
What is not in itNo copies of your video or audio, and no voiceprints: those stay on the Mac that indexed the footage. The names you give people are in it, in people.json. If your camera recorded GPS, the coordinates are in the folder; keep that in mind before sharing it.

The read layer

Seven small files to read first

Written for a reader that pays per token. Together they are usually enough to choose the clips and their in and out points.

[01]INDEX.md

Start here. Under 2 KB: the counts, the days, the legends for the short codes in clips.tsv, and the other files in the order to read them, with their sizes.

Excerpt

# Prewatch index

`prewatch-read-layer` v1. 412 clips, 9 h 40 min of footage,
412 described, 38 with speech, 1906 moments; 6 days
(2026-07-12 to 2026-07-17), 41 scenes.

## Read in this order

1. `scenes.md`: every scene, its synopsis and its clips, 31 KB.
2. `clips.tsv`: one line per clip, 38 KB.
3. `moments.tsv`: events and best moments with in-points; grep it…

[02]scenes.md

One short block per scene: the time range, clip count and length, the mean position when the clips recorded one, a synopsis, the tags that set the scene apart, shot roles, spoken languages and the clips in capture order.

Excerpt

## 2026-07-14-b · 14:32–15:10 · 7 clips · 9 min 40 s · 64.02, -16.97
presenter talks to camera by river, summit behind; slow pan right along far ridge…
seen: summit, river, hiking, presenter · roles: ptc 2, broll 4, est 1 · speech: en 2
clips: A014_C004 A014_C005 A014_C006 A014_C007 A014_C008 A014_C009 A014_C010

[03]clips.tsv

One tab-separated line per clip: stem (the file name without its extension), day, start time, length, camera, camera motion, shot role, speech, quality flags and a caption of at most 12 words.

Excerpt · tab-separated

stem	day	t	dur	cam	motion	role	speech	flags	caption
A014_C005	07-14	14:29	41	A	lo	est	-	-	wide of valley, summit in cloud
A014_C006	07-14	14:32	240	A	st	ptc	en	ox	presenter talks to camera by river, summit behind
A014_C007	07-14	14:38	18	A	hh	broll	-	soft	boots crossing wet stones at river edge

[04]moments.tsv

Every event and best moment in the folder, merged into usable ranges: where each starts, how long it is usable (at least 2 s), the kinds of moment, a usability score from 1 to 5 and what happens. Search it rather than reading it whole.

Excerpt · tab-separated

stem	t	dur	kind	q	text
A014_C006	26.0	14.0	subject-enters	3	presenter walks into frame by the river
A014_C006	44.0	28.0	action+best	5	talks to camera: “three days of hiking to see this”
A014_C006	80.0	16.0	reveal	4	cloud clears off the summit

[05]transcripts.md

Everything said in the folder, clip by clip: start and end in seconds, the speaker (the name you gave, or Speaker 3) when voices were told apart, [unsure] where the recognizer doubted itself, and the English under any line in another language. transcripts.jsonl holds the same as JSON.

Excerpt

## A014_C006.MOV · `c_3f9a1c2e7b04d815` · 2026-07-14-b · 14:32:04 · en 0.98
[45.1–47.0] S1: okay, we made it
[47.2–50.1] S1: three days of hiking to see this
[51.4–52.6] S1: worth it [unsure]

[06]summaries.md

The full description of every clip, by scene and stem, with its tags.

[07]paths.tsv

Stem, clip id and path for every clip, so an agent can import the right file into an editor.

Excerpts from the example folder on the homepage, in the files' real formats. Codes like st (steady), ptc (talking to camera) and ox (overexposed) are explained in INDEX.md. Captions, shot roles, moments and summaries come from the optional descriptions, made with your own Claude or OpenAI key; without them those parts are empty and the rest is all there.

The full record

Everything else, for the clips that matter

The complete catalogue, and one folder per clip with its manifest, contact sheet, keyframes and transcript. Open these only when a decision needs the detail.

File	What it holds
`catalog.md, catalog.jsonl`	The folder catalogue: one entry per clip, by day and scene, with its whole summary, tags, camera, motion, flags, speech and location. The Markdown is for reading, the JSON Lines for scripts.
`groups.json`	The days and scenes, and the rules that cut them: a new scene starts after a long pause between clips or a move of more than a kilometer. Measured from the clips' own dates and locations, never from file or folder names.
`clips/<clip id>/manifest.json`	Everything known about one clip. The keys are listed below.
`clips/<clip id>/sheet_overview.jpg`	The whole clip on one contact sheet of up to 30 tiles, each tile mapped to a time in the manifest. Clips with many keyframes also get `sheet_detail_0000.jpg` and onward.
`clips/<clip id>/kf/`	The keyframes, taken at the start, middle and end of each shot and where the picture changes, each at 256, 768 and 1536 px on the long edge. Log footage gets a viewing transform, never a grade.
`clips/<clip id>/transcript.json, .vtt, .srt`	What was said, with segment and word times, as JSON and as WebVTT and SubRip subtitles you can import into an editor. `transcript.en.*` holds the English translation when the speech was in another language.
`clips/<clip id>/motion.json`	The camera-motion trajectory that the steady, handheld and shaky readings come from. Optional.
`people.json`	Everyone heard in the folder: the name you gave each person (or Speaker 3), and which speaker in which clip is them. Names only, no voice data. Saved by any Mac that can write to the folder.
`picks.json`	The transcript lines you ticked, as source-time ranges with their words, in your order. Your AI reads them with the picks tool.
`prewatch.json`	The folder's descriptor: format, schema, id, sidecar or library, the folder's transcription language and a copy of the indexing progress.
`writer.json`	A note from the Mac that is indexing the folder right now: its name, a heartbeat, and how many clips are indexed of how many. It is a note, not a lock.
`README.md`	The full guide to the folder, for any agent that finds it: the layout, every manifest key, the reading order and the rules for readers.

manifest.json · the main keysTimes: seconds, frame, timecode

tech: Codec, resolution, frame rate, duration, start timecode, color and log profile, and the camera's own metadata: make, model, lens, ISO, shutter, aperture, capture date and location when the file has them
shots: Each shot's start and end, how it began (continuous, cut, transition) and its camera motion: locked off, steady, handheld or shaky
keyframes, sheets: Every keyframe's time, files, sharpness and brightness; every contact-sheet tile's time
flags: Black, frozen, static, underexposed, overexposed, flat log, soft, duplicate, partial, with the range they cover
steady_segments, loops: The least shaky windows of each shot, and stretches that loop without a visible seam
audio: Whether there is speech, loudness, sound events, the language, the transcript and translation, and the speakers within the clip (S1, S2), linked to people in people.json
summary, tags, role, events, best_moments: The optional descriptions: what the clip shows, its shot role, and the moments to cut on, each marked when the model was unsure
models, generator, state: Which models and which engine wrote what, when, and why a clip has no description

How agents read it

Three ways in, the same files

An assistant in a chat app asks Prewatch. An agent with file access reads the folder. A script parses it.

Over MCP[01]

Claude, ChatGPT, Claude Code, Codex

Prewatch's MCP server answers from the read layer and the catalogue, in compact, paginated text. Locations are left out of every answer.

overviewevery folder, or one folder's days and scenes
searchwhat was seen and said, moments first
momentsusable ranges with timecode and the file path
clipeverything about one clip, compactly
framethe exact frame at a time, as an image
statuswhether a folder is still being indexed

With file access[02]

Any agent that can read files

Read INDEX.md, then scenes.md and clips.tsv.
Search moments.tsv and transcripts.md for what the edit needs.
Open a clip's sheet_overview.jpg only for the clips that matter.
Open a 768 px keyframe or the manifest only when a decision needs the detail.

grep -i summit Prewatch/moments.tsv

From a script[03]

Standard tools

TSV, JSON and JSON Lines parse with anything. The subtitle files import into an editor as they are.

awk -F'\t' 'NR > 1 && $5 >= 4' \
  Prewatch/moments.tsv
jq -r 'select(.speech) | .filename' \
  Prewatch/catalog.jsonl

Prewatch's engine has a command line for agents too. It is not part of the Mac app, and nothing here needs it.

Token cost

65 to 68% less to read

The full catalogue of a large folder is too long to read every session. The read layer carries nothing the manifests don't, in far fewer words: short codes explained once in INDEX.md, captions cut to 12 words, times in seconds.

An agent plans a cut from INDEX.md, scenes.md and clips.tsv, then searches moments.tsv for in and out points instead of reading anything whole.

381 clips−68%

catalog.md

110,241

Read layer

34,765

324 clips−68%

catalog.md

92,349

Read layer

29,369

99 clips−65%

catalog.md

31,251

Read layer

10,839

Tokens in three real folders of trip footage, counted with Claude's tokenizer, October 2026. Read layer = INDEX.md + scenes.md + clips.tsv.

Versions and rules

Versioned, documented, read-only

Every file says its versionEach file names its format and version (prewatch-read-layer v1, manifest schema 1). Every change to the format is recorded in a changelog with its reason.
New keys never break readersThe version goes up only for a change a reader can't ignore. Readers should ignore keys they don't know and tolerate missing optional sections.
Same index, same bytesNothing in the read layer depends on when it was written: the same manifests give the same files, so they diff cleanly and cache well.
Read, don't writePrewatch owns the folder and rewrites its files as it indexes. A clip folder without a manifest.json is a clip being written: skip it.
Is the folder done?writer.json with status idle and as many clips indexed as there are clips means the writing Mac has nothing left to do.
Earlier namesEarlier test builds called the folder Shotlog and its descriptor shotlog.json. It is the same format; Prewatch renames it the next time it indexes the folder.

Index once. Read it anywhere.

Notify me at launch Where each step runs

14 days free, then $59 a year or $7.99 a month. Works with your Claude or ChatGPT plan; timelines need DaVinci Resolve Studio 21.1+. Clip descriptions are optional and use your own API key, billed by Anthropic or OpenAI.