@aicopycoders/exodus 2026.11.1200-beta.11 → 2026.11.1200-beta.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,14 +8,17 @@ description: Make a video ad with Exodus from the terminal. One sentence ("swipe
8
8
  Exodus makes the PIECES of a video ad, not the finished ad. From a script, a run
9
9
  writes a storyboard, draws one picture per scene, records the voice, renders one
10
10
  video clip per scene, and generates a music bed. Then it parks and waits for a
11
- cut.
11
+ cut (the app makes it for some runs, below).
12
12
 
13
- There is no server-side stitch and no server-side mix. Nothing joins the clips,
14
- nothing sets levels, nothing burns in captions
13
+ On a run you cut (an admin's run started with `exodus video start` or
14
+ `workflow run`), there is no server-side stitch and no server-side mix.
15
+ Nothing joins the clips, nothing sets levels, nothing burns in captions
15
16
  (`scout/src/workflow/video/music-bed.ts` states the ruling: "the cut, and the
16
17
  mix, happen outside from the pieces the CLI pulls"). You pull the pieces, cut
17
18
  them wherever you like, and upload the result. Approving the upload is what
18
- makes it the ad.
19
+ makes it the ad. The app cuts the others itself: a swiped video, a video from
20
+ the dashboard's Video page and a beta tester's run ("End: watch and
21
+ approve").
19
22
 
20
23
  Your job in this skill is to drive that loop, hand over the pieces with the
21
24
  facts about them, and make whatever cut the user asked for. **How to edit is the
@@ -42,7 +45,7 @@ wrong one.
42
45
  server's list is the truth, and nothing prints it on request. Pass a key it
43
46
  doesn't offer and the refusal names every key it does: `video start --conceit
44
47
  must be one of …`. Nothing is spent on a refused start. Today the server offers
45
- 15 formats and then Custom:
48
+ these formats and then Custom (One-take UGC to admins only, for now):
46
49
 
47
50
  | Key | Kind |
48
51
  |---|---|
@@ -61,8 +64,27 @@ must be one of …`. Nothing is spent on a refused start. Today the server offer
61
64
  | `infomercial` | Infomercial |
62
65
  | `dating-show` | Dating Show |
63
66
  | `game-show` | Game Show |
67
+ | `doorbell-cam` | Doorbell Cam |
68
+ | `reality-confessional` | Reality Confessional |
69
+ | `movie-trailer` | Movie Trailer |
70
+ | `sitcom-skit` | Sitcom Skit |
71
+ | `press-conference` | Press Conference |
72
+ | `stand-up-special` | Stand-up Special |
73
+ | `whisper-asmr` | Whisper ASMR |
74
+ | `unboxing` | Unboxing |
75
+ | `doctor-consult` | Doctor's Office Consult |
76
+ | `documentary-sit-down` | Documentary Sit-down |
77
+ | `microdrama` | Microdrama |
78
+ | `pixar-song` | Suno Pixar Song |
79
+ | `skeleton-timeline` | Skeleton / Claymation |
80
+ | `authority-yapper` | Authority Yapper |
81
+ | `ugc-ultra-realistic` | UGC Ultra-Realistic |
82
+ | `ugc-one-take` | One-take UGC |
64
83
  | `custom` | Custom |
65
84
 
85
+ A swipe's template prints its kind by one of these keys
86
+ (`ugc-ultra-realistic`, say).
87
+
66
88
  Custom builds the ad from the script itself. A script with no `CAST:` runs as a
67
89
  voice-over, and a script with people runs as a scene. Voice-over and Scene are
68
90
  not on the menu by name; Custom is the way to them. A narrator-only script fits
@@ -83,7 +105,11 @@ The member types one sentence, such as "swipe this ad as a microdrama for my
83
105
  brand". You drive the run through its stops and wait for the member at each
84
106
  one. When the sentence names a video ad to swipe as it is made (a video file,
85
107
  a link to the ad, or an ad in Exodus) and the member asks for no format of
86
- their own, go to "Swiping a video ad" below instead. The Golden Six formats start on the template door, which needs
108
+ their own, go to "Swiping a video ad" below instead. Words that say how their
109
+ ad is made are not a format of their own: "as a UGC video, one person talking
110
+ to the camera, like theirs" goes to the swipe, whose template reads the kind
111
+ from the ad. A format of their own is one their ad is not made as, or a
112
+ template the member names as one ("the UGC template"). The Golden Six formats start on the template door, which needs
87
113
  Templates switched on for the member's account. Without it the CLI answers
88
114
  "video isn't enabled for this key" or "Templates aren't available on your
89
115
  account. Ask an admin if you need it." Tell the member that and stop. A beta
@@ -129,8 +155,8 @@ does offer, and nothing is spent.
129
155
  Exodus or behind a link (the `swipe` skill's section 1 gets them). Save
130
156
  the words to `source.txt`. A video ad the member wants swiped whole, its
131
157
  kind and look and shots as well as its words, goes to "Swiping a video
132
- ad" below. That path picks the kind itself, so a member set on one of the
133
- Golden Six stays here.
158
+ ad" below. That path picks the kind itself, so a member set on a format
159
+ of their own (as above), one of the Golden Six among them, stays here.
134
160
  - the format: the table above.
135
161
  - the brand: `exodus brand current`.
136
162
  2. `exodus video start --input-options --conceit <key>` prints the template's
@@ -331,10 +357,41 @@ the audition scenes and prints what to run next:
331
357
  ### End: watch and approve
332
358
 
333
359
  At the final watch, follow the block `status` prints ("Where a run can
334
- stop"). When the cut is already uploaded, give the member the run page to
335
- watch it. When the run waits for a cut: `exodus video pull <runId> --out ./ad-<runId>`, make the
336
- cut ("Cutting the ad"), `exodus video upload <runId> --file <cut.mp4>`, and
337
- give the member the run page. Ask: approve, redo a clip, or stop here.
360
+ stop"). Who makes the cut, and whether the member approves it, depends on how
361
+ the run started:
362
+
363
+ - **The app makes the cut** of a swiped video, a video from the dashboard's
364
+ Video page and a beta tester's run, once every clip is made and no scene is
365
+ held. On a run started with `--one-shot` that cut is delivered by itself,
366
+ with no approve: on an admin key `status` then says "Final cut: approved
367
+ and delivered.", and on a beta tester's key "Your video is ready: <link>".
368
+ Only when the app's check of the finished film against its own sound fails
369
+ (One-take UGC checks it) does a One-shot cut wait instead, as a Guided one
370
+ does, with the check's sentences under it in `status`. The member's last say is before that: the One-shot yes, and the yes to keep
371
+ the last held take, since that keep starts the cut. Say so at each. Give
372
+ the member the run page to watch the film. A run that stopped at the
373
+ storyboard waits for the member instead: on an admin key `status` says
374
+ "Final cut: uploaded. Approve it with: exodus video approve <runId>"; on a
375
+ beta tester's key it says "Your video is ready to watch: <link>" and gives
376
+ the line that finishes it, `exodus video approve <runId>` (the video's page
377
+ finishes it too).
378
+ - **You make the cut** of any other run (an admin's `video start` or
379
+ `workflow run`). When the cut is already uploaded, give the member the run
380
+ page to watch it. When the run waits for a cut: `exodus video pull <runId>
381
+ --out ./ad-<runId>`, make the cut ("Cutting the ad"), `exodus video upload
382
+ <runId> --file <cut.mp4>`, and give the member the run page. On a run
383
+ started with `--one-shot` the upload is delivered by itself, as above.
384
+
385
+ When the cut waits for the member, ask: approve, redo a clip, or stop here.
386
+ On a One-take run no take is made again on its own (every redo door refuses
387
+ it): ask approve, a new run that films every take again at its full price
388
+ (for a swiped video, `exodus video swipe start <swipeId> --again`, its price
389
+ first), or stop here.
390
+
391
+ On an admin key, `pull` writes the pieces only, never the finished video,
392
+ even once the app has made and delivered it: give the member the run page to
393
+ watch it. On a beta tester's key, `pull` also writes `video.<ext>` once the
394
+ finished video is ready.
338
395
 
339
396
  - Approve: `exodus video approve <runId>` makes the cut the ad. It is one-way.
340
397
  - Redo a clip: `retry-clip` as at stop 4, after their yes. Then pull, cut
@@ -617,12 +674,19 @@ The rows:
617
674
  admins only for now: for anyone else the CLI refuses it, so don't offer it
618
675
  to them. Use it when the member asks for a one-take UGC video or names
619
676
  Luke's UGC method, and then the sheet's first line says the swipe makes
620
- one-take UGC. When the template prints "Also fits their ad: One-take UGC
621
- (ugc-one-take). …", name it in the sheet's first line as one option beside
622
- the kind the swipe makes, with the reason that line gives. The line comes
623
- only for an ad its write takes and a member who may start it. Add `--kind
624
- ugc-one-take` to the write only on the member's yes; never choose it
625
- unasked. A reply that picks it is not the yes yet: run its write line with
677
+ one-take UGC. Use it too when the template prints "Also fits their ad:
678
+ One-take UGC (ugc-one-take). …" and the member asked for a UGC video of one
679
+ person talking to the camera, in any words: the word "one-take" is not
680
+ needed. Then take it: in the sheet's first line, in place of "The swipe
681
+ makes that kind of ad.", say in one line that the swipe makes One-take UGC,
682
+ with the reason the template's line gives; One-take UGC is then the kind
683
+ made. The write carries `--kind ugc-one-take`, its dry run first (People,
684
+ below), and the sheet's yes is the yes to it. The line comes only for an ad
685
+ its write takes and a member who may start it. When the line comes and the
686
+ member asked for nothing it fits, name it in the sheet's first line as one
687
+ option beside the kind the swipe makes, with the reason that line gives.
688
+ Then add `--kind ugc-one-take` to the write only on the member's yes; never
689
+ choose it unasked. A reply that picks it is not the yes yet: run its write line with
626
690
  `--kind ugc-one-take` and no `--yes` (free; People, below) for the people's
627
691
  price, send the sheet again with **It buys:** in the saved sheet's form, and
628
692
  wait for the yes. A sheet run (`exodus video swipe run --sheet <file>`) of
@@ -635,7 +699,15 @@ The rows:
635
699
  key; it needs their ElevenLabs key and their Kie key. Its price is the
636
700
  server's estimate, known once the swipe is written: `exodus video swipe
637
701
  sheet price <swipeId>` (free) prints it at 720p or a 480p draft, the whole
638
- video or the first take only, each with the most it can cost.
702
+ video or the first take only, each with the most it can cost. The "about"
703
+ films each take once. A take filmed again (as when a filming left out
704
+ script words that matter) is paid again, so the run can cost more than
705
+ "about"; the "at most" counts each take and picture made twice. On an admin
706
+ key, plain `exodus video status` prints a line that starts "Cost so far:"
707
+ or "Cost:" once the run has spent anything: that is the run's own cost, the
708
+ figure the dashboard shows, and the line says what is not in it (what the
709
+ swipe paid for before the run). When it prints none, no cost is recorded
710
+ yet: say so, and never call the run free.
639
711
  - **The saved sheet** (a kind that has one; One-take UGC today). The server
640
712
  keeps one for each swipe of such a kind, made after its write. For such a
641
713
  video this sheet's yes covers the write and its people only, and **It
@@ -651,7 +723,10 @@ The rows:
651
723
  ("About $… for new people: …" and "At most $… in all: …") and the line to
652
724
  run: "On their yes, run the same command with --yes --people-max-usd
653
725
  <most>". Put that most on the sheet, as above: the sheet's yes is the yes to
654
- it. When it prints no people's price, the write makes none. When the member
726
+ it. When the member gave a money limit and the people's most, added over
727
+ every video on the sheet, is already over it, say so on the sheet and ask:
728
+ no write goes out until what it can cost fits. When it prints no people's
729
+ price, the write makes none. When the member
655
730
  wants no people, the write takes `--no-people`, and the sheet says so. Two
656
731
  more writes make none, and nothing is paid for them. A member's own
657
732
  script (`their-format`) that keeps its own person (the "Persona and
@@ -698,7 +773,9 @@ The rows:
698
773
  has its person picked on the saved sheet, in step 4.
699
774
  - **Run.** With "stop at the storyboard", the line reads **It buys:** <n>
700
775
  scripts, and <n> storyboards with their pictures; the voices and clips
701
- wait for your yes at each storyboard.
776
+ wait for your yes at each storyboard. With "one shot", the film is
777
+ delivered by itself once the app's cut is made, with no final approve: say
778
+ so in **My picks** when one shot is picked.
702
779
  - **Finish.** `swipe start` takes `--music` and nothing else for the finish.
703
780
  Music is made on the member's own ElevenLabs key. Caption style, speed,
704
781
  jump cuts and the end card come with a later update.
@@ -710,7 +787,14 @@ The rows:
710
787
  sheet says exactly that: no number, no range, no guess. A kind with a saved
711
788
  sheet (One-take UGC today) gets its price after the write, with its saved
712
789
  sheet (step 4). The people its write makes are priced before it (People,
713
- above). The Director block of `exodus video
790
+ above). A kind with no saved sheet prints no price before its write or its
791
+ start, so the member sees no figure before the yes: say so on the sheet.
792
+ When the member gave a money limit ("under $27"), say too that this kind
793
+ prints no price, so the limit cannot be checked against one before the yes.
794
+ Only when the template offered One-take UGC for this ad ("Also fits their
795
+ ad: …"), say that it prints a price before its start, and that its start is
796
+ refused when it can cost more than the "at most" shown. Ask how they want to
797
+ go on, and wait. The Director block of `exodus video
714
798
  status` prints "Spent: $… of $12.00": the $12.00 is the Director's limit
715
799
  for its redos on that video, not a price and not a ceiling for the first
716
800
  pass. Never quote it as the cost.
@@ -762,9 +846,12 @@ for the next video.
762
846
  worked out for this swipe. Today that can be the person (`who`), the voice
763
847
  (`voice`), what the person holds (`prop`), the kind of opening (`hookKind`)
764
848
  and the text card at the start (`headline`). Show each with its reason. "Let
765
- it run" here is the yes to the starts with the sheets as they stand: set
766
- nothing, since a start with no pick films every recommended value and every
767
- other row's default. When people were made but the person row recommends none,
849
+ it run" here, said in reply to these saved sheets and their prices, is the yes
850
+ to the starts with the sheets as they stand: set nothing (a size a money
851
+ limit needs is set before the sheets are shown, below), since a start with no pick films every recommended value
852
+ and every other row's default. A "let it run" said before them, as in the
853
+ first message, is not this yes: the writes went on the yes to step 3's sheet,
854
+ and the starts wait for a reply to these. When people were made but the person row recommends none,
768
855
  a start with no pick films a new person, not one of them: the write and the
769
856
  start say so, and the member picks with `who=<n>` if they want one of them. A
770
857
  member's pick wins (the row then reads `from you:`). `<row>=` clears a pick,
@@ -795,6 +882,27 @@ price again after a set. The first take only is a cheap check of the method
795
882
  and the size, not of the final person: the whole video after it is a second
796
883
  start, paid on its own (`takes=all`, then `swipe start <swipeId> --again`),
797
884
  and it casts the person and draws the pictures again. Say so before that yes.
885
+ **A money limit.** When the member gave one ("keep the whole thing under
886
+ $15"), hold it before the start: add the people's most when the dry write
887
+ printed one (its "At most $… in all"), what the write cost when the limit is
888
+ for everything, and the start's "at most" (never its "about": a take filmed
889
+ again is paid again), and compare the sum with the limit. The text calls the
890
+ price leaves out are in no figure: say so, and leave room for them. Over it,
891
+ nothing starts. When a smaller size the price lists fits (its whole video,
892
+ every take, and the start does not refuse it), set it before you show the
893
+ saved sheets (`exodus video swipe sheet set <swipeId> size=480p`, free), read
894
+ the price again, and say on the sheet in one line that it is a 480p draft,
895
+ the size that fits their limit: their yes to that sheet is the yes to it. A
896
+ limit given after they saw the sheets: name the 480p draft and wait for their
897
+ yes. With a money limit and no "at most" printed, the limit cannot be
898
+ checked: stop and ask. For example, with a limit for everything:
899
+ when the write's cost, the people's most and 720p's "at most" add up to more
900
+ than the limit, and the same sum with 480p's "at most" is under it, set
901
+ 480p. Every figure in that sum is the one the CLI printed for this swipe,
902
+ never one from memory. When no size fits, stop and ask; when the price lists the first take
903
+ only (`takes=first`), you may name it as a smaller thing they can choose,
904
+ never as the whole video. The `--max-usd` you start with is the "at most" the
905
+ price shows, so it is never above what is left of the member's limit.
798
906
 
799
907
  A write that carried the people's most makes the first people to pick from
800
908
  (People, step 3). Offer more people, or voices to pick from, only when the
@@ -815,8 +923,11 @@ video swipe sheet voices <swipeId>` lists them again: one read of the voice
815
923
  list on the member's ElevenLabs key, and no speech is made, so it buys
816
924
  nothing. It prints the voices that fit the person, best fit first, each with
817
925
  its age and accent when known ("Sarah · young · American") and a sample to
818
- hear, then "Recommended: <n> (…)" and why, or why none is. A voice row with no
819
- voice prints "List the voices: exodus video swipe sheet voices <swipeId>". A
926
+ hear, then "Recommended: <n> (…). <why> A start with no pick films it."; after
927
+ the member's pick, "Recommended: <n> (…). You picked it, so a start films it."
928
+ or "… You picked <m>, so a start films your pick."; or why none is. A voice
929
+ row with no voice prints "List the voices: exodus video swipe sheet voices
930
+ <swipeId>". A
820
931
  pick is a set (`who=<n>`, `voice=<n>`), and the video is filmed with that
821
932
  person, their face and that voice. If the server says these choices are not
822
933
  switched on yet, say so and go on with the sheet as it is.
@@ -878,7 +989,9 @@ every video has started:
878
989
  `--one-shot` when the member chose to stop at the storyboard, and with
879
990
  `--music` when they chose music. For a kind with a saved sheet whose price
880
991
  printed a number, add `--max-usd <n>` with the "at most" it showed: a
881
- start that can now cost more is refused, and nothing is started. No
992
+ start that can now cost more is refused, and nothing is started. With a
993
+ money limit, start only once that "at most" fits what is left of it ("A
994
+ money limit", above). No
882
995
  number printed: no `--max-usd`, and never a guessed one. When the sheet
883
996
  has people, the start says first whom it films ("A start with no pick
884
997
  films person N, the recommended one.", or the member's pick). While they
@@ -887,9 +1000,13 @@ every video has started:
887
1000
  were asked for, then starts and says whom it films. Give the member the
888
1001
  `Watch it:` link at once. Then go on to the next video.
889
1002
  3. When every video has started, follow each run with `exodus video status
890
- <runId>` and do what it prints. A one-shot run that waits for a cut goes
891
- to "End: watch and approve" (pull, cut, upload, the run page). A run that
892
- stopped at the storyboard goes to stop 3, then the end.
1003
+ <runId>` and do what it prints. The app makes a swiped video's cut ("End:
1004
+ watch and approve"), so make no cut of your own. A one-shot run is
1005
+ delivered by itself once that cut is made: give the member its run page.
1006
+ While the app makes it, `status` may still say "Parked: every piece is
1007
+ made and the run is waiting for a cut." for a short while: read `status`
1008
+ again before anything else. A run that stopped at the storyboard goes to
1009
+ stop 3, then the end.
893
1010
 
894
1011
  **Never start the same swipe twice.** One swipe is one video. A start of a
895
1012
  swipe that already has a video is refused, starts nothing, and names the run:
@@ -905,10 +1022,15 @@ row marked refused is that write's refusal: report it as a refused write. When
905
1022
  no such row is there yet, the write may still finish: check again later.
906
1023
 
907
1024
  At the end, report each video on one line: its ad and persona, its run id
908
- and its `Watch it:` link, or why it stopped.
1025
+ and its `Watch it:` link, or why it stopped. For a One-take video, add what it
1026
+ cost (the "Cost:" line of `status`), beside the "about" shown before the
1027
+ yes.
909
1028
 
910
- **The final approve** is asked for each video as at "End: watch and
911
- approve". It is one way. A redo of a clip there needs its own yes.
1029
+ **The end of each video** is as "End: watch and approve" says. A one-shot
1030
+ video is delivered by itself once the app's cut is made, with no final
1031
+ approve, unless the film's check against its own sound fails ("End: watch and
1032
+ approve"). A video that stopped at the storyboard asks the final approve, which
1033
+ is one way. A redo of a clip there needs its own yes.
912
1034
 
913
1035
  **A refusal or a failed check stops that video only.** The others go on, and
914
1036
  every video is in the report at the end. A refused write prints "The writer
@@ -1280,7 +1402,9 @@ CLI words it the way the run page does. On their own brands they can:
1280
1402
  until the storyboard is approved.
1281
1403
  - `video retry-frame <runId> --scene <n>`: redraws one scene's picture while
1282
1404
  the storyboard waits. No `--node`; the server finds the step.
1283
- - `video pull <runId> --out <dir>`: the finished video (`video.<ext>`), each
1405
+ - `video pull <runId> --out <dir>`: the finished video (`video.<ext>`) once
1406
+ it is ready (until then it says "The finished video isn't ready yet, so
1407
+ only the scene pieces came down."), each
1284
1408
  scene's clip (`scene-NN.<ext>`) and voice (`scene-NN.voice.<ext>`), and the
1285
1409
  music (`music.<ext>`), with a `manifest.json` holding only `runId`,
1286
1410
  `pulledAt`, `dashboardUrl`, `scenes` (`index`, `clip`, `voice`), `music` and
@@ -1522,8 +1646,9 @@ under it:
1522
1646
  it instead (`stop.missingScenes` in `--json`) and approval is refused until
1523
1647
  it has one. A scene whose picture the video service refused needs
1524
1648
  `retry-frame --note` before `retry-clip`; the clip redo alone resends the
1525
- refused picture. On a video started from the dashboard, the app makes the
1526
- cut itself; when a scene's clip still has a drawing fault after it was made
1649
+ refused picture. On a video the app cuts itself (one started from the
1650
+ dashboard, a swiped video, a beta tester's run: "End: watch and approve"),
1651
+ the app makes the cut; when a scene's clip still has a drawing fault after it was made
1527
1652
  again, the stop block says `Held:` and names the scene
1528
1653
  (`stop.heldScenes` in `--json`). No cut is made until each held scene is
1529
1654
  made again with `retry-clip`, or kept as it is with `exodus video keep
@@ -1535,7 +1660,8 @@ under it:
1535
1660
  cannot be made again on its own, so no `retry-clip` is offered. Show the user the sentence
1536
1661
  and ask them to watch the take. With their yes, `exodus video keep <runId>
1537
1662
  --scene <n>` keeps it as it is: it orders nothing, and keeping the last held
1538
- take starts the cut. Otherwise a new run films it again.
1663
+ take starts the cut. Otherwise a new run films it again. On a One-shot run
1664
+ that cut is delivered by itself: say so before the last keep.
1539
1665
  A take held for its label has a sentence that begins "The label check
1540
1666
  read the product's label as mirror writing in take N", says why it was not
1541
1667
  fixed (a flip would turn the room around against the other takes, the take
@@ -2191,7 +2317,8 @@ length. Do not invent a number.
2191
2317
  `pull` writes a flat folder and a `manifest.json` that indexes it. The manifest
2192
2318
  is the data you decide from; the filenames are its values. Scene numbers are the
2193
2319
  run's own. Every `pull` re-downloads and overwrites every file, so running it
2194
- again is always safe.
2320
+ again is always safe. It never writes the finished video the app made ("End:
2321
+ watch and approve").
2195
2322
 
2196
2323
  ```
2197
2324
  storyboard.json the whole storyboard envelope (see below)
@@ -83,6 +83,9 @@ export class FirstCutError extends Error {
83
83
  readonly code: 1 | 2;
84
84
  }
85
85
 
86
+ /** Why a finished cut is refused for its loudness (LoudnessRefusal's message), or null when its true peak is at or under -1 dBTP. */
87
+ export function truePeakRefusal(measured: { i: number; tp: number } | null): string | null;
88
+
86
89
  /** The finished cut's true peak is over -1 dBTP, or could not be measured, after the loudness pass. */
87
90
  export class LoudnessRefusal extends FirstCutError {
88
91
  constructor(message: string, measured: { i: number; tp: number } | null);
@@ -269,8 +272,11 @@ export interface CutPace {
269
272
  /** COP-300: the finished cut was checked against its own sound (cutSync). */
270
273
  captionCheck?: true;
271
274
  };
272
- /** `limited`: limitPeaks' limiter ran after the loudness pass. */
273
- loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true };
275
+ /**
276
+ * `limited`: limitPeaks' limiter ran after the loudness pass. #4573: `limitedAgain` times it ran again lower, from
277
+ * the same mix, because the finished file was over -1 dBTP; `limit` is the ceiling the kept cut was made at.
278
+ */
279
+ loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true; limitedAgain?: number; limit?: number };
274
280
  /** Present only with cutChecks. */
275
281
  checks?: CutChecks;
276
282
  /** COP-300: present when a sped-up cut burned its captions: the caption file is on the finished cut's clock. */
@@ -199,11 +199,32 @@ export const FINISH_LRA = 11;
199
199
  export const TRUE_PEAK_MAX_DB = -1;
200
200
  /**
201
201
  * limitPeaks: after the loudness pass, the sound oversampled 4x through a
202
- * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
202
+ * limiter at PEAK_LIMIT (about -1.9 dB), so a peak between two samples is caught too.
203
203
  * The cut is still measured after and refused over TRUE_PEAK_MAX_DB. Its
204
204
  * resample is pinned to stereo, as every one after loudnorm is (loudnessApplyArgs).
205
205
  */
206
- export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
206
+ export const PEAK_LIMIT = 0.8;
207
+ /** The limiter at `limit`, a linear level alimiter takes from 0.0625 to 1. */
208
+ export function peakLimiter(limit = PEAK_LIMIT) {
209
+ return `aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=${limit}:level=false:attack=2:release=60`;
210
+ }
211
+ export const PEAK_LIMITER = peakLimiter();
212
+ /**
213
+ * #4573: the AAC encode after the limiter can put a peak back over
214
+ * TRUE_PEAK_MAX_DB, by a different amount on each cut of the same takes (the
215
+ * room tone is fresh noise every time). A limited cut that lands over is
216
+ * limited again from the same mix, this many times at most, each time lower by
217
+ * what the last one landed over FINISH_TRUE_PEAK; still over, it is refused.
218
+ */
219
+ export const LIMIT_AGAIN_MAX = 2;
220
+ /** The lowest ceiling a limit again goes to (about -6 dB): a cut that needs lower is refused, not squashed. */
221
+ const PEAK_LIMIT_MIN = 0.5;
222
+
223
+ /** The next ceiling down after a limited pass measured `tp` dBTP. */
224
+ export function lowerPeakLimit(limit, tp) {
225
+ const lower = limit * 10 ** (-(tp - FINISH_TRUE_PEAK) / 20);
226
+ return Math.max(PEAK_LIMIT_MIN, Math.round(lower * 10_000) / 10_000);
227
+ }
207
228
  /**
208
229
  * jumpCut: inside a talking clip, a pause over maxGap between two heard words
209
230
  * is cut down, keeping keepAfter after the earlier word and keepBefore before
@@ -5571,11 +5592,9 @@ function ffmpegReason(res) {
5571
5592
  return res.signal ? `it was stopped by ${res.signal}.` : "it printed no reason.";
5572
5593
  }
5573
5594
 
5574
- /** Both passes on the mix, then the finished cut measured again. A receipt may
5575
- * retain that final observation without changing the legacy mastering result. */
5576
- export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null) {
5577
- const measured = measureLoudness(mix);
5578
- const args = loudnessApplyArgs(mix, measured, out, limiter);
5595
+ /** The mix normalized with pass one's numbers into `out`, through the limiter at `limit` when one is given. */
5596
+ function applyLoudness(mix, measured, out, limit) {
5597
+ const args = loudnessApplyArgs(mix, measured, out, limit == null ? null : peakLimiter(limit));
5579
5598
  const res = spawnSync("ffmpeg", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8", maxBuffer: 1 << 26 });
5580
5599
  if (res.status !== 0) {
5581
5600
  // ffmpeg's words still reach the log, and its reason leads the error:
@@ -5584,11 +5603,32 @@ export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null)
5584
5603
  const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
5585
5604
  throw new FirstCutError(1, `ffmpeg failed on the loudness pass: ${ffmpegReason(res)} The command it ran:\n ffmpeg ${quoted}`);
5586
5605
  }
5587
- const finished = measureLoudness(out);
5606
+ return measureLoudness(out);
5607
+ }
5608
+
5609
+ /** Both passes on the mix, then the finished cut measured again. A receipt may
5610
+ * retain that final observation without changing the legacy mastering result.
5611
+ * `limit` (limitPeaks) is the limiter's ceiling, PEAK_LIMIT; a limited cut over
5612
+ * the limit is limited again lower (LIMIT_AGAIN_MAX), one under it is left as it is. */
5613
+ export function finishLoudnessPass(mix, out, limit = null, onMeasured = null) {
5614
+ const measured = measureLoudness(mix);
5615
+ let ceiling = limit;
5616
+ let finished = applyLoudness(mix, measured, out, ceiling);
5617
+ let again = 0;
5618
+ while (ceiling != null && finished && finished.tp > TRUE_PEAK_MAX_DB && again < LIMIT_AGAIN_MAX) {
5619
+ const lower = lowerPeakLimit(ceiling, finished.tp);
5620
+ if (lower >= ceiling) break;
5621
+ ceiling = lower;
5622
+ finished = applyLoudness(mix, measured, out, ceiling);
5623
+ again++;
5624
+ }
5588
5625
  const refusal = truePeakRefusal(finished);
5589
5626
  if (refusal) throw new LoudnessRefusal(refusal, finished);
5590
5627
  onMeasured?.(finished);
5591
- return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1, ...(limiter ? { limited: true } : {}) };
5628
+ return {
5629
+ lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1,
5630
+ ...(limit != null ? { limited: true } : {}), ...(again > 0 ? { limitedAgain: again, limit: ceiling } : {}),
5631
+ };
5592
5632
  }
5593
5633
 
5594
5634
  /** The filters of `names` this ffmpeg does not have. */
@@ -6860,9 +6900,9 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6860
6900
  else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
6861
6901
  else clean = { voice: VOICE_CLEAN, under: UNDER_VOICE };
6862
6902
  }
6863
- let limiter = null;
6903
+ let peakLimit = null;
6864
6904
  if (finish?.limitPeaks) {
6865
- if (hasFilter("alimiter")) limiter = PEAK_LIMITER;
6905
+ if (hasFilter("alimiter")) peakLimit = PEAK_LIMIT;
6866
6906
  else notes.push("this ffmpeg has no alimiter filter, so the loudness pass ran without the limiter");
6867
6907
  }
6868
6908
  const paths = finishPaths(out);
@@ -6983,13 +7023,14 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6983
7023
  let loudnessMeasurement = null;
6984
7024
  if (finish?.finishLoudness) {
6985
7025
  try {
6986
- loudness = finishLoudnessPass(rendered, out, limiter, template
7026
+ loudness = finishLoudnessPass(rendered, out, peakLimit, template
6987
7027
  ? (measured) => { loudnessMeasurement = measured; } : null);
6988
7028
  } catch (error) {
6989
- if (!template || !(error instanceof FirstCutError)) throw error;
6990
- // One local limiter pass on the same retained mix, never a provider call.
7029
+ // A limited pass already limited itself again (#4573); the same mix would only be refused the same way.
7030
+ if (!template || peakLimit != null || !(error instanceof FirstCutError)) throw error;
7031
+ // The limiter on the same retained mix, never a provider call, limited again lower as finishLoudnessPass does.
6991
7032
  // If it still clips or cannot be measured, the refusal holds the cut.
6992
- loudness = finishLoudnessPass(rendered, out, PEAK_LIMITER,
7033
+ loudness = finishLoudnessPass(rendered, out, PEAK_LIMIT,
6993
7034
  (measured) => { loudnessMeasurement = measured; });
6994
7035
  } finally {
6995
7036
  rmSync(rendered, { force: true });
@@ -74,6 +74,10 @@ export interface CustomerRun {
74
74
  notes?: string[];
75
75
  } | null;
76
76
  canRetry: boolean;
77
+ canCutAgain?: boolean;
78
+ cutFailure?: {
79
+ sentence: string;
80
+ };
77
81
  stopReason: CustomerStopReason | null;
78
82
  detailsPath: string | null;
79
83
  cutHolds?: string[];
@@ -100,6 +100,13 @@ function stoppedLines(run, page) {
100
100
  run.canRetry ? `Try again from the video's page: ${page}` : "Start a new one from the Video page.",
101
101
  ];
102
102
  }
103
+ if (run.cutFailure && run.canCutAgain) {
104
+ return [
105
+ "The final cut didn't work.",
106
+ run.cutFailure.sentence,
107
+ `All your clips are done. Cut again from the video's page; it makes no new clips and costs nothing: ${page}`,
108
+ ];
109
+ }
103
110
  return run.canRetry
104
111
  ? ["Something went wrong making this video.", `Try again from the video's page: ${page}`]
105
112
  : ["Something went wrong making this video. Start a new one from the Video page."];
@@ -167,6 +167,9 @@ export interface SwipeDraft {
167
167
  ours: number;
168
168
  theirs: number;
169
169
  };
170
+ howClose?: {
171
+ sentence: string;
172
+ };
170
173
  }
171
174
  export interface SwipeView {
172
175
  _id: string;
@@ -26,7 +26,7 @@ export const SWIPE_MODES = [
26
26
  ];
27
27
  export const SWIPE_CLOSENESS = [
28
28
  { step: 1, flag: "mirror", name: "Mirror", line: "Same lines in the same order. Only your brand, product and claims change." },
29
- { step: 2, flag: "close", name: "Close", line: "Same parts in the same order, each line said in new words." },
29
+ { step: 2, flag: "close", name: "Close", line: "Same parts in the same order, with the same kind of line in each, in new words." },
30
30
  { step: 3, flag: "same-beats", name: "Same beats", line: "Same job for each part, in the same order. New words and new examples." },
31
31
  {
32
32
  step: 4,
@@ -1112,6 +1112,7 @@ function swipeLines(swipe, after) {
1112
1112
  `Kept: ${draft.note.kept}`,
1113
1113
  `Changed: ${draft.note.changed}`,
1114
1114
  ...(draft.lengthGap ? [`Length: ours is about ${draft.lengthGap.ours} s, theirs about ${draft.lengthGap.theirs} s.`] : []),
1115
+ ...(draft.howClose ? [draft.howClose.sentence] : []),
1115
1116
  costLine(swipe),
1116
1117
  "",
1117
1118
  swipe.workflowRunId && swipe.runHoldsStart === false
@@ -196,6 +196,8 @@ export interface VideoRun {
196
196
  status: string;
197
197
  isTerminal: boolean;
198
198
  error?: string;
199
+ costUsd?: number;
200
+ costScope?: "soFar" | "final";
199
201
  pauseReason?: BuilderPauseReason | "pilot";
200
202
  pausedNodeId?: string;
201
203
  pilot?: {
@@ -223,6 +225,9 @@ export interface VideoRun {
223
225
  };
224
226
  workflowId?: string;
225
227
  cutHeldScenes?: number[];
228
+ cutFailure?: {
229
+ sentence: string;
230
+ };
226
231
  cutCheck?: string[];
227
232
  moduleOwned?: boolean;
228
233
  director?: RunDirector;
@@ -328,6 +333,7 @@ export type RunStop = {
328
333
  framesNodeId?: string;
329
334
  heldScenes?: number[];
330
335
  heldTakes?: HeldTake[];
336
+ cutFailure?: string;
331
337
  } | {
332
338
  at: "pilot";
333
339
  nodeId?: string;
@@ -607,6 +613,9 @@ export declare function waitFlow(runId: string, opts: {
607
613
  onProgressLine?: (line: string) => void;
608
614
  }, deps: VideoDeps): Promise<FlowResult>;
609
615
  export declare function statusFlow(runId: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
616
+ export declare const ONE_TAKE_FILMED_AGAIN_CODE = "one-take-filmed-again";
617
+ export declare const COST_LEAVES_OUT = "Not in it: what was made before the run, such as a swipe's script and people.";
618
+ export declare function runCostLine(run: Pick<VideoRun, "costUsd" | "costScope" | "isTerminal">, items: readonly NodeItem[]): string | null;
610
619
  export declare const ONE_TAKE_HEARD_AS_CODE = "one-take-words-heard-as";
611
620
  export declare const ONE_TAKE_LABEL_CODES: readonly ["one-take-label-flipped", "one-take-label-unsure", "one-take-label-held", "one-take-label-flipped-all"];
612
621
  export declare const ONE_TAKE_SAID_WRONG_CODES: readonly ["one-take-said-wrong", "one-take-second-listen-failed"];
@@ -487,7 +487,7 @@ one.
487
487
  1 mirror Mirror
488
488
  Same lines in the same order. Only your brand, product and claims change.
489
489
  2 close Close
490
- Same parts in the same order, each line said in new words.
490
+ Same parts in the same order, with the same kind of line in each, in new words.
491
491
  3 same-beats Same beats
492
492
  Same job for each part, in the same order. New words and new examples.
493
493
  4 same-arc Same arc
@@ -916,6 +916,7 @@ export function classifyRun(run) {
916
916
  ...(missingScenes.length > 0 ? { missingScenes } : {}),
917
917
  ...(missingScenes.length > 0 && framesNodeId ? { framesNodeId } : {}),
918
918
  ...(run.cutHeldScenes?.length ? { heldScenes: run.cutHeldScenes } : {}),
919
+ ...(run.cutFailure?.sentence ? { cutFailure: run.cutFailure.sentence } : {}),
919
920
  };
920
921
  }
921
922
  return { at: "paused", nodeId: run.pausedNodeId, reason: run.pauseReason };
@@ -1141,6 +1142,16 @@ export function stopLines(stop, runId, runUrl, videoPage) {
1141
1142
  }
1142
1143
  if (stop.heldScenes?.length)
1143
1144
  return heldSceneLines(stop.heldScenes, runId, videoPage, stop.heldTakes);
1145
+ if (stop.cutFailure) {
1146
+ return [
1147
+ "Parked: every piece is made, but the app's cut of them didn't work.",
1148
+ stop.cutFailure,
1149
+ `Cut it again on the video's page. It makes no new clips and costs nothing: ${videoPage}`,
1150
+ `Or cut it yourself: exodus video pull ${runId} --out ./ad-${runId}`,
1151
+ `Then upload: exodus video upload ${runId} --file cut.mp4`,
1152
+ `Watch it here: ${runUrl}`,
1153
+ ];
1154
+ }
1144
1155
  if (stop.cutAttached === null) {
1145
1156
  return [
1146
1157
  "Parked: every piece is made.",
@@ -4007,7 +4018,8 @@ export async function statusFlow(runId, json, deps) {
4007
4018
  if (run.nodes.some((n) => n.kind === "storyboard" && n.status === "done")) {
4008
4019
  lines.push(...(await statusVoiceLines(runId, deps)));
4009
4020
  }
4010
- lines.push("", hasFinal && stop.at === "finished"
4021
+ const cost = runCostLine(run, items);
4022
+ lines.push("", ...(cost ? [cost] : []), hasFinal && stop.at === "finished"
4011
4023
  ? "Final cut: approved and delivered."
4012
4024
  : hasFinal
4013
4025
  ? `Final cut: uploaded. Approve it with: exodus video approve ${runId}`
@@ -4020,6 +4032,29 @@ export async function statusFlow(runId, json, deps) {
4020
4032
  lines.push("Final speech:", ...speechSummaryLines(finalSpeech));
4021
4033
  return { code: 0, lines };
4022
4034
  }
4035
+ export const ONE_TAKE_FILMED_AGAIN_CODE = "one-take-filmed-again";
4036
+ export const COST_LEAVES_OUT = "Not in it: what was made before the run, such as a swipe's script and people.";
4037
+ export function runCostLine(run, items) {
4038
+ const total = run.costUsd;
4039
+ if (typeof total !== "number" || !Number.isFinite(total) || total <= 0)
4040
+ return null;
4041
+ const finished = run.costScope === undefined ? run.isTerminal === true : run.costScope === "final";
4042
+ const filmed = new Map();
4043
+ for (const item of items) {
4044
+ if (item.itemKind !== "clip" || !isPullSceneIndex(item.sceneIndex))
4045
+ continue;
4046
+ if (!(item.findings ?? []).some((f) => f.code === ONE_TAKE_FILMED_AGAIN_CODE))
4047
+ continue;
4048
+ const times = item.artifact?.type === "video" ? item.artifact.qc?.attempts : undefined;
4049
+ if (typeof times === "number" && Number.isInteger(times))
4050
+ filmed.set(item.sceneIndex, Math.max(filmed.get(item.sceneIndex) ?? 0, times));
4051
+ }
4052
+ const again = [...filmed.entries()]
4053
+ .filter(([, times]) => times > 1)
4054
+ .sort(([a], [b]) => a - b)
4055
+ .map(([scene, times]) => `scene ${scene} was filmed ${times} times`);
4056
+ return `${finished ? "Cost" : "Cost so far"}: $${total.toFixed(2)}${again.length > 0 ? ` (${again.join(", ")})` : ""}. ${COST_LEAVES_OUT}`;
4057
+ }
4023
4058
  export const ONE_TAKE_HEARD_AS_CODE = "one-take-words-heard-as";
4024
4059
  export const ONE_TAKE_LABEL_CODES = ["one-take-label-flipped", "one-take-label-unsure", "one-take-label-held", "one-take-label-flipped-all"];
4025
4060
  const ONE_TAKE_LABEL_ALL_FLIPPED_CODE = "one-take-label-flipped-all";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aicopycoders/exodus",
3
- "version": "2026.11.1200-beta.11",
3
+ "version": "2026.11.1200-beta.13",
4
4
  "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
5
5
  "repository": {
6
6
  "type": "git",