rushes 0.8.1 → 0.9.1
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.
- package/.claude-plugin/plugin.json +1 -1
- package/AGENTS.md +26 -26
- package/README.md +60 -56
- package/dist/cli/demo.js +20 -8
- package/dist/cli/main.js +1 -1
- package/dist/core/approval.js +15 -0
- package/dist/core/batches.js +5 -4
- package/dist/core/exportNotes.js +6 -4
- package/dist/core/logText.js +1 -1
- package/dist/core/noteState.js +46 -0
- package/dist/core/notes.js +20 -12
- package/dist/core/picks.js +79 -0
- package/dist/core/project.js +27 -2
- package/dist/core/schema.js +20 -2
- package/dist/core/script.js +6 -2
- package/dist/core/tabs.js +3 -2
- package/dist/core/takes.js +73 -0
- package/dist/mcp/tools.js +11 -9
- package/dist/server/app.js +92 -23
- package/dist/server/brief.js +5 -2
- package/dist/server/loudness.js +20 -45
- package/dist/server/storyboard.js +4 -1
- package/package.json +3 -3
- package/skills/rushes/SKILL.md +13 -13
- package/web-dist/assets/geist-cyrillic-400-normal-DXusLSnH.woff2 +0 -0
- package/web-dist/assets/geist-cyrillic-400-normal-DkrqoNl2.woff +0 -0
- package/web-dist/assets/geist-cyrillic-500-normal-BboVsk8R.woff +0 -0
- package/web-dist/assets/geist-cyrillic-500-normal-NWpm63d5.woff2 +0 -0
- package/web-dist/assets/geist-cyrillic-600-normal-BeW5VFD_.woff2 +0 -0
- package/web-dist/assets/geist-cyrillic-600-normal-CnEeIcMC.woff +0 -0
- package/web-dist/assets/geist-cyrillic-700-normal-BH7gZKkM.woff +0 -0
- package/web-dist/assets/geist-cyrillic-700-normal-BSHy2ewF.woff2 +0 -0
- package/web-dist/assets/geist-cyrillic-ext-400-normal-ChfpGzr5.woff +0 -0
- package/web-dist/assets/geist-cyrillic-ext-500-normal-BXrH8YSv.woff +0 -0
- package/web-dist/assets/geist-cyrillic-ext-600-normal-PR76dHFV.woff +0 -0
- package/web-dist/assets/geist-cyrillic-ext-700-normal-CBIC21Ex.woff +0 -0
- package/web-dist/assets/geist-latin-400-normal-B40WzpMT.woff2 +0 -0
- package/web-dist/assets/geist-latin-400-normal-akEymXtG.woff +0 -0
- package/web-dist/assets/geist-latin-500-normal-BDXIbFrL.woff +0 -0
- package/web-dist/assets/geist-latin-500-normal-CTWBw9NS.woff2 +0 -0
- package/web-dist/assets/geist-latin-600-normal-CSETrqM2.woff2 +0 -0
- package/web-dist/assets/geist-latin-600-normal-DsPlZH-9.woff +0 -0
- package/web-dist/assets/geist-latin-700-normal-Bod5GerT.woff +0 -0
- package/web-dist/assets/geist-latin-700-normal-CFi8mLqe.woff2 +0 -0
- package/web-dist/assets/geist-latin-ext-400-normal-Bz1pQMyt.woff +0 -0
- package/web-dist/assets/geist-latin-ext-400-normal-CND6cjiG.woff2 +0 -0
- package/web-dist/assets/geist-latin-ext-500-normal-BovoTgeE.woff2 +0 -0
- package/web-dist/assets/geist-latin-ext-500-normal-C9fx-R30.woff +0 -0
- package/web-dist/assets/geist-latin-ext-600-normal-CVFbg5dS.woff2 +0 -0
- package/web-dist/assets/geist-latin-ext-600-normal-TmIUreF9.woff +0 -0
- package/web-dist/assets/geist-latin-ext-700-normal-BnofTsEi.woff2 +0 -0
- package/web-dist/assets/geist-latin-ext-700-normal-DKAtFBEc.woff +0 -0
- package/web-dist/assets/geist-mono-cyrillic-400-normal-C51Di1Mf.woff2 +0 -0
- package/web-dist/assets/geist-mono-cyrillic-400-normal-CPJFfJgk.woff +0 -0
- package/web-dist/assets/geist-mono-cyrillic-500-normal-D2cXvDHF.woff2 +0 -0
- package/web-dist/assets/geist-mono-cyrillic-500-normal-DfuvdVgn.woff +0 -0
- package/web-dist/assets/geist-mono-latin-400-normal-B2yvC1Cq.woff +0 -0
- package/web-dist/assets/geist-mono-latin-400-normal-DTRLJnHl.woff2 +0 -0
- package/web-dist/assets/geist-mono-latin-500-normal-D-GG86Jb.woff +0 -0
- package/web-dist/assets/geist-mono-latin-500-normal-YINYabwD.woff2 +0 -0
- package/web-dist/assets/geist-mono-latin-ext-400-normal-CfzLURNc.woff +0 -0
- package/web-dist/assets/geist-mono-latin-ext-400-normal-DI-rJ0UV.woff2 +0 -0
- package/web-dist/assets/geist-mono-latin-ext-500-normal-Buglb9-a.woff2 +0 -0
- package/web-dist/assets/geist-mono-latin-ext-500-normal-CrWEgvU_.woff +0 -0
- package/web-dist/assets/geist-mono-symbols2-400-normal-DjbiTEEA.woff +0 -0
- package/web-dist/assets/geist-mono-symbols2-500-normal-CmnCPGa0.woff +0 -0
- package/web-dist/assets/geist-mono-vietnamese-400-normal-CZEPLOgu.woff +0 -0
- package/web-dist/assets/geist-mono-vietnamese-500-normal-Dx9-epDo.woff +0 -0
- package/web-dist/assets/geist-vietnamese-400-normal-C8xY9-dI.woff +0 -0
- package/web-dist/assets/geist-vietnamese-500-normal-_b1ojCbH.woff +0 -0
- package/web-dist/assets/geist-vietnamese-600-normal-B5MZcNo4.woff +0 -0
- package/web-dist/assets/geist-vietnamese-600-normal-BFUgqsz8.woff2 +0 -0
- package/web-dist/assets/geist-vietnamese-700-normal-Dm6ODIDG.woff +0 -0
- package/web-dist/assets/index-D8GLNrzy.css +1 -0
- package/web-dist/assets/index-DdsawADA.js +67 -0
- package/web-dist/index.html +2 -2
- package/web-dist/assets/figtree-latin-400-normal-BD4aNku5.woff +0 -0
- package/web-dist/assets/figtree-latin-400-normal-g7Dtegnw.woff2 +0 -0
- package/web-dist/assets/figtree-latin-500-normal-BWnGEVsr.woff2 +0 -0
- package/web-dist/assets/figtree-latin-500-normal-B_yy1phn.woff +0 -0
- package/web-dist/assets/figtree-latin-600-normal-BM_oTo4n.woff +0 -0
- package/web-dist/assets/figtree-latin-600-normal-Cv_xCTDl.woff2 +0 -0
- package/web-dist/assets/figtree-latin-700-normal-BCCt2T1q.woff +0 -0
- package/web-dist/assets/figtree-latin-700-normal-th6qEP7c.woff2 +0 -0
- package/web-dist/assets/figtree-latin-ext-400-normal-CXAzuTZb.woff2 +0 -0
- package/web-dist/assets/figtree-latin-ext-400-normal-Gbh-3PTk.woff +0 -0
- package/web-dist/assets/figtree-latin-ext-500-normal-BOEJvrb_.woff +0 -0
- package/web-dist/assets/figtree-latin-ext-500-normal-Du0rIuHj.woff2 +0 -0
- package/web-dist/assets/figtree-latin-ext-600-normal-CQqsimlV.woff +0 -0
- package/web-dist/assets/figtree-latin-ext-600-normal-DJlfifZj.woff2 +0 -0
- package/web-dist/assets/figtree-latin-ext-700-normal-BoDi4KL2.woff +0 -0
- package/web-dist/assets/figtree-latin-ext-700-normal-CS4sQkGV.woff2 +0 -0
- package/web-dist/assets/index-DhS2fPd_.js +0 -11
- package/web-dist/assets/index-jf-RHBPN.css +0 -1
- package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-BEIGL1Tu.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-ugxPyKxw.woff +0 -0
- package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DJqRU3vO.woff +0 -0
- package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DmUKJPL_.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-greek-400-normal-B9oWc5Lo.woff +0 -0
- package/web-dist/assets/jetbrains-mono-greek-400-normal-C190GLew.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-greek-500-normal-D7SFKleX.woff +0 -0
- package/web-dist/assets/jetbrains-mono-greek-500-normal-JpySY46c.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-latin-400-normal-6-qcROiO.woff +0 -0
- package/web-dist/assets/jetbrains-mono-latin-400-normal-V6pRDFza.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-latin-500-normal-BWZEU5yA.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-latin-500-normal-CJOVTJB7.woff +0 -0
- package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-Bc8Ftmh3.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-fXTG6kC5.woff +0 -0
- package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-Cut-4mMH.woff2 +0 -0
- package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-ckzbgY84.woff +0 -0
- package/web-dist/assets/jetbrains-mono-vietnamese-400-normal-CqNFfHCs.woff +0 -0
- package/web-dist/assets/jetbrains-mono-vietnamese-500-normal-DNRqzVM1.woff +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rushes",
|
|
3
3
|
"description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent reads and acts on.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.9.1",
|
|
5
5
|
"author": { "name": "Red Morley Hewitt" },
|
|
6
6
|
"homepage": "https://github.com/iamredmh/rushes",
|
|
7
7
|
"repository": "https://github.com/iamredmh/rushes",
|
package/AGENTS.md
CHANGED
|
@@ -32,7 +32,7 @@ Save renders to `renders/`, voice reads to `audio/voiceover/`, music beds to `au
|
|
|
32
32
|
|
|
33
33
|
## The Assets library
|
|
34
34
|
|
|
35
|
-
The **Assets**
|
|
35
|
+
The **Assets** workspace is a library of every project file, organised into folders: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and, once a cut has one, Proxies. Proxies are listed and deleted from there; you never register or remove one yourself — see proxies, below.
|
|
36
36
|
|
|
37
37
|
Some of it needs no registering. A `*.md`, `*.txt`, `*.pdf`, `*.srt` or `*.vtt` file directly in the project root, and anything saved directly into `exports/`, are found automatically.
|
|
38
38
|
|
|
@@ -53,8 +53,8 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
|
|
|
53
53
|
|
|
54
54
|
1. **Create the project** unless one exists: `npx -y rushes new <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. It makes the project, `renders/` and `audio/voiceover`, `audio/music` and `audio/sfx`, and a `brief.md` to fill in. It refuses a folder that is already a Rushes project and never overwrites a `brief.md` that is there. Always pass `--no-browser`: without it the command stays running as the server and never returns.
|
|
55
55
|
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.
|
|
56
|
-
3. **Write `brief.md`.** Its sections, in order, are Title, Purpose, Audience, Length and formats, Tone, Include and avoid, Built with, Open questions and References. Fill every one, keep the `Status: draft` line, and tell the user to open
|
|
57
|
-
4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in
|
|
56
|
+
3. **Write `brief.md`.** Its sections, in order, are Title, Purpose, Audience, Length and formats, Tone, Include and avoid, Built with, Open questions and References. Fill every one, keep the `Status: draft` line, and 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.
|
|
57
|
+
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`.
|
|
58
58
|
5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
|
|
59
59
|
|
|
60
60
|
```markdown
|
|
@@ -68,10 +68,10 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
|
|
|
68
68
|
A folder of clips lands in the window from the right.
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
-
`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
|
|
71
|
+
`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.
|
|
72
72
|
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.
|
|
73
73
|
|
|
74
|
-
The brief and the storyboard are Markdown files the user reads and approves on their own pages under
|
|
74
|
+
The brief and the storyboard are Markdown files the user reads and approves on their own pages under Plan. Use the same file names so the next session finds them.
|
|
75
75
|
|
|
76
76
|
## Picking up a film that's underway
|
|
77
77
|
|
|
@@ -79,7 +79,7 @@ When the user asks to open or review a film they started in the chat, or the pro
|
|
|
79
79
|
|
|
80
80
|
1. **Open the project**, or create it where the work is: `npx -y rushes new <folder> --no-browser` (it never overwrites a `brief.md` and leaves every other file alone), then `rushes_open`.
|
|
81
81
|
2. **Write `brief.md` from the conversation.** Fill each section from what the user actually said. Mark anything you had to infer with `(inferred)` so they can check it. Where the chat never touched a section, write `Not discussed yet.` rather than inventing something. Put ideas they floated but didn't settle, and anything you couldn't answer, under Open questions. Keep `Status: draft`, and never approve it yourself.
|
|
82
|
-
3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in
|
|
82
|
+
3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in Plan › Script). Copy storyboard stills into a `storyboard/` folder in the project: copy them, never move them, so the originals stay where the user's other tools expect them. Write the shots into `storyboard.md` in the shot format above, each with `Status: draft` and a `Still:` line naming its copy (the Storyboard page shows any still the file names). Register other reference images with `rushes_add_file` (`kind: "image"`). Renders, voice reads and music beds go in as usual (`rushes_add_version`, `rushes_add_variant`). Run `rushes_scan` for audio and cuts in the folder; it doesn't look for images, so naming the stills in `storyboard.md` (or registering other images) is yours to do: you know where you saved them.
|
|
83
83
|
4. **Say what you filled in:** what came from the user's words, what you inferred, what you registered, and what you looked for and couldn't find ("I found four of the six stills"). Ask them to read `brief.md` under Assets › Scripts & docs.
|
|
84
84
|
5. **If the chat is one you can't see** (another session, another tool), say so and ask the user to paste it or point you to it. Don't reconstruct a brief from memory of a conversation you didn't have.
|
|
85
85
|
|
|
@@ -91,13 +91,13 @@ No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `ru
|
|
|
91
91
|
|
|
92
92
|
## Locked tabs and the prompts they copy
|
|
93
93
|
|
|
94
|
-
Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. When Rushes has found files for a locked
|
|
94
|
+
Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. When Rushes has found files for a locked Voice, Music or Effects tab in the project folder, the page adds a line under the prompt, such as "14 music files found in this project", with a **Review** button that opens Assets › Found filtered to that kind. So a user may open a locked tab, see files you haven't brought in, and ask you about them: call `rushes_scan` to list them, and `rushes_bring_in` for the ones that belong. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
|
|
95
95
|
|
|
96
96
|
> In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
|
|
97
97
|
|
|
98
98
|
## Visuals: stills and carousels
|
|
99
99
|
|
|
100
|
-
When the user makes stills, standalone images or carousels (posts), register them so they can mark them up in the **Visuals**
|
|
100
|
+
When the user makes stills, standalone images or carousels (posts), register them so they can mark them up in the **Visuals** workspace, the way they mark a cut on the Timeline. Call `rushes_add_visual` with one visual per post: a `name` and `pages`, each page with its pictures, one per aspect ratio it comes in (a png, jpg, webp or gif inside the project; Rushes reads each ratio from the picture's own size, so never name one). A still is a visual with one page; a carousel has many. Every page must come in the same ratios, and every page needs a picture in every aspect ratio.
|
|
101
101
|
|
|
102
102
|
The user drags to mark a region on the picture, clicks for a point, or adds a note for the whole image, and sends a batch. `rushes_get_batch` and `rushes_list_notes` return each Visuals note with a `visual` object: the visual's id and name, its `version`, the `page`, the `ratio` as a label (null when the note is for every ratio), the `shape` (`region`, `pin` or `image`), the `region` or `pin` as fractions of the picture, `words` saying where it is ("left third, top third"), and the `file` to open. A note with no ratio is for every ratio: say in your reply which ratios you fixed.
|
|
103
103
|
|
|
@@ -105,33 +105,33 @@ To answer feedback, change the marked pictures and register the result as a new
|
|
|
105
105
|
|
|
106
106
|
## Shelved films
|
|
107
107
|
|
|
108
|
-
The user can shelve a film they have set aside (
|
|
108
|
+
The user can shelve a film they have set aside (**Shelve film** in the dashboard's **More** menu, or Shift+S). `rushes_status` returns `films`, each with `shelved`: the time it was shelved, or null. A shelved film is the user's decision: leave it alone, make no new cuts of it and fix none of its notes unless the user asks. Its open notes are not counted in the tabs or sent in batches, and `rushes_list_notes` leaves them out. A new cut of a shelved film brings it back (the reply has `restored: true`), so make one only when the user wants that film worked on again. You never shelve or restore a film: that is the user's to do.
|
|
109
109
|
|
|
110
110
|
## The loop
|
|
111
111
|
|
|
112
112
|
1. **Register what you made.**
|
|
113
|
-
- A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. Give every cut a short `label` (48 characters at most) that says what changed, e.g. `"launch 1.45x slower"`, and put the detail in `note
|
|
113
|
+
- A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. Give every cut a short `label` (48 characters at most) that says what changed, e.g. `"launch 1.45x slower"`, and put the detail in `note` as one short summary line, then a `- ` line per change (the Cut menu shows them as points): the Cut menu's version list shows the label, and a longer one is refused. When the cut is likely to play badly in a browser (4K or larger, over 1.5 GB, or a codec such as ProRes), the reply carries `proxySuggested: true` and `proxyReason`; the Timeline tab then offers the user a proxy (**Create proxy**, under the player). Prefer H.264 MP4 to begin with and this won't come up.
|
|
114
114
|
- Other shapes of the same cut (a 9:16, 1:1 or 4:5 of the 16:9: same edit, same length): register every shape you rendered, main one first. `rushes_add_version` with `file` (the main one) and `formats: [{ file }, …]` registers them all in one call; `rushes_add_format` (`file`, optional `video`, `version` and `label`) adds one to a cut already registered. Rushes measures each ratio with ffprobe; here `label` is only a ratio hint for an unusual shape such as 2.39:1 (not the cut's short label, which belongs to `rushes_add_version`). A second render with a ratio the cut already has is refused: a re-render is a new version. A shape more than 0.1 s off the cut's length is still registered, with a warning: `rushes_add_format` returns it as `warning`, and `rushes_add_version` returns a list as `formatWarnings` (there, `warning` means "Picture is locked").
|
|
115
115
|
- A VO script: `rushes_set_script` with sections `{start, end, current}` in seconds. It merges by `id`: send only the sections you changed, with their ids, plus any new ones without an id. Sections you leave out are kept, with their takes. Pass `replace: true` only when you mean to replace the whole script. `rushes_get_script` reads the whole script back.
|
|
116
116
|
- A voice read: `rushes_add_variant` with `stage: "voice"`, `video` (the film it is for) and `round` (the round's name, e.g. "Round 2 · Gerald, tone" — reads in one round are compared side by side; a new direction gets a new round, a small fix to a marked word can stay in the current one). Say in `description` what the read is, or what changed from the one it's based on. `rushes_add_take` stays in the file format and API for compatibility only; voiceover work doesn't use it.
|
|
117
|
-
- Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`, and `
|
|
118
|
-
- Every voice read, music bed and SFX pass belongs to one film or several: pass its `video` (an id or name, or a list of them when one bed is fitted to several films) to `rushes_add_variant`, and the
|
|
117
|
+
- Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`, `video`, and `round` as for a voice read (each new batch of beds or passes is a round, e.g. "Round 2 · softer middle"). Give it `meta: {description: "..."}` (and `bpm`, `key` or `lufs` when you know them), shown in its details: the tooltip on its name in the tab's list of takes and the line its details button opens; SFX passes also take `cues` (`{name, t, file?}`: `t` in seconds, and `file` the sample you placed there, an audio file, optional), labelled on the waveform. Give a sound the same name every time it comes back (`thud`, not `thud 2`): the Effects tab groups cues by name into layers, one per sound, and shows a cue's `file` on its card, where the user can play that sample on its own.
|
|
118
|
+
- Every voice read, music bed and SFX pass belongs to one film or several: pass its `video` (an id or name, or a list of them when one bed is fitted to several films) to `rushes_add_variant`, and the Voice, Music and Effects tabs (and the Timeline) list it only on those films. In a project with more than one film, one without a `video` is on no film: it waits, folded, under "Not on this film" on each film's tab (with the ones on other films) until someone puts it on one. `rushes_set_films` (`lane`, `variant`, `videos`) moves an existing one; the user does the same from the **Films** button on its card. `rushes_bring_in` and `rushes_open` give the files they bring in the `film` you name (or, for the files they match to the newest cut, that cut's film). 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 (Red, 16 Nov 2026: earlier reads listed on a second film read as clutter from the wrong film). When a new cut changes a film's length or timing, fit its bed and effects to the new cut and add them as new takes on that film; until then, tell the user the bed in use was made for an older cut.
|
|
119
119
|
- The storyboard's shots, once you have the first cut: `rushes_set_shots` with `video`, optional `version` (defaults to the newest) and `shots` as `{start, name, tag?}`. Send new timings whenever a later cut moves them.
|
|
120
120
|
2. **Open it for the user:** `rushes_open`. It also looks through the project folder and brings in the files that go with the cut (next section). Each project's dashboard lives at its own address, `/p/<id>/` — safe to run more than one project at once. A tab unlocks as soon as it has something in it.
|
|
121
|
-
3. **Wait for feedback.** The user presses **Send
|
|
122
|
-
4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` —
|
|
121
|
+
3. **Wait for feedback.** The user presses **Send**, at the foot of the notes panel, which saves a batch and gives them a prompt to paste to you. Wherever they press it, the batch holds every open note from every tab and every film in play, plus any changed script sections; its `stage` is the tab when everything came from one, or `null` when it spans tabs. Each note carries its own `stage` and `video`: fix each one on its own tab and film. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections. When the brief or the storyboard changed too, the prompt the user pastes ends with a line about each.
|
|
122
|
+
4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — on every tab, a voice read included: a voice range note is about that stretch of the read), `t`, `tOut`, `on` (the lane, variant, take, cue or section it's about), `text`, and optionally `box` (normalised 0 to 1), `grab` (a PNG path in `screenshots/`; older notes may point to `.rushes/grabs/`), `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set) and, on Picture, `format` (`null` when the note is for every format, or a format id such as `"9x16"` when it's for that shape only). When a note's `format` is not null, fix only that format and leave the others alone; an all-format note is for every shape, so fix each and say in `reply` which formats you fixed. `rushes_list_notes` takes `format` (an id such as `9x16`, or its label `9:16`: that format's Picture notes plus the all-format ones) and `onlyThisFormat: true` (only that format's). On an audio stage, `on` is `"<laneId>/<variantId>"` for a music bed, SFX pass or voice read (the lane and variant ids `rushes_add_variant` returns) — for a voice read the lane id is the round's slugged name, so `on` names the round and the read together — or `"<laneId>/<variantId>:<cueId>"` for an SFX cue. On a mix note (stage `mix`, made on the Timeline tab) it's `null` for the whole mix, `"vo"` for the voice (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or the effects. Older notes may carry a bare variant id, `"vo"` on a voice note itself, a section id, `"<sectionId>:<takeId>"` for a take, `"<variantId>:<cueId>"` or a bare cue id; Rushes still lists these with a sensible label, but none of them name a read any more. A music, sfx or mix note can also carry `marks` — short feedback like `Fall` (bring the level down over the range) or `Quieter 3 dB` (3 dB lower over the range). `rushes_list_notes`, `rushes_get_batch` and exported notes all show them. Marks are the user's, like a note's text and times — you read and act on them, you don't set them. Voice notes carry no marks: a voice note is about the whole read (`scope: "whole"`), a point in it (`t`) or a range of it (`t` to `tOut`: replace or fix just that stretch), and its `text` says what to change. Older voice notes may begin with a word such as `Speaker`, `Pacing`, `Tone`, `Fix this` or `Keep this`, from quick-start buttons the dashboard no longer has.
|
|
123
123
|
5. **Register the new cut** with `rushes_add_version`, with a short `label` and the detail in `note`. If the video is locked, the reply carries `warning: "Picture is locked at vN"`; the version is still added.
|
|
124
|
-
6. **Reply to every note** in one `rushes_reply` call. For each, set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. If you didn't fix a note, leave it `todo` and say why in `reply`.
|
|
125
|
-
7. **Audio batches.**
|
|
126
|
-
- **
|
|
127
|
-
- **Music or
|
|
124
|
+
6. **Reply to every note** in one `rushes_reply` call. For each, set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. If you didn't fix a note, leave it `todo` and say why in `reply`. Every note comes back with its `state`: `todo` (the user's, not sent yet), `sent` (in a batch the user sent: yours, and shown to them as "With your agent") or `done`. `rushes_list_notes` with `state: "sent"` lists everything you have been given and not finished, whichever batch it came in. A done note the user opens again is `todo` and goes out in their next batch.
|
|
125
|
+
7. **Audio batches.** For a note on the voice, the music, the effects or the mix (stage `mix` is the Timeline tab, where every take in use plays together), call `rushes_get_picks` first (pass the note's film as `video`: picks and levels are per film), so you know which read or variant is in use before you fix anything. It also returns `levels: { voice?, music?, sfx? }` in dB — where the user wants each sound to sit. Don't try to change these; they're set from the level on each sound's row of the Timeline tab and only tell you the balance the user has already chosen. Then fix each note:
|
|
126
|
+
- **Voice:** register a new whole read with `rushes_add_variant` (`stage: "voice"`) — a new round for a new direction (another voice, a different tone), or the current round for a small fix to a marked word. Say in `description` what changed.
|
|
127
|
+
- **Music or effects:** make the new bed or pass the text and marks ask for, and register it as in step 1.
|
|
128
128
|
|
|
129
|
-
Then reply as in step 6.
|
|
130
|
-
8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and the section goes back to draft, as any section does when you change its line: a flag has been acted on, and the user approved the old words, not the new ones, so they approve again. 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.
|
|
129
|
+
Then reply as in step 6. The mix plays one read, one bed and one effects pass per film: the one the user picked last (`use` in `rushes_get_picks`). A take you add is not in use, and is not heard, until they pick it. `rushes_get_picks` also lists every take per sound in `takes`, each with its `state`: `in-use`, `new` (arrived since the pick, waiting to be heard), `earlier` or `put-away` (the user set it aside: don't offer it again), plus `madeFor` and `stale` (made for a cut the film has replaced). Section takes are never mixed.
|
|
130
|
+
8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and the section goes back to draft, as any section does when you change its line: a flag has been acted on, and the user approved the old words, not the new ones, so they approve again. The same holds on their side: when the user changes the words or direction of an approved line, brief section or shot, it goes back to draft, so `build.ready` in `rushes_status` is only true for words the user approved as they stand. 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.
|
|
131
131
|
|
|
132
132
|
## Opening a project, and the files that go with the cut
|
|
133
133
|
|
|
134
|
-
When asked to open or review work in Rushes, call `rushes_open`, then tell the user what it brought in and what it left. Rushes looks through the project folder itself, and only inside it: it never follows a link out and never reads a file's contents. It brings in the current set of files that go with the newest cut, unpicked, so
|
|
134
|
+
When asked to open or review work in Rushes, call `rushes_open`, then tell the user what it brought in and what it left. Rushes looks through the project folder itself, and only inside it: it never follows a link out and never reads a file's contents. It brings in the current set of files that go with the newest cut, unpicked, so Voice, Music and Effects have something to review, and leaves everything else one step away in Assets › Found. At most one file per kind comes in, and only when it clearly matches the cut by length, time and name. Nothing is ever picked; the user chooses in the dashboard.
|
|
135
135
|
|
|
136
136
|
`rushes_open` returns `broughtIn` (every file Rushes has brought in since it started, so it can include files from earlier calls and ones the user brought in by hand; each has its kind, lane, reasons and `origin`: `auto` for the scoring, `include` for yours, `hand` for the user's), `alreadyIn` (your `include` files that were already registered), `failed` (files that couldn't come in, with the reason) and `found` (counts of what it left, by kind; `rushes_scan` calls the same counts `counts`). It waits about 20 seconds for the folder to be looked through. On a big folder it answers with `scanning: true` and carries on in the background; call `rushes_scan` or `rushes_open` again later for the rest. Say it plainly, for example: "I brought in `vo_jules/read.wav` as a voice read and `bed/theme.wav` as music. 14 more files are in Assets › Found."
|
|
137
137
|
|
|
@@ -139,17 +139,17 @@ Pass `include` for files you made for this cut: `include: [{ path, kind?, round?
|
|
|
139
139
|
|
|
140
140
|
`rushes_scan` (CLI `rushes scan [--film NAME] [--json]`) looks again, brings in the current set as opening does, and returns the candidates that are left, best score first, up to 200 (default 100), each with its reasons. `rushes_bring_in` (CLI `rushes bring-in <file>... [--kind K] [--round NAME] [--film NAME]`, which exits 1 if any file can't come in) brings chosen files in: voice, music and sfx as variants, video as cuts, `md`, `txt` and `pdf` as docs. It refuses any path outside the project folder, reports each file it can't bring in with the reason, and takes up to 60 files at a time and up to 12 files of each kind per call (the dashboard's **Bring in** has the same cap per click, so the tabs stay quick). Each refusal is `{ path, reason, code }`: match on `code` (`outside`, `gone`, `already`, `cap`, `link`, `folder`, `hiddenFile`, `skippedFolder`, `chooseKind`, `notAudio`, `notVideo`, `notDoc`, `unknownType`, or `other`), never on the words.
|
|
141
141
|
|
|
142
|
-
The user sees the rest in **Assets › Found**, the first folder in Assets: files grouped by folder with their reasons, a play button to audition each one, **Bring in N** (the ticked files, up to 12 of each kind per click), **Not these** (hides them for good, with a **Hidden** list and **Restore**), **Look again** (the same scan as `rushes_scan`) and
|
|
142
|
+
The user sees the rest in **Assets › Found**, the first folder in Assets: files grouped by folder with their reasons, a play button to audition each one, **Bring in N** (the ticked files, up to 12 of each kind per click), **Not these** (hides them for good, with a **Hidden** list and **Restore**), **Look again** (the same scan as `rushes_scan`) and, while something is new, a count on the Assets tab and a line such as "3 brought in · 118 more found" beside **Bring in new files** in the **More** menu. Files in Found are never an agent's to pick for the user; whatever comes in, by you or by Rushes, is unpicked.
|
|
143
143
|
|
|
144
144
|
## The Change Log
|
|
145
145
|
|
|
146
|
-
Rushes keeps a log of what happened in the project, written as it happens (`.rushes/log.json`, oldest first on disk; every view of it is newest first): cuts, formats (another shape of a cut, e.g. "9:16 added to v2"), voice reads, music beds, sound-effects passes, takes, the script, picks, picture lock and unlock, notes sent, your replies, files added and bring-ins. A burst of registrations is one line. The user
|
|
146
|
+
Rushes keeps a log of what happened in the project, written as it happens (`.rushes/log.json`, oldest first on disk; every view of it is newest first): cuts, formats (another shape of a cut, e.g. "9:16 added to v2"), voice reads, music beds, sound-effects passes, takes, the script, picks, picture lock and unlock, notes sent, your replies, files added and bring-ins. A burst of registrations is one line. The user reads it in the **Activity** tab of the notes panel.
|
|
147
147
|
|
|
148
148
|
- **At the start of a session, call `rushes_get_log`** to catch up on what changed since you last worked on the project. It takes `limit` (default 30, at most 200), `area` and `since` (a date and time). It returns `entries` newest first, `earlier` (how many it left out), `undated` (audio from before the log) and `dropped` (lines removed past 5000).
|
|
149
149
|
- **When you change direction or make a decision**, add one line with `rushes_log` (`text`, optional `area`, `video`, `version`, `ref`), e.g. "Slowed the zooms: the first cut felt rushed". One line per decision, not a running commentary, 160 characters at most. The log is exported and shared, so never copy a note's or reply's text into it. Don't log what Rushes logs itself.
|
|
150
150
|
- **Give every cut a short `label`** (step 1 of the loop).
|
|
151
151
|
- CLI: `rushes log [--limit N] [--area A] [--md]` and `rushes log add "text" [--area A]`. Flags go before the text; text that starts with a dash goes after `--`: `rushes log add --area mix -- "-3 dB on the bed"`. `rushes_export_notes` also writes `exports/change-log-<date>.md`.
|
|
152
|
-
-
|
|
152
|
+
- The prompt Send gives ends with the last five lines, under "Recent changes".
|
|
153
153
|
|
|
154
154
|
## Tools
|
|
155
155
|
|
|
@@ -158,8 +158,8 @@ The MCP server has twenty-four tools: `rushes_open`, `rushes_status`, `rushes_ad
|
|
|
158
158
|
## Rules
|
|
159
159
|
|
|
160
160
|
- Never edit `.rushes/*.json` by hand while the server is running. Use the tools, or the CLI (`rushes add`, `rushes notes`, `rushes reply`).
|
|
161
|
-
- Picks — which
|
|
162
|
-
- A project whose voiceover exists only as takes from before rounds keeps
|
|
161
|
+
- Picks — which read, bed and effects pass is in use, one of each, for each film on its own — are set from the dashboard only (**Use** / **Unpick**). No tool or CLI command sets one; read them with `rushes_get_picks`. Section take picks remain in the file format for compatibility only; nothing sets them any more.
|
|
162
|
+
- A project whose voiceover exists only as takes from before rounds keeps Voice locked until a voice read exists, but open notes on those takes still count towards Send and can be answered with `rushes_reply`.
|
|
163
163
|
- You own a note's `reply`, `fixT` and `fixVersion`. The user owns its text, times and box. Either of you can set `status`.
|
|
164
164
|
- After the first cut, send the storyboard's shots with `rushes_set_shots`; when a new cut moves them, send new timings.
|
|
165
165
|
- Lock picture with `rushes_lock_picture` only when the user says picture is locked. Pass `version: null` to unlock.
|
package/README.md
CHANGED
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
<p align="center">
|
|
24
24
|
<a href="#get-started">Get started</a> ·
|
|
25
25
|
<a href="#how-it-works">How it works</a> ·
|
|
26
|
-
<a href="#every-stage-in-one-place">The
|
|
26
|
+
<a href="#every-stage-in-one-place">The desk</a> ·
|
|
27
27
|
<a href="#your-notes-are-plain-files">Plain files</a> ·
|
|
28
28
|
<a href="#faq">FAQ</a> ·
|
|
29
29
|
<a href="#for-agents-set-yourself-up">For agents</a>
|
|
@@ -59,7 +59,7 @@ It runs on your machine. There's no account, no API key and no server to sign up
|
|
|
59
59
|
|
|
60
60
|
No project to hand? `npx -y rushes demo` builds an example on your machine and opens it.
|
|
61
61
|
|
|
62
|
-
> Status: early. The
|
|
62
|
+
> Status: early. The Plan, Review, Visuals and Assets workspaces, the MCP tools and the CLI all work today.
|
|
63
63
|
|
|
64
64
|
## How it works
|
|
65
65
|
|
|
@@ -67,78 +67,78 @@ No project to hand? `npx -y rushes demo` builds an example on your machine and o
|
|
|
67
67
|
<img src="docs/assets/loop.png" alt="The loop in four steps. One, the agent registers a cut, a script or a mix. Two, you review it in the browser and pin notes. Three, you press Send to agent and your notes go as one batch. Four, the agent fixes each note and replies on it. The next version comes back to step two until picture is locked." width="880">
|
|
68
68
|
</p>
|
|
69
69
|
|
|
70
|
-
Your agent registers what it makes. You review it in the browser. When you press **Send
|
|
70
|
+
Your agent registers what it makes. You review it in the browser. When you press **Send**, at the foot of the notes panel, your notes go as one batch, saved as plain files in your project. The agent reads the batch, fixes each note and replies on it, and you see each reply arrive.
|
|
71
71
|
|
|
72
72
|
## Every stage in one place
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
Four workspaces in the top bar, in the order the work happens; the first, Plan, has a switch for Brief, Script and Storyboard. **Review** holds the cut on the **Timeline** tab and a tab for each sound: **Voice**, **Music** and **Effects**. Then come **Visuals** and **Assets**. A tab unlocks as soon as it has something in it, and a locked tab tells you what to ask your agent for. The notes panel sits on the right, with its **Notes** and **Activity** tabs and **Send** at its foot. On Visuals and Assets, which have no notes panel, the status bar at the bottom offers **Send** while anything is waiting.
|
|
75
75
|
|
|
76
|
-
###
|
|
76
|
+
### Timeline: point at the exact frame
|
|
77
77
|
|
|
78
|
-
<img src="docs/assets/screens/picture-review.jpg" alt="The
|
|
78
|
+
<img src="docs/assets/screens/picture-review.jpg" alt="The Review workspace's Timeline tab on cut v1 of the demo film, paused at 0:03.00 on a test pattern of colour bars. A dashed box is drawn round a checker block in the lower right of the frame. The notes panel on the right lists the open notes, with the boxed note selected; under the monitor, the ruler marks each note above the Picture track and a row each for Voice, Music and Effects." width="880">
|
|
79
79
|
|
|
80
80
|
Pin a note to a moment, to a range, or to a box drawn on the frame. Grab a frame to show what you mean. Every note records the shot it falls in.
|
|
81
81
|
|
|
82
82
|
### The agent replies on every note
|
|
83
83
|
|
|
84
|
-
<img src="docs/assets/screens/picture-fixed.jpg" alt="The
|
|
84
|
+
<img src="docs/assets/screens/picture-fixed.jpg" alt="The Timeline tab on cut v2, the hue pass of the same test pattern. In the notes panel the note about the checker block, carried over from v1 at 0:03.00, has a green tick and the agent's reply under it: v2 is a hue pass, and the block and the bars shift together now." width="880">
|
|
85
85
|
|
|
86
86
|
When the agent delivers a new cut, each note shows where it landed in the new version and what the agent did about it. A green tick means it's done. Anything the agent didn't fix stays open, with a reason.
|
|
87
87
|
|
|
88
|
-
###
|
|
88
|
+
### Plan: the brief, the script and the storyboard
|
|
89
89
|
|
|
90
|
-
<img src="docs/assets/screens/script-review.jpg" alt="The Script
|
|
90
|
+
<img src="docs/assets/screens/script-review.jpg" alt="The Script page in the Plan workspace, with the Brief, Script and Storyboard switch above it. Each of the four lines sits in a field with its timing and a fit bar. The second line is marked Edited by you, with the agent's wording struck through beneath it and the direction 'Two short sentences. Easier to say.'; the third has a direction of its own. The foot reads 0 of 4 lines approved, 1 edited, and the status bar says Next: send 7 changes." width="880">
|
|
91
91
|
|
|
92
|
-
Rewrite a line, add a direction, flag it or approve it. The bar on each row shows whether the line still fits its slot. When the agent adopts your edit, it records the next voice read from the corrected script.
|
|
92
|
+
Rewrite a line, add a direction, flag it or approve it. Every line sits in a field; once you change one, its row says **Edited by you**, with the agent's wording struck through beneath it and a button to go back to it, and the change goes with your next **Send**. The bar on each row shows whether the line still fits its slot. When the agent adopts your edit, it records the next voice read from the corrected script.
|
|
93
93
|
|
|
94
|
-
|
|
94
|
+
Plan is one workspace, so planning never crowds the review. A switch at its top opens **Brief**, **Script** and **Storyboard**, each with a tick once it is approved and a dot while it has edits you haven't sent; key `1` comes back to the page you used last. **Brief** shows `brief.md` in your project folder, one field per section. Edit a section and Rushes writes it into the file; press **Approve brief** and it sets the file's status line. If your agent rewrites `brief.md`, the page follows without a reload. **Storyboard** works the same way over `storyboard.md`: a row per shot with its still (click it to enlarge), its description, a direction line and a tick to approve it. A line at the foot of each page counts what is approved and what you have edited. When the brief, every script line (if the film has a script) and every shot are approved, the Plan tab in the top bar shows a green check and the row above the page says **Ready to build**, with a prompt to copy. Rushes never stops your agent building before then: it only says what is still waiting.
|
|
95
95
|
|
|
96
|
-
###
|
|
96
|
+
### Voice: compare reads, round by round
|
|
97
97
|
|
|
98
|
-
<img src="docs/assets/screens/voiceover.jpg" alt="The
|
|
98
|
+
<img src="docs/assets/screens/voiceover.jpg" alt="The Voice tab. Under the monitor, Round 2's read, Voice A slower, is In use, and Earlier lists Round 1's two reads, Voice A and Voice B, each with its waveform and description. In the notes panel, the note on Round 1's Voice A has a green tick and the agent's reply: Round 2 is Voice A at a slower pace." width="880">
|
|
99
99
|
|
|
100
|
-
Reads of the same script sit side by side in rounds. Switch between them with no gap in playback, or turn on **Blind** to hide which is which. Leave a note on a whole read, or at a point in it.
|
|
100
|
+
Reads of the same script sit side by side in rounds. Switch between them with no gap in playback, or turn on **Blind** to hide which is which. Leave a note on a whole read, or at a point in it. Each sound's tab lists its takes as **New**, **In use**, **Earlier** and **Put away**; a take isn't on the timeline until you pick it.
|
|
101
101
|
|
|
102
102
|
### Music: audition the beds
|
|
103
103
|
|
|
104
|
-
<img src="docs/assets/screens/music.jpg" alt="The Music tab with
|
|
104
|
+
<img src="docs/assets/screens/music.jpg" alt="The Music tab with two beds, each with its waveform: Warm pad is In use, Pulse is listed under Earlier. Two open notes are marked on the waveforms and listed in the notes panel: a point on Pulse at 0:02 and a 'Fall' range on Warm pad from 0:06 to 0:09." width="880">
|
|
105
105
|
|
|
106
106
|
Switch beds instantly while the picture plays. Mark a range as **Rise**, **Fall**, **Louder** or **Quieter**, and your agent gets it as a note it can act on.
|
|
107
107
|
|
|
108
108
|
### Visuals: mark up stills and carousels
|
|
109
109
|
|
|
110
|
-
The **Visuals**
|
|
110
|
+
The **Visuals** workspace (key `7`) is for the stills, standalone images and carousels your agent makes next to a video. Each is a visual: one post, in the aspect ratios it comes in, shown one page at a time in a large frame. It scrolls from one visual to the next, and whichever visual crosses the middle of the view is the current one: it gets the outline, and it is the only one you can add a note to. A carousel has Previous and Next, a count, **Full screen** (for looking closely; you mark in the workspace) and a strip of its pages with the open notes on each.
|
|
111
111
|
|
|
112
|
-
**Drag** on the picture to mark a region, click to drop a point, or press **Whole image** for a note about all of it. The composer always says where the note will go ("Adding to: Launch carousel · page 3 · 4:5 · v2"), and a draft stays with the visual you began it on. Notes belong to a page, a ratio and a version, never to where you have scrolled, so every mark is still there when you come back. The notes column lists the whole
|
|
112
|
+
**Drag** on the picture to mark a region, click to drop a point, or press **Whole image** for a note about all of it. The composer always says where the note will go ("Adding to: Launch carousel · page 3 · 4:5 · v2"), and a draft stays with the visual you began it on. Notes belong to a page, a ratio and a version, never to where you have scrolled, so every mark is still there when you come back. The notes column lists the whole workspace, grouped by visual and page, with the visual you are looking at highlighted and the rest faded; click a note to jump to it. When your agent registers a new version, your old notes stay with the version they were made on ("from v1"), marked until you tick them done.
|
|
113
113
|
|
|
114
114
|
### Shelve a film
|
|
115
115
|
|
|
116
|
-
A film that went nowhere can be set aside without losing it. Open the
|
|
116
|
+
A film that went nowhere can be set aside without losing it. Open the **More** menu (**⋯**, at the right of the top bar) and choose **Shelve film**, or press **Shift+S**. The film leaves the **Film** menu's films in play, a toast offers **Undo**, and its open notes stop counting: they leave the Send count, the tab to-do counts, batches and Export notes, and they come back when you restore the film. Nothing is deleted: its cuts, notes, picks and files stay as they were.
|
|
117
117
|
|
|
118
|
-
|
|
118
|
+
The **Film** menu in the top bar switches films, each listed with its open notes. **Shelved (N)** at its foot lists the shelved films: choose one to look at it, view-only, under a "Shelved" banner, and **Restore** it from the menu or the banner. A new cut from your agent also brings a shelved film back. Your agent can see which films are shelved, but never shelves or restores one.
|
|
119
119
|
|
|
120
|
-
###
|
|
120
|
+
### Effects: layers by sound
|
|
121
121
|
|
|
122
|
-
<img src="docs/assets/screens/sound-effects.jpg" alt="The
|
|
122
|
+
<img src="docs/assets/screens/sound-effects.jpg" alt="The Effects tab with the pass in use, Pass A, open into its layers: one row per sound (Whoosh 1, Whoosh 2 and Whoosh 3), each with a count and a mark where it plays, under the pass's waveform with its three cues labelled." width="880">
|
|
123
123
|
|
|
124
124
|
Every cue is labelled on the waveform. Open the pass into **layers by sound**: one row per sound, with a count, and a tick wherever it plays. Click a layer's file to hear that sample on its own.
|
|
125
125
|
|
|
126
|
-
###
|
|
126
|
+
### Everything together on the Timeline
|
|
127
127
|
|
|
128
|
-
<img src="docs/assets/screens/
|
|
128
|
+
<img src="docs/assets/screens/timeline-sound.jpg" alt="The Timeline tab with a take in use for each sound: rows for Voice, Music and Effects under the Picture track, each with its take's waveform, mute (M) and solo (S) buttons and a level, the music at -12 dB. The transport above them reads the loudness of what you hear: -18.8 LUFS, the true peak in dBTP and the music 6 dB under the voice." width="880">
|
|
129
129
|
|
|
130
|
-
|
|
130
|
+
There is no separate mix: the takes in use play together against the picture on the **Timeline** tab. Each sound has its own row there with mute (**M**), solo (**S**) and a level, and the tab reads the loudness and true peak (with ffmpeg installed).
|
|
131
131
|
|
|
132
|
-
###
|
|
132
|
+
### Activity: the Change Log
|
|
133
133
|
|
|
134
|
-
<img src="docs/assets/screens/
|
|
134
|
+
<img src="docs/assets/screens/activity.jpg" alt="The notes panel's Activity tab beside the Timeline: an 'Add a line to the log' box, filters by area (All, Picture, Voice, Music, Effects, Mix, Visuals, Notes, Files), and today's entries newest first: the agent's replies to two notes, the picks for the film, and the two cuts added, each marked as by the agent or by Rushes, with Export as Markdown at the foot." width="880">
|
|
135
135
|
|
|
136
|
-
Rushes keeps a running log of what happened: each cut, read, bed and pass as it arrives, notes sent, and the agent's replies. Export it as Markdown for whoever needs to catch up.
|
|
136
|
+
Rushes keeps a running log of what happened, in the **Activity** tab of the notes panel: each cut, read, bed and pass as it arrives, notes sent, and the agent's replies. Export it as Markdown for whoever needs to catch up.
|
|
137
137
|
|
|
138
138
|
## Why Rushes
|
|
139
139
|
|
|
140
140
|
- **Notes your agent can act on.** Each one carries its stage, a timecode or range, an optional box on the frame, a frame grab, and the shot it falls in.
|
|
141
|
-
- **Everything in one batch.** **Send
|
|
141
|
+
- **Everything in one batch.** **Send** sends every open note from every tab and every film, wherever you press it, so nothing waits behind.
|
|
142
142
|
- **Versions keep their history.** Notes follow the work from cut to cut, and you can lock picture when it's done.
|
|
143
143
|
- **Local, with no sign-up.** No account, no API key, nothing uploaded. It runs on your machine.
|
|
144
144
|
- **Works with the agent you already use.** One MCP server for Claude Code, Codex, Cursor, Claude Desktop and Gemini CLI, a plugin and skill for Claude Code, and a command line for anything else.
|
|
@@ -160,7 +160,7 @@ Rushes keeps your review in a `.rushes/` folder in the project. The agent reads
|
|
|
160
160
|
|
|
161
161
|
**Can I use it without an agent?** Yes. Review, leave notes, and run **Export notes** for a dated Markdown file you can send to a person. The agent loop is where it pays off most.
|
|
162
162
|
|
|
163
|
-
**Does it need ffmpeg?** No, but it helps. With ffmpeg installed Rushes reads frame rates and durations, makes browser-playable proxies of heavy cuts, and measures loudness on
|
|
163
|
+
**Does it need ffmpeg?** No, but it helps. With ffmpeg installed Rushes reads frame rates and durations, makes browser-playable proxies of heavy cuts, and measures loudness on the Timeline tab. Run `rushes doctor` to check.
|
|
164
164
|
|
|
165
165
|
**Can it handle big files?** Cuts that play badly in a browser (4K and above, huge files, ProRes and similar) get an offer of a light 1080p proxy. Your original is never changed. See [Proxies](#proxies).
|
|
166
166
|
|
|
@@ -184,7 +184,7 @@ If your user asked you to use Rushes, do this:
|
|
|
184
184
|
|
|
185
185
|
It prints one line per harness. Existing config is kept and a `.rushes.bak` backup is written first. Run it with `--dry-run` first if you want to show the user the changes before making them. A machine already set up through the GitHub form is recognised as Rushes too — setup switches it to the npm launch instead of adding a second registration.
|
|
186
186
|
2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
|
|
187
|
-
3. From then on, follow [AGENTS.md](AGENTS.md). If the user wants a new film, start with **Starting a film** in AGENTS.md: plan it with them first, then build. Otherwise, in short: register what you made, call `rushes_open`, wait for the user to press **Send
|
|
187
|
+
3. From then on, follow [AGENTS.md](AGENTS.md). If the user wants a new film, start with **Starting a film** in AGENTS.md: plan it with them first, then build. Otherwise, in short: register what you made, call `rushes_open`, wait for the user to press **Send**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
|
|
188
188
|
|
|
189
189
|
The MCP server has twenty-four tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_visual`, `rushes_add_variant`, `rushes_set_films`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_log`, `rushes_get_log`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor`.
|
|
190
190
|
|
|
@@ -237,7 +237,7 @@ No project to hand? Build one:
|
|
|
237
237
|
npx -y rushes demo # creates ./rushes-demo and opens it
|
|
238
238
|
```
|
|
239
239
|
|
|
240
|
-
It generates a complete example on your machine — a 30 s test film in two cuts, a short script, voice reads in two rounds, two music beds, an SFX pass, and example notes on
|
|
240
|
+
It generates a complete example on your machine — a 30 s test film in two cuts, a short script, voice reads in two rounds, two music beds, an SFX pass, and example notes on the cut, the voice reads, the music and the mix — so every tab has something in it from the start. Nothing is downloaded and nothing ships with Rushes; it's all made locally with ffmpeg and, where available, your system's text-to-speech. It needs ffmpeg — without it, `demo` says so and points you at `rushes doctor`. It refuses to write into a folder that isn't empty. Pass a folder name to put it somewhere else, and `--no-browser` to skip opening it.
|
|
241
241
|
|
|
242
242
|
### Health check: `rushes doctor`
|
|
243
243
|
|
|
@@ -250,7 +250,7 @@ Each check prints ✓ or ✗ with a plain fix, e.g. `✗ Claude Code — the Rus
|
|
|
250
250
|
|
|
251
251
|
## Shortcuts
|
|
252
252
|
|
|
253
|
-
|
|
253
|
+
On the Timeline tab:
|
|
254
254
|
|
|
255
255
|
- **Space** play or pause
|
|
256
256
|
- **←/→** step one frame (Shift: ten)
|
|
@@ -258,8 +258,10 @@ In the Picture tab:
|
|
|
258
258
|
- **B** draw a box
|
|
259
259
|
- **G** grab a frame
|
|
260
260
|
- **N** new note
|
|
261
|
+
- **V** the select tool
|
|
262
|
+
- **F** full screen
|
|
261
263
|
|
|
262
|
-
|
|
264
|
+
On the Voice, Music and Effects tabs:
|
|
263
265
|
|
|
264
266
|
- **Space** play or pause
|
|
265
267
|
- **←/→** step one frame (Shift: ten)
|
|
@@ -269,10 +271,11 @@ In the Voiceover, Music, Sound effects and Mix tabs:
|
|
|
269
271
|
|
|
270
272
|
Anywhere:
|
|
271
273
|
|
|
272
|
-
- **1–8** switch
|
|
274
|
+
- **1–8** switch place (1: Plan, which opens the page you used last; 2 and 6: Timeline; 3, 4, 5: Voice, Music, Effects; 7: Visuals; 8: Assets)
|
|
275
|
+
- **\\** hide or show the notes panel
|
|
273
276
|
- **[ / ]** previous/next film in play
|
|
274
277
|
- **Shift+S** shelve the current film, or restore it if it is shelved
|
|
275
|
-
- **Alt+←/→** previous/next format (
|
|
278
|
+
- **Alt+←/→** previous/next format (Timeline)
|
|
276
279
|
- **?** shortcuts
|
|
277
280
|
- **Esc** close
|
|
278
281
|
|
|
@@ -282,13 +285,13 @@ Every tab is visible from the start, in workflow order, even before there's anyt
|
|
|
282
285
|
|
|
283
286
|
> In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
|
|
284
287
|
|
|
285
|
-
When the project's folder already holds files for a locked
|
|
288
|
+
When the project's folder already holds files for a locked Voice, Music or Effects tab, its page also says how many were found and offers a **Review** button, such as "14 music files found in this project". See **Finding your other files**, below.
|
|
286
289
|
|
|
287
|
-
Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets
|
|
290
|
+
Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets workspace follows the same rule.
|
|
288
291
|
|
|
289
292
|
## The Change Log
|
|
290
293
|
|
|
291
|
-
The **
|
|
294
|
+
The **Activity** tab of the notes panel (what was the Change Log button) is a log of what happened, newest first and grouped by day:
|
|
292
295
|
|
|
293
296
|
- each cut, format (another shape of a cut: "9:16 added to v2"), voice read, music bed, sound-effects pass and take as it arrives;
|
|
294
297
|
- the script, picks and notes sent;
|
|
@@ -300,9 +303,9 @@ Rushes writes it itself, one short line per event, and a burst of registrations
|
|
|
300
303
|
- filter by tab;
|
|
301
304
|
- click a line to open that cut or variant.
|
|
302
305
|
|
|
303
|
-
A dot on the
|
|
306
|
+
A dot on the Activity tab means new lines since you last looked. **Export as Markdown** writes `exports/change-log-<date>.md`; **Export notes** (in the More menu, or in Assets › Exports) writes it too, beside the notes. A project made before the log existed starts it from the dates it already has (cuts, notes sent and files); its older audio is listed undated, under "Before the log".
|
|
304
307
|
|
|
305
|
-
|
|
308
|
+
The Cut menu's version list shows each cut's short label (the agent's, or one taken from its note) and how long ago it arrived, with its full note beside the list.
|
|
306
309
|
|
|
307
310
|
Agents read and write the same log with `rushes_get_log` and `rushes_log`, or from the command line:
|
|
308
311
|
|
|
@@ -322,7 +325,7 @@ An agent only shows what it registers, but the work that goes with a cut usually
|
|
|
322
325
|
- **Where.** Only inside the project folder, up to eight folders deep. It never follows a symlink out of it, never reads a file's contents, and skips hidden folders, `node_modules` and Rushes' own `.rushes`, `proxies`, `screenshots` and `exports`. It examines up to 5,000 files. The dashboard never waits for it: a big folder shows "Looking through the folder…" and fills in as it goes.
|
|
323
326
|
- **What each file probably is.** The nearest folder or file-name word decides: `vo`, `voice`, `narration` for voiceover; `bed`, `music`, `score` for music; `sfx`, `foley`, `whoosh` for sound effects. Audio with no such word is "Other audio", and you choose its kind. Video files other than the registered cut are offered as other cuts.
|
|
324
327
|
- **The current set.** Each audio file is scored against the cut: a similar length, being made around the same time, and sharing a word or version (such as `v20`) with its name. For each kind, the best file comes in on its own only when it clearly beats the rest. That's at most one voice read, one music bed and one sound effects pass, and nothing else. Nothing is ever picked: files come in unpicked, and you choose in the dashboard. Each one carries its reasons, in plain words.
|
|
325
|
-
- **Assets › Found.** Everything else stays one step away, in the **Found** folder at the top of Assets. Files are grouped by folder, with their length, size and reasons, and you can play one before you bring it in.
|
|
328
|
+
- **Assets › Found.** Everything else stays one step away, in the **Found** folder at the top of Assets. Files are grouped by folder, with their length, size and reasons, and you can play one before you bring it in. The Assets tab in the top bar carries the count of files found until you've looked, and **Bring in new files** in the More menu opens it.
|
|
326
329
|
- **Bring in** registers the ticked files: voiceover, music and sound effects as variants, and video as cuts. It takes up to 12 files of each kind at a time, so the tabs stay quick; each voiceover folder becomes its own round.
|
|
327
330
|
- **Not these** hides the ticked files for good. A **Hidden** list brings them back with **Restore**.
|
|
328
331
|
- **Look again** runs the scan once more, and a filter box and kind buttons narrow the list.
|
|
@@ -365,39 +368,40 @@ Rushes creates `screenshots/` itself on the first grab. It never creates the oth
|
|
|
365
368
|
|
|
366
369
|
## Packs, picture lock and shots
|
|
367
370
|
|
|
368
|
-
A project with more than one film gets
|
|
371
|
+
A project with more than one film gets a **Film** menu in the top bar — `[`/`]` switch between the films in play, and each film remembers its own version and playhead. The **Cut** menu beside it lists the film's cuts, with **Lock picture** at its foot: lock a film at a cut and the dashboard opens on that cut until you unlock it. A version can carry a shot list from the storyboard, shown on the timeline's picture row, and every note on the cut records the shot it falls in.
|
|
369
372
|
|
|
370
373
|
## Formats
|
|
371
374
|
|
|
372
|
-
A piece often ships in several shapes — 9:16, 4:5, 1:1, 16:9 — the same edit reframed. Your agent registers each shape with `rushes_add_format` (or all of them at once with `rushes_add_version`'s `formats`, or `rushes add format <file>` from the command line); Rushes measures each ratio itself.
|
|
375
|
+
A piece often ships in several shapes — 9:16, 4:5, 1:1, 16:9 — the same edit reframed. Your agent registers each shape with `rushes_add_format` (or all of them at once with `rushes_add_version`'s `formats`, or `rushes add format <file>` from the command line); Rushes measures each ratio itself. The monitor then shows a switch, always in the same order (9:16, 4:5, 1:1, 4:3, 16:9), with a count of open notes on each. Switching keeps your place and whether it's playing. **Alt+←/→** steps through them.
|
|
373
376
|
|
|
374
377
|
A new note belongs to the format on screen: the switch above the note box reads **This format** | **All formats**, and you can change it on the note afterwards. A note for one format shows only there; notes for the other formats wait in a quiet **Other formats** row at the foot of the list. A drawn box always stays on the format it was drawn on. With one format there's no switch, and nothing changes. Assets › Cuts lists each format under its cut, and a frame grab is named with its ratio, such as `hero_v1_9x16_00m01.00s_f30.png`.
|
|
375
378
|
|
|
376
379
|
A format's file can sit outside the project folder, like any registered cut, and plays by the same rules. A second render of a shape the cut already has is refused: a re-render is a new version.
|
|
377
380
|
|
|
378
|
-
The format keys never fire while you're typing a note. In a text field, Alt+←/→ keeps its usual meaning: on macOS it jumps a word, and on Windows and Linux the browser may take it as Back, so click outside the note box first (or use the
|
|
381
|
+
The format keys never fire while you're typing a note. In a text field, Alt+←/→ keeps its usual meaning: on macOS it jumps a word, and on Windows and Linux the browser may take it as Back, so click outside the note box first (or use the switch on the monitor) to switch format.
|
|
379
382
|
|
|
380
383
|
## Proxies
|
|
381
384
|
|
|
382
385
|
Some cuts play badly in a browser: 4K or larger, over 1.5 GB, a codec browsers can't play reliably (ProRes, DNx, HEVC 10-bit — anything that isn't H.264, VP9 or AV1), or one that threw a playback error. Rushes checks with ffprobe as the cut is added, and if it's likely to struggle, a bar appears under the player saying why in a few words, with a **Create proxy** button. It makes a lightweight 1080p H.264 copy on your drive — your original file is never changed — with visible progress and **Cancel**. Notes, timecodes and frame numbers are identical on the proxy and the original.
|
|
383
386
|
|
|
384
|
-
Once it's ready, a **Proxy / Original** switch appears on the player (defaults to Proxy, remembered per film). **Grab
|
|
387
|
+
Once it's ready, a **Proxy / Original** switch appears on the player (defaults to Proxy, remembered per film). **Grab this frame** (**G**) always takes the still from the original at full quality, whichever one you're watching. Turn on **Make lighter copies of new cuts automatically** in the More menu (off by default, saved per project) to skip the offer next time. The **Assets** tab has a **Proxies** folder listing each one with its size and a **Delete proxy** button; deleting removes only the proxy file, never the original.
|
|
385
388
|
|
|
386
389
|
Without ffmpeg, no proxy is ever offered.
|
|
387
390
|
|
|
388
391
|
## Audio review
|
|
389
392
|
|
|
390
|
-
|
|
393
|
+
On the Timeline, Voice, Music and Effects tabs, switching what you hear is instant and never restarts playback or knocks picture out of sync.
|
|
391
394
|
|
|
392
|
-
|
|
395
|
+
Voice works in rounds: the same script read by a few voices, then variations of whichever one you pick. Each sound's tab lists its takes in four groups: **New** (on Voice, a heading per round), **In use**, **Earlier** and **Put away**.
|
|
393
396
|
|
|
394
|
-
- **Use** picks a music bed, SFX pass or voice read
|
|
395
|
-
- **Blind** (
|
|
396
|
-
- On
|
|
397
|
-
- On
|
|
398
|
-
-
|
|
399
|
-
-
|
|
400
|
-
-
|
|
397
|
+
- The circle beside a take (**Use this one**) picks a music bed, SFX pass or voice read, which then shows as **In use** and plays on the Timeline tab. Clicking a take's block auditions it without changing the pick. **Unpick** on the take in use clears the pick, and **Put away** moves a take you don't want out of the list's way (**Bring back** returns it).
|
|
398
|
+
- **Blind** (Voice and Music) renames the beds `Bed 1`, `Bed 2`… — on Voice, each round's reads `Read 1`, `Read 2`… — in a shuffled order and masks their descriptions, so you can compare without knowing which is which.
|
|
399
|
+
- On Voice, a note is on the whole read, a point (marked at the playhead) or a **range** of the read (I and O), to have a stretch replaced. There are no Rise/Fall/Louder/Quieter marks there. Say what you want in the note itself: there are no preset prompts.
|
|
400
|
+
- On the Timeline tab a note is on the film (this frame, or the whole mix), never on one sound's take: to note a take, open its sound's tab.
|
|
401
|
+
- On a range of a music bed or an effects pass, a note can carry marks: toggle **Rise**, **Fall**, **Louder** or **Quieter** (with a dB amount, 3 by default) to say how a range should change — "Fall" or "Quieter 3 dB".
|
|
402
|
+
- The **Timeline** tab shows a loudness readout — integrated LUFS, true peak, and the music's level under the VO — measured over exactly what the timeline plays, using the newest round's picked voice read. It needs **ffmpeg** on your PATH; without it, the readout shows "—". After a timeout or an error, click the readout to measure again.
|
|
403
|
+
- Each sound's row on the Timeline tab (Voice, Music, Effects) has mute (**M**), solo (**S**) and a level slider, −24 dB to +6 dB in 0.5 dB steps, shown as e.g. `−14.0 dB`. Double-click resets it to 0; arrow keys move it 0.5 dB at a time. Levels are saved with your picks, never change a file, and the loudness readout is measured with them applied.
|
|
404
|
+
- On **Effects**, rest the pointer on a cue's label or tick (or Tab to it) for a card with its full name, its time, where it falls in the pass (`cue 5 of 80`) and, when your agent sent one, its source file. The arrow beside a pass's name opens its **layers by sound**: one row per sound, in the order it first comes in, with a count (`thud ×19`) and a tick everywhere it plays. Click a tick to move the playhead there; click a layer's file name to hear that sample on its own (it stops the tab, and Play stops it). The layers stay open while you work, until you reload. The Effects row on the Timeline tab has the card too.
|
|
401
405
|
|
|
402
406
|
## What gets saved
|
|
403
407
|
|
|
@@ -406,9 +410,9 @@ your-project/.rushes/
|
|
|
406
410
|
project.json videos, versions, audio lanes and variants
|
|
407
411
|
script.json VO sections: the agent's line, your version, direction, takes
|
|
408
412
|
notes.json every note, with the agent's replies
|
|
409
|
-
picks.json which variant or take is in use, and each
|
|
413
|
+
picks.json which variant or take is in use, and each sound's level
|
|
410
414
|
batches.json what you sent to the agent
|
|
411
|
-
log.json the Change Log: what happened, one line each
|
|
415
|
+
log.json the Change Log (the Activity tab): what happened, one line each
|
|
412
416
|
```
|
|
413
417
|
|
|
414
418
|
Add `.rushes/` to git if you want your review history kept with the project — and `screenshots/` alongside it, since notes point to the grabs there. Keep `proxies/` out of git: proxies can run to gigabytes, and Rushes can always make them again. Rushes ignores its own temporary files.
|