rushes 0.2.1 → 0.3.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.
- package/.claude-plugin/plugin.json +1 -1
- package/AGENTS.md +36 -8
- package/README.md +75 -4
- package/dist/cli/doctor.js +35 -10
- package/dist/cli/main.js +200 -18
- package/dist/core/batches.js +35 -3
- package/dist/core/exportNotes.js +9 -5
- package/dist/core/formats.js +159 -0
- package/dist/core/found.js +333 -0
- package/dist/core/labels.js +192 -0
- package/dist/core/log.js +190 -0
- package/dist/core/logEvents.js +193 -0
- package/dist/core/logText.js +122 -0
- package/dist/core/media.js +119 -13
- package/dist/core/notes.js +35 -4
- package/dist/core/project.js +69 -1
- package/dist/core/schema.js +147 -1
- package/dist/core/store.js +19 -3
- package/dist/mcp/client.js +13 -1
- package/dist/mcp/tools.js +181 -11
- package/dist/server/app.js +495 -38
- package/dist/server/assets.js +19 -7
- package/dist/server/files.js +61 -4
- package/dist/server/found.js +1216 -0
- package/dist/server/logbook.js +208 -0
- package/dist/server/loudness.js +7 -3
- package/dist/server/peaks.js +3 -2
- package/dist/server/proxy.js +16 -4
- package/dist/server/start.js +15 -2
- package/package.json +1 -1
- package/skills/rushes/SKILL.md +9 -4
- package/web-dist/assets/index-BDMm5p1-.css +1 -0
- package/web-dist/assets/index-C9dBtlRy.js +3 -0
- package/web-dist/index.html +2 -2
- package/web-dist/assets/index-ChXjhVC5.js +0 -3
- package/web-dist/assets/index-Cj_tr1I-.css +0 -1
|
@@ -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.3.0",
|
|
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
|
@@ -45,7 +45,7 @@ Everything else, register with `rushes_add_file` (`kind`, `file`, optional `name
|
|
|
45
45
|
|
|
46
46
|
The CLI equivalent is `rushes add file <path> --kind K [--name N] [--note T] [--video V]`.
|
|
47
47
|
|
|
48
|
-
When the user wants to share notes with someone else, call `rushes_export_notes` (CLI: `rushes export notes`). It writes every note, grouped by stage and, for Picture, by film and version, to a dated Markdown file in `exports/`, and returns
|
|
48
|
+
When the user wants to share notes with someone else, call `rushes_export_notes` (CLI: `rushes export notes`). It writes every note, grouped by stage and, for Picture, by film and version, to a dated Markdown file in `exports/`, writes the Change Log beside it as `exports/change-log-<date>.md`, and returns both paths.
|
|
49
49
|
|
|
50
50
|
## A demo project
|
|
51
51
|
|
|
@@ -53,22 +53,23 @@ No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `ru
|
|
|
53
53
|
|
|
54
54
|
## Locked tabs and the prompts they copy
|
|
55
55
|
|
|
56
|
-
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. 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.:
|
|
56
|
+
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 Voiceover, Music or Sound 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.:
|
|
57
57
|
|
|
58
58
|
> 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.
|
|
59
59
|
|
|
60
60
|
## The loop
|
|
61
61
|
|
|
62
62
|
1. **Register what you made.**
|
|
63
|
-
- A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. 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`; Picture then offers the user a proxy. Prefer H.264 MP4 to begin with and this won't come up.
|
|
63
|
+
- 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`: the 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`; Picture then offers the user a proxy. Prefer H.264 MP4 to begin with and this won't come up.
|
|
64
|
+
- 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").
|
|
64
65
|
- 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.
|
|
65
66
|
- A voice read: `rushes_add_variant` with `stage: "voice"` 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.
|
|
66
67
|
- Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`. Give it `meta: {description: "..."}`, shown on its lane card in place of `bpm`/`key`; SFX passes also take `cues` (`{name, t}` in seconds), labelled on the waveform.
|
|
67
68
|
- 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.
|
|
68
|
-
2. **Open it for the user:** `rushes_open`. 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.
|
|
69
|
+
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.
|
|
69
70
|
3. **Wait for feedback.** The user presses **Send to agent**, which saves a batch and gives them a prompt to paste to you. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections.
|
|
70
|
-
4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — Voiceover only ever uses `point` or `whole`; it has no Range scope), `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/`)
|
|
71
|
-
5. **Register the new cut** with `rushes_add_version` and
|
|
71
|
+
4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — Voiceover only ever uses `point` or `whole`; it has no Range scope), `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) — on Voiceover 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 Mix it's `null` for the whole mix, `"vo"` for the VO lane (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or SFX lane. Older notes may carry a bare variant id, `"vo"` on Voiceover 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. On Music, Sound effects and Mix, a 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. Voiceover notes carry no marks: a note there is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — about the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead).
|
|
72
|
+
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.
|
|
72
73
|
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`.
|
|
73
74
|
7. **Audio batches.** On Voiceover, Music, Sound effects or Mix, call `rushes_get_picks` first, so you know which read or variant is in use before you fix anything. On Mix, it also returns `levels: { voice?, music?, sfx? }` in dB — where the user wants each lane to sit. Don't try to change these; they're set from the dashboard's sliders and only tell you the balance the user has already chosen. Then fix each note:
|
|
74
75
|
- **Voiceover:** 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.
|
|
@@ -77,9 +78,31 @@ Every tab is visible from the start, in workflow order, even before it has anyth
|
|
|
77
78
|
Then reply as in step 6. Mix plays the newest round's picked voice read; takes are never mixed.
|
|
78
79
|
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 a flagged section goes back to draft. 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.
|
|
79
80
|
|
|
81
|
+
## Opening a project, and the files that go with the cut
|
|
82
|
+
|
|
83
|
+
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 Voiceover, Music and Sound 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.
|
|
84
|
+
|
|
85
|
+
`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."
|
|
86
|
+
|
|
87
|
+
Pass `include` for files you made for this cut: `include: [{ path, kind?, round? }]`. They come in whatever they score, and they win over the scoring: a kind you include (voice, music or sfx) isn't also guessed for that cut, on any later scan or restart (Rushes keeps this in `.rushes/found.json`). A newer cut is a fresh decision, and nothing already registered is ever removed. One narrow case: if Rushes had just started and had already brought in its own pick before your call arrived, both are in, unpicked. Give `kind` (`voice`, `music`, `sfx`, `cut` or `doc`) when the name doesn't say, and `round` for a voice read. `rushes_open` also takes `film`, to match the files to a film other than the newest cut's. If the scoring picked the wrong file, bring the right one in with `include` (or `rushes_bring_in`) and say which.
|
|
88
|
+
|
|
89
|
+
`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.
|
|
90
|
+
|
|
91
|
+
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 a header chip, "3 brought in · 118 more found", while something is new. Files in Found are never an agent's to pick for the user; whatever comes in, by you or by Rushes, is unpicked.
|
|
92
|
+
|
|
93
|
+
## The Change Log
|
|
94
|
+
|
|
95
|
+
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 opens it from the **Change Log** button.
|
|
96
|
+
|
|
97
|
+
- **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).
|
|
98
|
+
- **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.
|
|
99
|
+
- **Give every cut a short `label`** (step 1 of the loop).
|
|
100
|
+
- 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`.
|
|
101
|
+
- Send to agent's prompt ends with the last five lines, under "Recent changes".
|
|
102
|
+
|
|
80
103
|
## Tools
|
|
81
104
|
|
|
82
|
-
The MCP server has
|
|
105
|
+
The MCP server has twenty-two tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_variant`, `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`. Each takes an optional `project` folder, which defaults to the folder the harness started in.
|
|
83
106
|
|
|
84
107
|
## Rules
|
|
85
108
|
|
|
@@ -97,14 +120,19 @@ The MCP server has seventeen tools: `rushes_open`, `rushes_status`, `rushes_add_
|
|
|
97
120
|
|
|
98
121
|
```bash
|
|
99
122
|
npx -y rushes open
|
|
100
|
-
npx -y rushes add version renders/hero_v2.mp4 --video "Hero 60s" --
|
|
123
|
+
npx -y rushes add version renders/hero_v2.mp4 --video "Hero 60s" --label "logo hold" --note "held the logo 0.5 s longer"
|
|
124
|
+
npx -y rushes add format renders/hero_v2_9x16.mp4 --video "Hero 60s"
|
|
101
125
|
npx -y rushes notes --stage picture --status todo --json
|
|
102
126
|
npx -y rushes reply n_8f2k3a "Held the phone 0.5 s longer" --done --fix-t 12.9 --fix-version v2
|
|
103
127
|
npx -y rushes add variant voice gerald.wav --name Gerald --round "Round 1 · Voices"
|
|
104
128
|
npx -y rushes add shots shots.json --video "Hero 60s" --version v2
|
|
105
129
|
npx -y rushes add file brief.pdf --kind doc
|
|
106
130
|
npx -y rushes export notes
|
|
131
|
+
npx -y rushes log --limit 20
|
|
132
|
+
npx -y rushes log add "Slowed the zooms" --area picture
|
|
107
133
|
npx -y rushes doctor --json
|
|
134
|
+
npx -y rushes scan --json
|
|
135
|
+
npx -y rushes bring-in audio/music/bed.wav --kind music
|
|
108
136
|
```
|
|
109
137
|
|
|
110
138
|
`shots.json` is a JSON array of `{name, start, tag?}`, or that array wrapped as `{"shots": [...]}`.
|
package/README.md
CHANGED
|
@@ -40,7 +40,7 @@ If your user asked you to use Rushes, do this:
|
|
|
40
40
|
2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
|
|
41
41
|
3. From then on, follow [AGENTS.md](AGENTS.md). In short: register what you made, call `rushes_open`, wait for the user to press **Send to agent**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
|
|
42
42
|
|
|
43
|
-
The MCP server has
|
|
43
|
+
The MCP server has twenty-two tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_variant`, `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`.
|
|
44
44
|
|
|
45
45
|
If you can't run commands, give the user the matching line from **Manual setup** below.
|
|
46
46
|
|
|
@@ -57,7 +57,7 @@ On Windows, `rushes setup` writes the launch as `cmd /c npx -y rushes mcp` (in J
|
|
|
57
57
|
|
|
58
58
|
### Other harnesses
|
|
59
59
|
|
|
60
|
-
Any MCP client that can launch a local stdio server works. Point it at `npx -y rushes mcp`. Agents with no MCP support can use the CLI instead (`rushes add`, `rushes notes`, `rushes reply`): see [AGENTS.md](AGENTS.md).
|
|
60
|
+
Any MCP client that can launch a local stdio server works. Point it at `npx -y rushes mcp`. Agents with no MCP support can use the CLI instead (`rushes add`, including `rushes add format` for another shape of a cut, `rushes notes`, `rushes reply`): see [AGENTS.md](AGENTS.md).
|
|
61
61
|
|
|
62
62
|
ChatGPT's apps can't run local MCP servers yet. Use Codex, OpenAI's agent, instead.
|
|
63
63
|
|
|
@@ -69,6 +69,8 @@ npx -y rushes open # opens the review desk in your browser
|
|
|
69
69
|
npx -y rushes stop # stops it
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
+
`rushes open` also looks through the folder for the files that go with the cut, and says what it brought in and what it left (see **Finding your other files**).
|
|
73
|
+
|
|
72
74
|
Each project opens at its own address, `http://127.0.0.1:4580/p/<id>/` — safe to run several projects at once.
|
|
73
75
|
|
|
74
76
|
A server your agent starts in the background stops by itself after two hours with nothing connected.
|
|
@@ -114,6 +116,7 @@ Anywhere:
|
|
|
114
116
|
|
|
115
117
|
- **1–7** switch tab (7: Assets)
|
|
116
118
|
- **[ / ]** previous/next film
|
|
119
|
+
- **Alt+←/→** previous/next format (Picture)
|
|
117
120
|
- **?** shortcuts
|
|
118
121
|
- **Esc** close
|
|
119
122
|
|
|
@@ -123,13 +126,70 @@ Every tab is visible from the start, in workflow order, even before there's anyt
|
|
|
123
126
|
|
|
124
127
|
> 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.
|
|
125
128
|
|
|
129
|
+
When the project's folder already holds files for a locked Voiceover, Music or Sound 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.
|
|
130
|
+
|
|
126
131
|
Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets tab follows the same rule.
|
|
127
132
|
|
|
133
|
+
## The Change Log
|
|
134
|
+
|
|
135
|
+
The **Change Log** button in the header opens a log of what happened, newest first and grouped by day:
|
|
136
|
+
|
|
137
|
+
- 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;
|
|
138
|
+
- the script, picks and notes sent;
|
|
139
|
+
- the agent's replies.
|
|
140
|
+
|
|
141
|
+
Rushes writes it itself, one short line per event, and a burst of registrations is one line. You can:
|
|
142
|
+
|
|
143
|
+
- type a line of your own at the top;
|
|
144
|
+
- filter by tab;
|
|
145
|
+
- click a line to open that cut or variant.
|
|
146
|
+
|
|
147
|
+
A dot on the button means new lines since you last looked. **Export as Markdown** writes `exports/change-log-<date>.md`; **Export notes** on the Exports tab 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".
|
|
148
|
+
|
|
149
|
+
Picture'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 and under the picture.
|
|
150
|
+
|
|
151
|
+
Agents read and write the same log with `rushes_get_log` and `rushes_log`, or from the command line:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
rushes log --limit 20 # newest first
|
|
155
|
+
rushes log --area music
|
|
156
|
+
rushes log --md # the same Markdown the export writes
|
|
157
|
+
rushes log add "Kept the wide shot" --area picture
|
|
158
|
+
rushes log add --area mix -- "-3 dB on the bed" # text that starts with a dash goes after --
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Finding your other files
|
|
162
|
+
|
|
163
|
+
An agent only shows what it registers, but the work that goes with a cut usually sits in the same folder: the voiceover, the music, the effects. So when a project is opened, Rushes looks through the folder itself, and brings in the **current set** for the newest cut so those tabs have something to review.
|
|
164
|
+
|
|
165
|
+
- **When.** On open (`rushes open`, or your agent's `rushes_open`) and whenever you press **Look again** or run `rushes scan`. There's no folder watcher.
|
|
166
|
+
- **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.
|
|
167
|
+
- **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.
|
|
168
|
+
- **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.
|
|
169
|
+
- **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. A chip in the header ("3 brought in · 118 more found") opens it while there's something new to look at.
|
|
170
|
+
- **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.
|
|
171
|
+
- **Not these** hides the ticked files for good. A **Hidden** list brings them back with **Restore**.
|
|
172
|
+
- **Look again** runs the scan once more, and a filter box and kind buttons narrow the list.
|
|
173
|
+
- Files already in the project are never offered twice.
|
|
174
|
+
- **Locked tabs say so.** If the folder holds files for a tab that's still locked, its page adds a line under the prompt, such as "14 music files found in this project" (or "1 music file found in this project"), with a **Review** button that opens Found filtered to that kind. The line follows the live count.
|
|
175
|
+
|
|
176
|
+
If the guess is wrong, ask your agent to bring in the right file: `rushes_bring_in`, or `include` on `rushes_open` for files it made for this cut, which come in whatever they score and win over the guess. `rushes_scan` lists what's left, with reasons.
|
|
177
|
+
|
|
178
|
+
The same from the command line:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
npx -y rushes scan [--film NAME] [--json]
|
|
182
|
+
npx -y rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME] [--film NAME]
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
- `rushes scan` looks again, brings in the current set as opening does, and prints what it brought in and the top candidates left with their reasons. `--json` prints all of them as data.
|
|
186
|
+
- `rushes bring-in` brings the named files in. Paths are read from the folder you run it in. `--kind` is needed when a name doesn't say (`doc` takes `md`, `txt` and `pdf`), `--round` names the voiceover round, and `--film` picks the film a cut joins. It prints one line per file, says why for any it can't bring in (a path outside the project folder is always refused), and exits 1 if any failed.
|
|
187
|
+
|
|
128
188
|
## Screenshots and the Assets library
|
|
129
189
|
|
|
130
|
-
Press **G**, or the camera button, to grab the current frame. It's saved as a PNG to `screenshots/`, named for the film, version and timecode — grabbing the same frame twice overwrites the same file.
|
|
190
|
+
Press **G**, or the camera button, to grab the current frame. It's saved as a PNG to `screenshots/`, named for the film, version and timecode (and, on a cut with several formats, the ratio on screen) — grabbing the same frame twice overwrites the same file.
|
|
131
191
|
|
|
132
|
-
The **Assets** tab (key `7`) is a library with a folder sidebar: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and Proxies. Each folder has search and a sort order; Screenshots, Images, Cuts and Delivery also get a grid/list toggle, and Screenshots, Cuts and Delivery get a film filter — every other folder is list-only. Audio plays inline, one at a time, and Markdown or text files get a read-only preview. Every item has five actions: Download, Save as (Chrome and Edge only — other browsers just get Download), Open, Show in Finder and Copy path. A file your agent registered from outside the project folder (or reached through a link out of it) plays and downloads only if it is a media or document type (audio, video, images, PDF, Markdown, text, captions); for anything else, such as an editor project file on another drive, use Show in Finder or Copy path. **Open** appears, and is accepted, only for a fixed list of safe, non-executable types — never scripts, apps or archives. Top-level `.md`, `.txt`, `.pdf`, `.srt` and `.vtt` files, plus anything in `exports/`, are picked up automatically; everything else your agent registers with `rushes_add_file`. The Exports folder also has an **Export notes** button, which writes every note to a dated Markdown file there.
|
|
192
|
+
The **Assets** tab (key `7`) is a library with a folder sidebar: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and Proxies. Each folder has search and a sort order; Screenshots, Images, Cuts and Delivery also get a grid/list toggle, and Screenshots, Cuts and Delivery get a film filter — every other folder is list-only. Audio plays inline, one at a time, and Markdown or text files get a read-only preview. Every item has five actions: Download, Save as (Chrome and Edge only — other browsers just get Download), Open, Show in Finder and Copy path. A file your agent registered from outside the project folder (or reached through a link out of it) plays and downloads only if it is a media or document type (audio, video, images, PDF, Markdown, text, captions), and a cut or a format only if it is video or audio; for anything else, such as an editor project file on another drive, use Show in Finder or Copy path. **Open** appears, and is accepted, only for a fixed list of safe, non-executable types — never scripts, apps or archives. Top-level `.md`, `.txt`, `.pdf`, `.srt` and `.vtt` files, plus anything in `exports/`, are picked up automatically; everything else your agent registers with `rushes_add_file`. The Exports folder also has an **Export notes** button, which writes every note to a dated Markdown file there.
|
|
133
193
|
|
|
134
194
|
Rushes recommends this layout for a project folder:
|
|
135
195
|
|
|
@@ -151,6 +211,16 @@ Rushes creates `screenshots/` itself on the first grab. It never creates the oth
|
|
|
151
211
|
|
|
152
212
|
A project with more than one film gets numbered pills in the header — `[`/`]` switch between them, and each film remembers its own version and playhead. The header reads **Picture vN**, with a lock button beside it: 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 as a strip under the timeline, and every Picture note records the shot it falls in.
|
|
153
213
|
|
|
214
|
+
## Formats
|
|
215
|
+
|
|
216
|
+
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. Picture then shows a toggle beside the version, 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.
|
|
217
|
+
|
|
218
|
+
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`.
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
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 toggle) to switch format.
|
|
223
|
+
|
|
154
224
|
## Proxies
|
|
155
225
|
|
|
156
226
|
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.
|
|
@@ -181,6 +251,7 @@ your-project/.rushes/
|
|
|
181
251
|
notes.json every note, with the agent's replies
|
|
182
252
|
picks.json which variant or take is in use, and each Mix lane's level
|
|
183
253
|
batches.json what you sent to the agent
|
|
254
|
+
log.json the Change Log: what happened, one line each
|
|
184
255
|
```
|
|
185
256
|
|
|
186
257
|
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.
|
package/dist/cli/doctor.js
CHANGED
|
@@ -191,7 +191,8 @@ async function harnessCheck(h, env) {
|
|
|
191
191
|
* against this project's own canonical root (the same check `isRushesFor` in server/lock.ts
|
|
192
192
|
* makes), falling back to a pid check when nothing answers. A server answering for a *different*
|
|
193
193
|
* project is reported as a failure -- a stale server.json left behind when the project moved or
|
|
194
|
-
* its folder was reused -- everything else here is informational.
|
|
194
|
+
* its folder was reused -- everything else here is informational. Also passes on how many Change
|
|
195
|
+
* Log lines that server couldn't write (ruling e), which runDoctor reports as its own check.
|
|
195
196
|
*/
|
|
196
197
|
async function serverCheck(cwd) {
|
|
197
198
|
const base = { id: "server", label: "Rushes server", required: false };
|
|
@@ -203,7 +204,7 @@ async function serverCheck(cwd) {
|
|
|
203
204
|
lock = null;
|
|
204
205
|
}
|
|
205
206
|
if (!lock || typeof lock.port !== "number" || typeof lock.pid !== "number") {
|
|
206
|
-
return { ...base, ok: true, detail: "No server is running for this folder." };
|
|
207
|
+
return { check: { ...base, ok: true, detail: "No server is running for this folder." }, logFailures: 0 };
|
|
207
208
|
}
|
|
208
209
|
const { port, pid } = lock;
|
|
209
210
|
const root = await canonicalRoot(cwd);
|
|
@@ -219,13 +220,12 @@ async function serverCheck(cwd) {
|
|
|
219
220
|
if (health?.app === "rushes") {
|
|
220
221
|
if (health.root !== root) {
|
|
221
222
|
return {
|
|
222
|
-
...base,
|
|
223
|
-
|
|
224
|
-
detail: `server.json points at another project's server (port ${port}).`,
|
|
225
|
-
fix: "Run rushes stop here, then rushes open",
|
|
223
|
+
check: { ...base, ok: false, detail: `server.json points at another project's server (port ${port}).`, fix: "Run rushes stop here, then rushes open" },
|
|
224
|
+
logFailures: 0,
|
|
226
225
|
};
|
|
227
226
|
}
|
|
228
|
-
|
|
227
|
+
const logFailures = typeof health.logFailures === "number" && Number.isFinite(health.logFailures) ? Math.max(0, Math.floor(health.logFailures)) : 0;
|
|
228
|
+
return { check: { ...base, ok: true, detail: `running on port ${port}${health.id ? `, project ${health.id}` : ""}.` }, logFailures };
|
|
229
229
|
}
|
|
230
230
|
let alive = false;
|
|
231
231
|
try {
|
|
@@ -235,7 +235,7 @@ async function serverCheck(cwd) {
|
|
|
235
235
|
catch {
|
|
236
236
|
alive = false;
|
|
237
237
|
}
|
|
238
|
-
return { ...base, ok: true, detail: alive ? `running on port ${port}.` : `not running (a stale lock names pid ${pid}; it clears on the next start).` };
|
|
238
|
+
return { check: { ...base, ok: true, detail: alive ? `running on port ${port}.` : `not running (a stale lock names pid ${pid}; it clears on the next start).` }, logFailures: 0 };
|
|
239
239
|
}
|
|
240
240
|
/** Free space where proxies live, only reported when a proxies/ folder exists. */
|
|
241
241
|
async function diskSpaceCheck(env) {
|
|
@@ -296,10 +296,35 @@ export async function runDoctor(env) {
|
|
|
296
296
|
checks.push({ id: `file:${key}`, label: name, ok: true, required: true, detail: "valid." });
|
|
297
297
|
}
|
|
298
298
|
catch (e) {
|
|
299
|
-
checks.push({
|
|
299
|
+
checks.push({
|
|
300
|
+
id: `file:${key}`, label: name, ok: false, required: key !== "log", detail: e.message,
|
|
301
|
+
fix: key === "found"
|
|
302
|
+
? `Delete ${RUSHES_DIR}/${name}. Rushes recreates it; files you hid come back in Found and the current set may be chosen again. Nothing else is lost.`
|
|
303
|
+
: key === "log"
|
|
304
|
+
? `Delete ${RUSHES_DIR}/${name}. Rushes starts the Change Log again, reading in the cuts, notes sent and files it has dates for. Nothing else is lost.`
|
|
305
|
+
: `Fix or restore ${name}, or delete the ${RUSHES_DIR} folder and run rushes init to start over.`,
|
|
306
|
+
});
|
|
300
307
|
}
|
|
301
308
|
}
|
|
302
|
-
|
|
309
|
+
// R7: a Change Log that couldn't be read was set aside, and the log started again.
|
|
310
|
+
if (await exists(join(env.cwd, RUSHES_DIR, "log.json.bad"))) {
|
|
311
|
+
checks.push({
|
|
312
|
+
id: "file:log-bad", label: "log.json.bad", ok: false, required: false,
|
|
313
|
+
detail: "An earlier Change Log couldn't be read, so Rushes set it aside as log.json.bad and started the log again. Nothing else was affected.",
|
|
314
|
+
fix: `Nothing to do. Delete ${RUSHES_DIR}/log.json.bad once you don't need it.`,
|
|
315
|
+
});
|
|
316
|
+
}
|
|
317
|
+
const server = await serverCheck(env.cwd);
|
|
318
|
+
checks.push(server.check);
|
|
319
|
+
// Ruling e: the running server counts Change Log lines it couldn't write. The changes themselves were saved.
|
|
320
|
+
if (server.logFailures > 0) {
|
|
321
|
+
const n = server.logFailures;
|
|
322
|
+
checks.push({
|
|
323
|
+
id: "log:writes", label: "Change Log", ok: false, required: false,
|
|
324
|
+
detail: `${n === 1 ? "1 change wasn't" : `${n} changes weren't`} written to the Change Log since the server started. The changes themselves were saved.`,
|
|
325
|
+
fix: `Check there's free disk space and that ${RUSHES_DIR}/log.json can be written, then restart the server with rushes stop and rushes open.`,
|
|
326
|
+
});
|
|
327
|
+
}
|
|
303
328
|
const disk = await diskSpaceCheck(env);
|
|
304
329
|
if (disk)
|
|
305
330
|
checks.push(disk);
|