@aicopycoders/exodus 2026.9.2000 → 2026.10.1200-beta.2

package/assets/skills/exodus-video/SKILL.md

@@ -38,6 +38,37 @@ storyboard itself when its checks pass (see "What costs money"). The full line i
 note cannot contain a colon. "The script file" shows the right form and the
 wrong one.
 
+**The kinds of ad.** `--conceit` takes one of the kinds the server offers. The
+server's list is the truth, and nothing prints it on request. Pass a key it
+doesn't offer and the refusal names every key it does: `video start --conceit
+must be one of …`. Nothing is spent on a refused start. Today the server offers
+15 formats and then Custom:
+
+| Key | Kind |
+|---|---|
+| `podcast` | Podcast |
+| `ugc` | UGC talking head |
+| `stage` | Speaking on stage |
+| `street` | Street interview |
+| `personification` | Personification |
+| `news-broadcast` | News Broadcast |
+| `court-tv` | Court TV |
+| `soap-opera` | Soap Opera |
+| `storytime` | Storytime While Doing a Task |
+| `customer-service-call` | Customer Service Call |
+| `debate-circle` | Debate Circle |
+| `talk-show-panel` | Talk Show Panel |
+| `infomercial` | Infomercial |
+| `dating-show` | Dating Show |
+| `game-show` | Game Show |
+| `custom` | Custom |
+
+Custom builds the ad from the script itself. A script with no `CAST:` runs as a
+voice-over, and a script with people runs as a scene. Voice-over and Scene are
+not on the menu by name; Custom is the way to them. A narrator-only script fits
+Custom alone. If the refusal lists different keys from this table, the server
+is right and this table is stale.
+
 The Rig box on that workflow is where the run's Conceit and Style come from.
 Conceit is the family plus Wrapper, Narrator Person, and Delivery. Style is the
 look. Narrated Story is the voice-over family and Acted Story is the dialogue
@@ -70,7 +101,7 @@ never how it is made. Every answer to them says `"view": "customer"`, and the
 CLI words it the way the run page does. On their own brands they can:
 
 - `video start --script <file> --conceit <key> --style <slug>` with
-  `--direction`, `--music`, `--review-storyboard` and `--wait`. Any other start
+  `--direction`, `--frame`, `--pacing`, `--music`, `--review-storyboard` and `--wait`. Any other start
   flag is refused with one sentence naming it. The answer is the run id and the
   link to the video's page.
 - `video status <runId>`: where the video is, in plain words (waiting in line,
@@ -125,9 +156,12 @@ exodus workflow run <workflowId|name> --input <field>=@script.txt --voices @voic
 exodus workflow run <workflowId|name> --input <field>=@script.txt --voice-treatment @voice-treatment.json --wait
                                                           same, with the video model speaking voices you WROTE
 exodus video status <runId>                               where it is, per scene
-exodus video start --script <file> --conceit <podcast|ugc|stage|street|personification> --style <slug> [--direction "…"] [--voice-path <path>] [--video-model <id>] [--voice native] [--music] [--review-storyboard] [--director] [--wait]
-                                                          start from a script, a conceit and a look.
+exodus video start --script <file> --conceit <kind> --style <look> [--direction "…"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice native] [--music] [--review-storyboard] [--director] [--wait]
+                                                          start from a script and the kinds the server offers.
                                                           No music bed unless you pass --music.
+                                                          --frame pov (conversation conceits) and --pacing
+                                                          (presenter conceits) change the shots; a conceit
+                                                          that can't follow one refuses it.
                                                           The app approves its own storyboard when its
                                                           checks pass and goes straight on to the clips,
                                                           which is the part that costs. It stops at the
@@ -365,6 +399,78 @@ Do not use a long dash in words a character says, or in words shown on screen.
 Synthesised speech reads a long dash oddly, and so does burned-in text. A spoken
 line stays `NAME: what they say`.
 
+### Directing a line
+
+A spoken line can carry two kinds of note. Neither is required.
+
+- **How the line is said goes in parentheses.** The voice acts it out.
+- **What happens on camera goes in square brackets.** The storyboard plans the
+  shot around it.
+
+```
+MIA: (whispering, excited) I can't believe this actually worked.
+MIA: [holds the jar up to the camera] This is the one.
+MIA: [leans in] (quietly) Don't tell my sister.
+```
+
+A note may sit anywhere on the line. It comes out of the spoken words, so the
+voice never says it. Several notes of one kind on a line are joined. Notes work
+on `CTA:` lines and on narrator lines too. They do not work on `CAST:` lines,
+where anything in brackets is just part of the description.
+
+How the voice uses a delivery note. By default a run records each line first,
+on the Eleven v4 voices, which take the note as a short cue in front of the
+line. The cue is the note's first clause, at most six words. A full stop,
+colon, semicolon, question mark, exclamation mark, or a dash with a space on
+each side ends the clause. A comma does not, so `whispering, excited` reaches
+the voice whole. Keep the note short and put the part that matters first. Put
+one delivery note on a line: two are joined with a semicolon, so the voice
+hears only the first.
+
+Right.
+
+```
+MIA: (whispering, excited) I can't believe this actually worked.
+```
+
+Wrong.
+
+```
+MIA: (She is whispering. She can barely contain how excited she is) I can't believe this actually worked.
+```
+
+The wrong note reaches the voice as `[she is whispering]`. The excitement is
+lost.
+
+In a narrated scene the whole narration is read as one part, so it takes one
+cue: the note on the first narrator line in that scene.
+
+What the reader refuses, with the code `malformed-direction`:
+
+- an empty note, `()` or `[]`
+- a square bracket that is never closed, or a stray `]`
+- a line with no spoken words left once the notes come out
+
+An unclosed `(` is not refused. It is read as ordinary words, and the voice
+says it. Check every `(` has its `)`.
+
+Both ways in read the file the same way: `exodus video start --script` and
+`exodus workflow run --input <field>=@script.txt`. The second holds only when
+the script goes straight from a Brief into the Storyboard. In a workflow where a
+bot writes or rewrites the script first, the notes are not read this way, and
+the bot may drop them or leave them in the spoken words.
+
+With `--voice native` (admins only) the video model speaks the lines itself and
+nothing is recorded first, so the six-word cue above does not apply.
+
+**A line with no note still gets a natural read.** A note is the surest way to
+get a particular delivery. The storyboard planner may add a note of its own to
+a line you left plain. A note you wrote always wins over the planner's.
+
+When you help the user write or tidy a script, suggest a delivery note where
+the tone carries the ad: the hook, the turn, the CTA. Do not put a note on every
+line. A note on every line reads as a script nobody trusted.
+
 **How many speakers you may have depends on the rig.** Three by default. A rig
 that carries saved format rules sets its own number: an ensemble rig seats more,
 a talking-head rig seats one. Over the number, the launch refuses before
@@ -979,6 +1085,10 @@ Read these out of `storyboard.json` before you build anything, in any tool:
   between the two halves.
 - **Overlays and SFX.** `overlays[]` and `audio.sfxCues[]` are cued the same
   way, by `cueLineId`. Nothing renders them for you.
+- **Jump cuts.** When `manifest.json` has `shots.pacing: "jump-cuts"`, every
+  scene was filmed from the same framing on purpose. Punch in about 15% on
+  every other cut between one speaker's scenes, so each cut visibly moves in
+  or out. The bundled script does this for you.
 - **Captions.** Nothing is burned into any clip. Captions belong in post; the
   word timings are what an editor imports to build them.
 
@@ -988,19 +1098,28 @@ State this to the user before you run it, so they know what the cut does with
 the pieces:
 
 - **It cuts the picture to the voice, and never the other way round.** A
-  narrated scene's segment runs exactly as long as that scene's voice track plus
-  a beat of air. A clip that runs longer is trimmed; a clip that runs shorter
-  holds its last frame for the difference. The narration is never sped up,
-  slowed down or cut short, so every scene plays at the speed it was recorded,
-  and the word times are handed on as they were measured.
+  narrated scene's segment runs to the narrator's last word plus a beat of air:
+  about 0.25 s before the next scene, 0.5 s when it ends the ad. The last word
+  comes from the voice track's own word timings; when the scene has none, the
+  end of the voice file stands in for it. A clip that runs longer is trimmed; a
+  clip that runs shorter holds its last frame for the difference. The narration
+  is never sped up or slowed down, so every scene plays at the speed it was
+  recorded, and the word times are handed on as they were measured. The voice
+  file is cut only in the silence after its last word, never inside a word.
 - **It closes the dead air at the joins.** A clip that plays its own dialogue
   keeps about 0.15 s after its last word and about 0.1 s before its first (0.25 s
   when a different speaker answers), read from its `words.json`, so one clip
   runs into the next like one conversation. It only ever shortens a clip's
   silence and never cuts into a word. The ad's first clip also opens about 0.1 s
   before its first word, so a hum a clip makes before anyone speaks is not the
-  first thing heard. The ad's last tail, a narrated scene, a still and a
-  reaction beat keep their length.
+  first thing heard. The clip that ends the ad keeps about 0.5 s after its last
+  word, the same beat a narrator line gets there, or longer when the storyboard
+  marks an action after the line. A narrated scene, a still and a reaction beat
+  keep their length.
+- **It shortens long pauses between sentences inside one clip.** A silence over
+  0.6 s between two sentences is cut down to about 0.5 s, picture and sound
+  together, unless the script writes the pause in (an ellipsis or a dash), a
+  direction asks for one, or a reaction's laugh follows the line.
 - **It fades the audience reaction in and out.** A reaction beat fades in
   across any quiet start before its laugh (a generated laugh clip can hum
   there). When a line follows, the picture moves on early and the laugh's own
@@ -1017,11 +1136,17 @@ the pieces:
   proportional estimate when the scene has no word times, and saying which
   method it used), a narrated scene's voice
   replacing whatever the clip recorded, a dialogue scene keeping its performed
-  line, a clip-less scene becoming a still, everything normalized to 1080×1920
+  line, everything normalized to 1080×1920
   at 24 fps and −16 LUFS per segment, a generated room-tone bed under the whole
   ad, and the music bed underneath at low level. Output is H.264 + AAC in an MP4
   with `-movflags +faststart`.
-- Flags: `--out <file>`, `--skip 2,5`, `--no-music`. It prints what went in,
+- **It stops when a scene has no clip.** A scene the storyboard plans that is
+  still being made, never started, or failed stops the cut, which names each
+  one. Wait for the clip and pull again, leave the scene out with `--skip`, or
+  pass `--still-fill` to hold that scene's keyframe on screen instead: under its
+  voice track if it has one, else silent for its planned length. The still is
+  only ever made when asked for, because a run of them reads as a broken ad.
+- Flags: `--out <file>`, `--skip 2,5`, `--no-music`, `--still-fill`. It prints what went in,
   what was left out and why, and the upload command. When a clip hums or
   clicks where nobody speaks at an edge the cut plays, it lists each one under
   "Sound at the edges" with its time in the cut. That is a warning to listen
@@ -1032,8 +1157,12 @@ the pieces:
   timeline, each scene's own word times offset by where that scene starts in the
   cut, less any lead-in trimmed at the join, and otherwise unaltered. Scenes with no word times leave
   gaps and are named in the report; when no scene delivered any, neither file is
-  written. These sidecars are the script's own output — another tool will not
-  produce them.
+  written. It always writes `cut.scenes.json` too: where each scene plays in the
+  cut, one `{scene, startSec, seconds}` entry per placement. `exodus video
+  upload` sends `cut.scenes.json` and `cut.words.json` with the cut when they
+  sit beside it, so the customer's edit list shows each scene's time on screen
+  and their editor folder gets the captions. These sidecars are the script's own
+  output — another tool will not produce them.
 
 Before uploading anything, from any tool, check what you made:
 `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 cut.mp4`

package/assets/skills/exodus-video/scripts/first-cut.d.mts

@@ -1,4 +1,4 @@
-// #2988: the types of the one export the Trigger worker calls. The script is
+// #2988: the types of the exports the Trigger worker calls. The script is
 // plain JS so the CLI can run it with `node` and no build.
 
 export class FirstCutError extends Error {
@@ -14,6 +14,8 @@ export interface FirstCutOptions {
   skip?: Set<number>;
   /** The music bed, when the pull has one. Defaults to on, as the CLI does. */
   music?: boolean;
+  /** #3365: hold a scene's keyframe where it has no clip, instead of refusing. Defaults to off. */
+  stillFill?: boolean;
 }
 
 export interface FirstCut {
@@ -25,3 +27,18 @@ export interface FirstCut {
 }
 
 export function firstCut(options: FirstCutOptions): FirstCut;
+
+/** #3365: the scenes the cut cannot be made without, by number. */
+export function scenesWithNoClip(options: {
+  manifest: { scenes?: Array<{ sceneIndex: number; clip: string | null }> } | null;
+  storyboard: unknown;
+  skip: Set<number>;
+  exists?: (file: string | null) => boolean;
+}): number[];
+
+/** #3424: the sentence-gap cut, which scout's scribe.ts sentenceGapCuts mirrors. */
+export function sentenceGapCuts(
+  words: Array<{ w: string; s: number; e: number }>,
+  lines: Array<{ text: string; asksPause: boolean; cuesBeat: boolean }>,
+  levels?: { windowSec: number; db: number[] } | null,
+): Array<{ s: number; e: number; after: string; gap: number; kept: number; sound: boolean }>;