rushes 0.11.0 → 0.12.0

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.
@@ -17,7 +17,7 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
17
17
  2. **Interview, briefly.** Ask at most three questions, and only ones whose answer changes the film: length and formats, who it is for, tone. Give each a recommended answer with its trade-off ("30 seconds fits a feed; 60 leaves room for the demo"). Never send a list of ten.
18
18
  3. **Write `brief.md`.** Fill every section and leave `Status: draft`. Tell the user to open Plan › Brief in Rushes, change any section and press **Approve brief**. Rushes then sets `Status: approved` in the file itself. Never approve it yourself or change that line, and if they say it's approved in chat while the file still says `draft`, ask them to press Approve. When they press **Send** on the Brief page, read `brief.md` again and keep their wording: a section they changed shows "Edited by you" with your last version struck through beneath it, so read the file before you rewrite it.
19
19
  4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in Plan › Script. Read `rushes_get_script` and wait until every section is `approved`.
20
- 5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
20
+ 5. **Storyboard.** Write the film's storyboard (`storyboard.md` in the project root for the first film, `films/<film-id>/storyboard.md` for any other): a `# Storyboard: <film>` title, then one section per shot, in this shape:
21
21
 
22
22
  ```markdown
23
23
  ## Shot 02 · Drop a folder
@@ -33,7 +33,7 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
33
33
  `Length` is planned seconds (they become the cut's shot starts), `Still` is a project-relative picture (png, jpg, webp or gif), best saved under `storyboard/`, and `Direction` is the user's line. Make a still for each shot if your tools can; the Storyboard page shows any still the file names, registered or not. The user reads and approves each shot in Plan › Storyboard, and Rushes sets `Status: approved` itself: never set or change a shot's status yourself. When they press **Send** there, read `storyboard.md` again, keep their wording, and update the still if what happens has changed.
34
34
  6. **Build only when all three are approved** (`rushes_status` reports `build`: `ready`, and what it is `waitingOn`). If the user says "just build it", do. Build in whatever tool suits the film, and name each scene after its planned shot. Then register the cut with `rushes_add_version`: a film's first cut starts with the storyboard's shots by itself (each `start` the running total of the lengths before it), so call `rushes_set_shots` only when the real timings differ (a cut brought in with `rushes_scan` or `rushes_bring_in` does not: send its shots with `rushes_set_shots`). A film with no script has nothing to wait on there: the script is only waited on when the film has one. While the plan isn't all approved the reply carries `planWarning`: a nudge, not a refusal.
35
35
 
36
- The brief and the storyboard are Markdown files the user reads and approves on their own pages under Plan.
36
+ The brief and the storyboard are Markdown files the user reads and approves on their own pages under Plan. Each film has its own script, brief and storyboard: the first film's brief and storyboard are `brief.md` and `storyboard.md` at the project root, every other film's are `films/<film-id>/brief.md` and `films/<film-id>/storyboard.md` (`rushes_status` lists each film's paths). The tools that read or write a film's material (`rushes_status`, `rushes_set_script`, `rushes_get_script`, `rushes_list_notes`, `rushes_get_log`, `rushes_list_assets`) take `film`, required when the project has several films. Visuals are shared by every film.
37
37
 
38
38
  ## Picking up a film that's underway
39
39
 
@@ -61,10 +61,10 @@ For stills, standalone images and carousels, register one visual per post with `
61
61
  - `rushes_add_version` for a render. Give every cut a short `label` (48 characters at most) saying what changed, and put the detail in `note` as one short summary line, then a `- ` line per change (the Cut menu shows them as points). If the cut is likely to play badly in a browser, the reply carries `proxySuggested: true` and `proxyReason`; the Timeline tab offers the user a proxy. Prefer H.264 MP4 to avoid this;
62
62
  - `rushes_add_format` for each other shape of a cut (a 9:16, 1:1 or 4:5 of the same edit): register every shape you rendered, main one first, or pass `formats: [{ file }]` to `rushes_add_version`. Its `label` is only a ratio hint such as 2.39:1, never the cut's short label;
63
63
  - `rushes_set_script` for the VO script. It merges by `id`, so send only the sections you changed; sections you leave out are kept. `rushes_get_script` reads the whole script;
64
- - `rushes_add_variant` for each voice read, music bed or SFX pass, with `video` set to the film it is for, or a list of films when one bed is fitted to several (only those films' tabs list it; with more than one film, one without `video` is on no film until it is put on one, and `rushes_set_films` moves an existing one). Put a take only on the films it was fitted to (a read timed to one film's cut is that film's alone, even when another film shares its script), and when a new cut changes a film's length or timing, fit its bed and effects to that cut as new takes. Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX take a `round` too (each new batch is a round). A take you add is not in use until the user picks it. Music and SFX carry `meta.description` for their row in the list of takes, and SFX passes carry `cues` as `{name, t, file?}`: the same name each time a sound comes back, and `file` (an audio file) when you know which sample you placed;
64
+ - `rushes_add_variant` for each voice read, music bed or SFX pass, with `video` set to the film it is for, or a list of films when one bed is fitted to several (only those films' tabs list it; with more than one film, one without `video` whose film can't be told from its names goes on the first film, and `rushes_set_films` moves an existing one). Put a take only on the films it was fitted to (a read timed to one film's cut is that film's alone, even when another film shares its script), and when a new cut changes a film's length or timing, fit its bed and effects to that cut as new takes. Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX take a `round` too (each new batch is a round). A take you add is not in use until the user picks it. Music and SFX carry `meta.description` for their row in the list of takes, and SFX passes carry `cues` as `{name, t, file?}`: the same name each time a sound comes back, and `file` (an audio file) when you know which sample you placed;
65
65
  - `rushes_set_shots` for the storyboard's shots, once you have the first cut; send new timings when a later cut moves them.
66
66
  2. Call `rushes_open` and tell the user it's ready, with what it brought in and what it left (below). Each project's dashboard lives at its own address, `/p/<id>/`.
67
- 3. When the user sends a batch, call `rushes_get_batch` and fix every note in it. Before you start on each note, call `rushes_working_on` with its id and what you are doing, in a few plain words: the user sees it on the note while you work. A batch holds every open note from every tab and film, so each note's own `stage` and `video` say where it belongs. A note carries the `shot` it falls in; on an audio stage, call `rushes_get_picks` first — for a mix note (stage `mix`, made on the Timeline tab) it also returns `levels` (dB per sound), which you read, not set; when they equal `balanced.levels` they are Rushes' house balance (Balance on the Timeline, or set by itself when a take is put in use), so render new takes near those levels: `rushes balance --voice F --music F --sfx F` measures files against the same rule and says how far each would move. Its `on` says what it's about: `"<lane>/<variant>"` for a bed, pass or voice read (for a voice read the lane names the round), `"<lane>/<variant>:<cue>"` for an SFX cue, `"vo"` for the voice in the mix, or `null` for the whole mix; older notes may carry a section id or `"<section>:<take>"`. On music, sfx and mix notes treat `marks` (e.g. "Fall", "Quieter 3 dB") as part of the note; voice notes carry none — they're on the whole read, a point in it, or a range of it (`t` to `tOut`: replace or fix just that stretch), and the `text` says what to change. A note on the cut (stage `picture`) has a `format` that is null for every format, or a format id such as `"9x16"`: when it isn't null, fix only that format. Picks are set from the dashboard only — no tool or CLI command sets one.
67
+ 3. When the user sends a batch, call `rushes_get_batch` and fix every note in it. Before you start on each note, call `rushes_working_on` with its id and what you are doing, in a few plain words: the user sees it on the note while you work. A batch is about one film (the one the user had selected when they pressed Send, named in the batch's `film`): pass that film to every tool that asks for one while you work it. It holds every open note from every tab on that film, so each note's own `stage` says where it belongs. A note carries the `shot` it falls in; on an audio stage, call `rushes_get_picks` first — for a mix note (stage `mix`, made on the Timeline tab) it also returns `levels` (dB per sound), which you read, not set; when they equal `balanced.levels` they are Rushes' house balance (Balance on the Timeline, or set by itself when a take is put in use), so render new takes near those levels: `rushes balance --voice F --music F --sfx F` measures files against the same rule and says how far each would move. Its `on` says what it's about: `"<lane>/<variant>"` for a bed, pass or voice read (for a voice read the lane names the round), `"<lane>/<variant>:<cue>"` for an SFX cue, `"vo"` for the voice in the mix, or `null` for the whole mix; older notes may carry a section id or `"<section>:<take>"`. On music, sfx and mix notes treat `marks` (e.g. "Fall", "Quieter 3 dB") as part of the note; voice notes carry none — they're on the whole read, a point in it, or a range of it (`t` to `tOut`: replace or fix just that stretch), and the `text` says what to change. A note on the cut (stage `picture`) has a `format` that is null for every format, or a format id such as `"9x16"`: when it isn't null, fix only that format. Picks are set from the dashboard only — no tool or CLI command sets one.
68
68
  4. Register the new cut with `rushes_add_version`. On a locked video the reply carries a `warning`.
69
69
  5. Reply to all the notes in one `rushes_reply` call. For each note set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. Each note has a `state`: `todo` (not sent yet), `sent` (yours to fix) or `done`; `rushes_list_notes` with `state: "sent"` finds every note you still owe. `rushes_get_picks` lists each take's `state` too (`in-use`, `new`, `earlier`, `put-away`): never offer a put-away take again.
70
70
  6. For script batches: when a section's `proposed` differs from `current`, adopt it with `rushes_set_script`, sending just that section with its `id`. If voiceover already exists, re-record the picked voice with the corrected script and register it with `rushes_add_variant` as a new read in a new round.