What the assistant can ask Shotwork for

An AI assistant works your library through four requests. The wording below is what the assistant itself reads before deciding what to do, taken straight from Shotwork, so it is exactly what your assistant was told.

build_timeline

Write an editable timeline the artist can open in DaVinci Resolve, Premiere or Final Cut. shots is your complete edit decision, in playing order: [{"shot_id": "...", "seconds": 2.5}, ...]. seconds is screen time -- leave it out to play the shot in full. Give hero shots room and weaker-but-relevant ones a shorter look; a reel where every shot is the same length reads as a contact sheet. Asking for more time than a shot actually has is an error, not something that will be quietly shortened. Search results tell you each shot's real duration, so check before allocating. trim decides which part of a shot survives being shortened: "head" keeps the start, "centre" (that exact value) keeps the middle. Keeping the middle is often better when the subject enters frame late. You do NOT choose where the file is written, and you should not try -- give a name and the path comes back in the result. You also don't need to compute any frame numbers or timeline positions; that is all done here from the durations you give. The result reports the runtime, any warnings, and where each clip landed. Nothing is written if the edit has problems -- you get the full list back so you can fix it and try again. Use notes to say briefly why you ordered it the way you did -- which shot you led on and why, what you left out. The artist sees this while reviewing, so your reasoning isn't lost between the two apps. To align cuts with music, pass beat_seconds -- the timestamps from get_beat_grid you're cutting to. Any resulting cut that lands within a few frames of one of them is nudged to land exactly on it. Your own seconds should already be a close estimate -- subtract consecutive beat timestamps yourself -- this only cleans up the last fraction of a frame, it doesn't choose which beats to cut on for you. Each clip in the result says whether it actually got snapped. By default a snapped cut lands beat_offset_frames (-2.0 frames, so slightly before the beat) rather than exactly on it -- editors commonly cut a frame or two ahead so the incoming image has already settled by the time the beat actually hits, instead of trailing it. Pass 0 to land exactly on the beat instead, or a different value for more or less lead. This is a proposal. Two files come back: the timeline, and a reel the artist opens in Shotwork to reorder, retrim and re-export. Aim for a strong starting point rather than agonizing over a perfect one -- they have the final say and the tools to use it.

Parameter	Type	Default
shots	list of object	required
name	string	'Reel'
timeline_fps	number	None
max_seconds	number	None
trim	string	'head'
include_restricted	boolean	False
notes	string	''
beat_seconds	array	None
beat_offset_frames	number	-2.0

get_beat_grid

The rhythm of a music track: tempo, every beat's own timestamp, how strong it is (0.0-1.0), and whether it's a downbeat. Call this before proposing a beat-driven cut -- there's no way to guess tempo or beat timing from a file name alone. audio_path is a file already on disk, the same track you'd attach as this reel's music. energy is how strong that beat's own onset is relative to the rest of the track -- useful for cut density: a quiet stretch can hold a shot longer, a loud one wants more cuts. downbeat is only meaningful when downbeats_available is true; when it's false, every beat comes back as a non-downbeat because no downbeat model is installed on this machine, not because the track doesn't have any -- don't read that as "this track has no downbeats." You still work out each shot's own seconds for build_timeline yourself -- this tells you where the beats are, it doesn't place cuts for you.

Parameter	Type	Default
audio_path	string	required

list_library_summary

What's in the artist's shot library: how many shots, which tags they actually use, which projects and clients and roles appear, and how ratings are distributed. Call this first, before searching. The tag vocabulary is the artist's own and won't match the words a client uses -- a brief asking for "creature performance" has to be mapped onto whatever tags are really in here, and you can't do that without seeing them.

No parameters.

search_shots

Find shots to consider for a reel. field_values filters on any preset field by id, matching any of the values given: {"client": ["Acme"], "materials": ["oak"]}. The field ids and their known values are in list_library_summary's field_values. The named client/project/role parameters are the VFX-preset shortcuts for the same thing. Tags match ANY of the ones you give unless match_all_tags is set, so pass several related terms rather than guessing at one. rating is the artist's own judgement of their work, 1-5, and is the single most reliable signal you have -- weight it heavily. Results come back best-rated first. An unrated shot isn't necessarily weak; it may simply not have been graded yet. Restricted shots are work the artist is NOT cleared to show publicly. They're excluded by default and you should leave them excluded unless the artist explicitly asks for them for a private showing. Prefer searching more than once with different terms over one broad search: you're building a reel, so variety across the body of it matters as much as the strength of any single shot.

Parameter	Type	Default
tags	array	None
match_all_tags	boolean	False
min_rating	integer	None
project	string	None
client	string	None
role	string	None
max_duration_seconds	number	None
min_duration_seconds	number	None
include_restricted	boolean	False
limit	integer	40
field_values	object	None