File formats¶

ShotWork writes two kinds of document. Both are plain JSON text you can open in any text editor, and neither contains footage: they point at your video files where they already are.

Extension	Name	What it holds
`.swselects`	shot selects	The videos you marked, every shot in them, and the fields those shots carry.
`.swreel`	reel	Which shots play, in what order, for how long, and what sits over and under them.

Shot selects¶

Key	Holds
`schema_version`	The format version. Currently 6.
`fields`	The shot selects file's own metadata fields, copied from the preset it started from.
`sources`	One record per video.
`shots`	One record per shot.
`exports`	Reserved for a later version; nothing writes it yet.

A source¶

Key	Holds
`id`	A short id that each shot's `source_id` points at.
`path`	The video's full path, as of the last save.
`relative_path`	The path from the shot selects file's own folder, or empty when the video is outside that folder or on another drive.
`file_fingerprint`	A short signature of the file that recognizes it after a move or rename. It is not an integrity check.
`fps_num`, `fps_den`	The exact frame rate as a fraction, for example 24000 and 1001.
`frame_count`, `width`, `height`	The video's length in frames and its frame size.
`start_timecode`	The timecode embedded in the file.
`has_vfr`	Whether the video has a variable frame rate.
`interest_points`	Every interest point on this video, by frame.

A shot¶

Key	Holds
`id`	The shot's own id, which reels refer to.
`source_id`	The video it was marked in.
`in_frame`, `out_frame`	The first and last frame of the shot, both included.
`name`, `tags`, `rating`, `notes`, `restricted`	What you entered in the detail panel.
`values`	Every preset field's value, by field id.
`created_at`, `updated_at`	When the shot was made and last changed, in UTC.
`ai`	Reserved for a later version; nothing writes it yet.

A shot selects file stores frames only. Seconds and timecode are worked out from the frame rate whenever ShotWork shows them.

Reel¶

A reel is an edit decision, not a render. It stores no timeline positions: ShotWork works them out from your shot selects every time it opens the reel, so a reel cannot carry arithmetic that has gone out of date. The one frame number it keeps is the frame you trimmed a clip's edge to by hand.

Key	Holds
`schema_version`	The format version. Currently 23.
`name`	The reel's name.
`timeline_fps`	The frame rate as a fraction, or empty to follow the footage.
`items`	The shots, gaps and cards, in playing order.
`trim`	Which part of a shortened shot plays, for the whole reel: its start (`head`) or its middle.
`max_seconds`	The length budget, or empty for none.
`include_restricted`	Whether restricted shots were allowed when the reel was made.
`notes`	Notes, such as an AI assistant's reasons for its order.
`music_tracks`	Each song's file, window on the reel, offset, level and fades.
`fades`	Fades on clip edges.
`default_template`, `template_overrides`	The reel's overlay template by name, and any per-shot overrides.
`overlay_fade_frames`	How long an overlay takes to fade in after a cut.
`viewport_seconds`	The length of the reel timeline's canvas.
`replace_uses_interest_point`	Whether a replacement starts at the new shot's interest point.

An item¶

Kind	Stores
Shot	`shot_id`; `seconds`, how long it holds, empty to play the whole shot; `trim` for this clip alone, which can also be `tail` or `interest`; `anchor_frame`, the frame an edge was trimmed to by hand; `scale`, once changed; and `label`, `source_name` and `held_seconds`, the shot's name, its video's name and its length when last seen, so a reel can still describe a shot that has since been deleted.
Gap	Its length in seconds.
Card	Whether it is an image, color or title card, how long it holds, the image path, color or template name, and an image card's `scale`.

Holds and shortening explains the trim anchors, and Clip picture the scale.

Files from other versions¶

An older file opens and is upgraded as it loads. Nothing is lost, and the next save writes the current format.
A file saved by a newer ShotWork refuses to open, with Could not open shot selects or Could not open reel. Update ShotWork to open it.

Beside exported clips¶

Export shots writes a metadata folder beside the clips, with one JSON file per clip: the clip's path relative to that folder, the whole shot record with the interest points inside its range, the source video's path, the frames actually exported including any handles (extra frames on either side of the marks), the preset, and when it was exported. Each clip also carries a small copy in its own comment tag.

Overlay templates¶

One JSON file per template, in the overlay_templates folder of ShotWork's app data, with a format version. Each lists its items with their zone, kind, text or field, image path, font family and size, color, scale, offsets, display and layout, justification, number format, logo gap, box width and height, and opacity.

Reels refer to a template by name, so a reel moved to another computer shows its overlay only if a template of that name exists there. One template, Basic Lower Third, ships inside ShotWork rather than in that folder, so it exists on every computer, and a file of the same name in the folder is hidden behind it.