Where it is
Each export writes <name>.events.json beside the video in ~/Movies/Kirocast/Exports: an MP4, a GIF, an Export for AI or a Talk mode take. When the project has a transcript, <name>.transcript.json sits beside it, on the same clock.
The file explains itself: its top-level fields spell out the units and what each kind of annotation means, so a model can read it on its own.
The top-level fields
{
"conventions": {
"coordinates": "normalized 0..1, origin top-left, relative to the captured screen area (before zoom/padding)",
"effects": "events on the \"effects\" track are editorial cues added by the author; …",
"time": "seconds in the exported video timeline"
},
"effectSemantics": { "focus": { … }, "mask": { … }, "tapTap": { … } },
"events": [ … ],
"format": "kirocast-events",
"generator": "Kirocast 1.0.0 (founder mode)",
"summary": {
"clicks": 9,
"effects": { "focus": 2, "mask": 1, "tapTap": 1 },
"fragments": 2,
"hasCameraOverlay": true,
"zoomSegments": 4
},
"version": 1,
"video": {
"duration": 42.6,
"file": "Export_1787674297.mp4",
"fps": 60,
"resolution": { "height": 1080, "width": 1920 }
}
}| Field | What it holds |
|---|---|
format, version | Always kirocast-events, version 1. New fields and event types can appear within a version; a reader should skip the ones it doesn’t know. |
video | The exported file’s name, length in seconds, size in pixels and frame rate, read from the file itself. |
summary | Counts at a glance: clicks, zooms, clips, each kind of effect, and whether a camera bubble is shown. |
conventions | The units for time and position, in plain words. |
effectSemantics | For each kind of effect: its intent, its attentionPriority, whether it marks a point or an area (geometry), and a sentence on what it means (meaning). See Clicks and annotations. |
events | One flat list, in time order. |
Time and position
tis seconds into the exported video, to the millisecond. Cuts and speed changes are already applied: a click inside a part you cut is left out, and a click in a sped-up clip lands where it plays.endTappears on events that last, such as a zoom or an annotation. Instant events, such as a click, have onlyt.xandyrun from 0 to 1, from the top-left corner of the area you recorded, before zoom and padding.x0.5,y0.5 is the centre of what you recorded, whatever the export’s framing.rectis an area in the same units:xandyfor its top-left corner, pluswidthandheight.
When two events share a t, the cause comes first: the click, then the zoom it triggered.
Every kind of event
{ "endT": 18.4, "sourceEnd": 18.4, "sourceStart": 0, "speed": 1, "t": 0, "track": "clip", "type": "fragment" },
{ "button": "left", "clickCount": 1, "t": 2.4, "track": "cursor", "type": "click", "x": 0.42, "y": 0.31 },
{ "endT": 3.1, "factor": 2, "t": 2.4, "track": "zoom", "transition": "smooth", "type": "zoomIn" },
{ "t": 2.4, "track": "position", "type": "focusPoint", "x": 0.42, "y": 0.31 }| Event | What it says | Fields |
|---|---|---|
clip · fragment | One clip of the edited timeline, from t to endT | sourceStart and sourceEnd (seconds in the original recording), speed |
cursor · click | A mouse click | x, y, button (left, right or other), clickCount (2 for a double-click) |
zoom · zoomIn / zoomOut | The view zooms in or back out, reaching factor at endT | factor, transition (smooth or linear) |
position · focusPoint | The point the zoom centres on | x, y |
effects · focus | A Smart Annotation around an area | rect, optional target |
effects · tapTap | A Tap Tap cue on a point | x, y, optional target |
effects · mask | A privacy blur over an area | rect, blurRadius |
overlay · cameraBubble | Where the camera bubble sits, for the whole video | rect |
Pointer movement between clicks stays out of the file, which keeps it short enough to read in one go.
These videos always show the whole recorded area. Their events file still lists the project’s zooms, as a record of what you meant to bring forward; the frames themselves stay at full view, so positions map straight onto them.
Clicks and annotations
A click is something that happened on screen. An effect is something you added to guide the viewer’s eye. The file keeps the two apart: clicks live on the cursor track, and every effect carries "interaction": false, so a reader never takes an annotation for a click.
{ "attentionPriority": "high", "endT": 11.75, "intent": "highlight_target", "interaction": false,
"rect": { "height": 0.12, "width": 0.2, "x": 0.35, "y": 0.22 },
"t": 8.75, "target": { "kind": "button", "label": "Export" }, "track": "effects", "type": "focus" }| Effect | intent | attentionPriority | Meaning |
|---|---|---|---|
focus | highlight_target | high | Look at what’s inside rect; the cue is centred on its middle. |
tapTap | read_this | high | Read this; it matters. Points at x, y. |
mask | obscure_content | low | Private content, blurred. It points at nothing. |
target names what an annotation points at: a kind (text, button, icon, image, region or unknown) and, usually, a label. It is filled in when Kirocast knows the answer: from macOS Accessibility when you circle something in Talk mode, or from the agent that placed the annotation. When it is absent, the video shows what the annotation covers.
For how an agent reads this file alongside the transcript and the video, see What your agent receives.