PromoShot
Recipe · footage first

Look at the clip before you compose.

In: a screen recording. Out: a push-in with a caption you can share. The agent that lands a cut on a pause has to see the footage first — probe, filmstrip, silences, scenes — then author.

Looping Ken Burns push-in over a screen recording with a lower caption

FocusPush.promo — 640×360 @ 6 fps. Viewport ramps 1s [0,0,1,1] → 6s [0.02,0.02,0.5,0.5]. Caption “Everything lives in one panel”.

The loop

  1. promo_media_probe — container, duration, streams.
  2. promo_media_filmstrip — a contact sheet of the source clip, sampled times per cell. Look at it before deciding what the clip shows.
  3. promo_media_silences — pause spans and their inverse. Cuts and captions want those boundaries.
  4. promo_media_scenes — hard cuts when the clip has no silence gaps. Default threshold 0.4.
  5. Then compose (viewport recipe) → still to look → GIF or video to share.

A talk track with real pauses

examples/media/talktrack.mp4 in GarAlex/promoshot is the practice clip. Duration ~15 s. Two pauses, three sound spans, scene cuts at exactly 5.0 s and 10.0 s.

promo_media_silences (defaults −35 dB / 0.35 s):

{
  "duration": 14.96,
  "thresholdDb": -35.0,
  "minSeconds": 0.35,
  "silences": [
    { "start": 3.21, "end": 5.05 },
    { "start": 9.03, "end": 11.02 }
  ],
  "sound": [
    { "start": 0.0,  "end": 3.21 },
    { "start": 5.05, "end": 9.03 },
    { "start": 11.02, "end": 14.96 }
  ]
}

promo_media_scenes (threshold 0.4) — three shots:

{
  "duration": 14.96,
  "threshold": 0.4,
  "cuts": [5.0, 10.0],
  "shots": [
    { "start": 0.0,  "end": 5.0 },
    { "start": 5.0,  "end": 10.0 },
    { "start": 10.0, "end": 14.96 }
  ]
}

When there are no silence gaps

FocusPush's recording.mp4 has no silence gaps. Sound is continuous 0–8 s at the default threshold. Cuts and captions cannot land on a pause in this clip — the caption sits at t=1 s because it was authored there, not because silence said so. Use promo_media_scenes (or just author) when silences come back empty.
Six-cell filmstrip of the FocusPush screen recording
Filmstrip, count=6 — sampled near 0.0, 1.3, 2.7, 4.0, 5.3, 6.7 s. 1280×360.
Still at 4 seconds: mid Ken Burns push with lower caption
Still at 4.0 s — mid push-in, caption visible. 1920×1080. Inspect: Focus Push, 8.00 s, 3 of 3 layers renderable.

Probe on that recording:

{
  "container": "mov,mp4,m4a,3gp,3g2,mj2",
  "duration": 8.0,
  "streams": [
    { "codec": "h264", "fps": 30.0, "height": 1080, "type": "video", "width": 1920 },
    { "channels": 1, "codec": "aac", "sampleRate": 44100, "type": "audio" }
  ]
}

Silences — empty on purpose:

{
  "duration": 8.0,
  "thresholdDb": -35.0,
  "minSeconds": 0.35,
  "silences": [],
  "sound": [{ "start": 0.0, "end": 8.0 }]
}
# MCP tools, or the CLI twins for validate / inspect / still / gif
promo_media_probe      file=/ABS/PATH/Promo/FocusPush.promo/Resources/recording.mp4
promo_media_filmstrip  file=.../recording.mp4  count=6
promo_media_silences   file=.../recording.mp4
promo_media_scenes     file=.../recording.mp4
promo_inspect          project=/ABS/PATH/Promo/FocusPush.promo
promo_render_still     project=...  time=4.0
promo_render_gif       project=...  fps=6  size=640x360

Product card → · Headless MCP → · Linux & CI →