Where it lives
By default in a Shotlog folder inside the footage folder, so the index travels and syncs with the media: to another drive, a NAS or a synced folder, with no re-indexing on the next machine. Or in a library on your Mac, which stays readable while the footage drive is unplugged. The layout is the same either way.
- Clips are identified by content, a hash of the file, never by path. One clip on a NAS, an SSD and a laptop is one record, whatever the mount point.
- Every time is exact. Manifests store seconds, the native frame and the timecode together; the folder-level files use seconds.
- One writer, many readers. The Mac that indexes a folder keeps a lease file with its host and a heartbeat; any other Mac or agent can read along.
- It is self-describing. Every shotlog contains a README for the agent that finds it.
The files
INDEX.mdStart here. Under 2 KB: counts, days, the legends, and which files to read next, with their sizes.scenes.mdOne short block per scene: time, approximate position, a synopsis, what is seen, shot roles, speech, and the clips in it.clips.tsvOne line per clip: day, scene, length, camera, motion, role, speech, flags and a short caption.moments.tsvEvery event and best moment in the folder with an in-point, a duration, a kind and a usability score from 1 to 5. Search it rather than reading it whole.paths.tsvClip stem, clip id and path, for importing the right file into an editor.transcripts.mdEvery line said in the folder, with times in seconds, the speaker when known, doubt marks and the English translation.summaries.mdThe full description of each clip, by scene.catalog.md / .jsonlThe complete folder catalogue: one entry per clip, by day and scene.groups.jsonThe days and scenes, and the rules that cut them (long pauses, or a move of more than a kilometre).clips/<id>/manifest.jsonEverything about one clip: shots with camera motion, keyframes, the contact-sheet tile map, flags, technical and camera metadata, audio, descriptions and events.clips/<id>/sheet_overview.jpgThe whole clip on one image, every tile mapped to a time.clips/<id>/kf/Keyframes at 256, 768 and 1536 px.clips/<id>/transcript.*The transcript as JSON (with word times), WebVTT and SubRip, plus an English translation when the speech was in another language.README.mdA guide to the folder for any agent that finds it. Every shotlog explains itself.The read layer: fewer tokens per decision
A full catalogue of a large folder is too long to read every session. So Prewatch writes a read layer beside it: INDEX.md, scenes.md and clips.tsv are enough to plan a cut, and moments.tsv is searched for the in-points.
| Folder | catalog.md | Read layer |
|---|---|---|
| 381 clips | 110,241 tokens | 34,765 tokens (−68%) |
| 324 clips | 92,349 tokens | 29,369 tokens (−68%) |
| 99 clips | 31,251 tokens | 10,839 tokens (−65%) |
Three real trip-footage folders, counted with Claude's tokenizer, October 2026. Read layer = INDEX.md + scenes.md + clips.tsv.
A typical query reads INDEX.md and then searches moments.tsv for what it needs, for example every moment where a fish is landed, rather than reading anything whole.
How agents read a shotlog
- In Claude Desktop, through Prewatch's MCP server: overview, search, moments, clip details and exact frames, with compact, paginated answers. No file access needed.
- Any agent with file access, such as a coding agent in a terminal, can open the folder directly: read
INDEX.md, thenscenes.mdandclips.tsv, searchmoments.tsvandtranscripts.md, and open a clip's manifest and contact sheet only for the clips that matter. - Scripts can parse the TSV and JSON Lines files with standard tools.
A command-line reader for agents exists in Prewatch's engine but is not distributed yet. The files are readable without it.
Format status
The Shotlog format is versioned. Every file says which version wrote it, and every change to the format is recorded in a changelog with its reason. The format may still change as Prewatch improves; it is not published as an open standard.
Readers should ignore keys they do not know and tolerate missing optional sections.