rushes 0.2.2 → 0.4.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.
@@ -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.2.2",
4
+ "version": "0.4.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 its path.
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
 
@@ -60,15 +60,16 @@ Every tab is visible from the start, in workflow order, even before it has anyth
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
- - 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
+ - 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, 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 Sound 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.
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
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/`) and `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set). 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).
71
- 5. **Register the new cut** with `rushes_add_version` and note what changed. If the video is locked, the reply carries `warning: "Picture is locked at vN"`; the version is still added.
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.
@@ -89,9 +90,19 @@ Pass `include` for files you made for this cut: `include: [{ path, kind?, round?
89
90
 
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.
91
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
+
92
103
  ## Tools
93
104
 
94
- The MCP server has nineteen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `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_scan`, `rushes_bring_in` and `rushes_doctor`. Each takes an optional `project` folder, which defaults to the folder the harness started in.
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.
95
106
 
96
107
  ## Rules
97
108
 
@@ -109,13 +120,16 @@ The MCP server has nineteen tools: `rushes_open`, `rushes_status`, `rushes_add_v
109
120
 
110
121
  ```bash
111
122
  npx -y rushes open
112
- npx -y rushes add version renders/hero_v2.mp4 --video "Hero 60s" --note "logo hold"
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"
113
125
  npx -y rushes notes --stage picture --status todo --json
114
126
  npx -y rushes reply n_8f2k3a "Held the phone 0.5 s longer" --done --fix-t 12.9 --fix-version v2
115
127
  npx -y rushes add variant voice gerald.wav --name Gerald --round "Round 1 · Voices"
116
128
  npx -y rushes add shots shots.json --video "Hero 60s" --version v2
117
129
  npx -y rushes add file brief.pdf --kind doc
118
130
  npx -y rushes export notes
131
+ npx -y rushes log --limit 20
132
+ npx -y rushes log add "Slowed the zooms" --area picture
119
133
  npx -y rushes doctor --json
120
134
  npx -y rushes scan --json
121
135
  npx -y rushes bring-in audio/music/bed.wav --kind music
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 nineteen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `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_scan`, `rushes_bring_in` and `rushes_doctor`.
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
 
@@ -111,11 +111,13 @@ In the Voiceover, Music, Sound effects and Mix tabs:
111
111
  - **←/→** step one frame (Shift: ten)
112
112
  - **I/O** set in and out
113
113
  - **N** new note
114
+ - **←/→** with a cue or a layer's tick focused: the previous or next cue (**Home**/**End**: the first or last); **Enter** moves the playhead there; **Esc** hides the card
114
115
 
115
116
  Anywhere:
116
117
 
117
118
  - **1–7** switch tab (7: Assets)
118
119
  - **[ / ]** previous/next film
120
+ - **Alt+←/→** previous/next format (Picture)
119
121
  - **?** shortcuts
120
122
  - **Esc** close
121
123
 
@@ -129,6 +131,34 @@ When the project's folder already holds files for a locked Voiceover, Music or S
129
131
 
130
132
  Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets tab follows the same rule.
131
133
 
134
+ ## The Change Log
135
+
136
+ The **Change Log** button in the header opens a log of what happened, newest first and grouped by day:
137
+
138
+ - 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;
139
+ - the script, picks and notes sent;
140
+ - the agent's replies.
141
+
142
+ Rushes writes it itself, one short line per event, and a burst of registrations is one line. You can:
143
+
144
+ - type a line of your own at the top;
145
+ - filter by tab;
146
+ - click a line to open that cut or variant.
147
+
148
+ 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".
149
+
150
+ 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.
151
+
152
+ Agents read and write the same log with `rushes_get_log` and `rushes_log`, or from the command line:
153
+
154
+ ```bash
155
+ rushes log --limit 20 # newest first
156
+ rushes log --area music
157
+ rushes log --md # the same Markdown the export writes
158
+ rushes log add "Kept the wide shot" --area picture
159
+ rushes log add --area mix -- "-3 dB on the bed" # text that starts with a dash goes after --
160
+ ```
161
+
132
162
  ## Finding your other files
133
163
 
134
164
  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.
@@ -158,9 +188,9 @@ npx -y rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME]
158
188
 
159
189
  ## Screenshots and the Assets library
160
190
 
161
- 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.
191
+ 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.
162
192
 
163
- 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.
193
+ 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.
164
194
 
165
195
  Rushes recommends this layout for a project folder:
166
196
 
@@ -182,6 +212,16 @@ Rushes creates `screenshots/` itself on the first grab. It never creates the oth
182
212
 
183
213
  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.
184
214
 
215
+ ## Formats
216
+
217
+ 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.
218
+
219
+ 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`.
220
+
221
+ 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.
222
+
223
+ 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.
224
+
185
225
  ## Proxies
186
226
 
187
227
  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.
@@ -202,6 +242,7 @@ Voiceover works in rounds: the same script read by a few voices, then variations
202
242
  - On Music, Sound effects and Mix, 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".
203
243
  - **Mix** shows a loudness readout — integrated LUFS, true peak, and the music's level under the VO — measured over exactly what Mix 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.
204
244
  - Each **Mix** lane (Voiceover, Music, Sound effects) has 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.
245
+ - On **Sound 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. Mix's Sound effects lane has the card too.
205
246
 
206
247
  ## What gets saved
207
248
 
@@ -212,6 +253,7 @@ your-project/.rushes/
212
253
  notes.json every note, with the agent's replies
213
254
  picks.json which variant or take is in use, and each Mix lane's level
214
255
  batches.json what you sent to the agent
256
+ log.json the Change Log: what happened, one line each
215
257
  ```
216
258
 
217
259
  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.
@@ -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
- ok: false,
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
- return { ...base, ok: true, detail: `running on port ${port}${health.id ? `, project ${health.id}` : ""}.` };
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({ id: `file:${key}`, label: name, ok: false, required: true, detail: e.message, fix: key === "found" ? `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.` : `Fix or restore ${name}, or delete the ${RUSHES_DIR} folder and run rushes init to start over.` });
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
- checks.push(await serverCheck(env.cwd));
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);
package/dist/cli/main.js CHANGED
@@ -10,7 +10,10 @@ import { ApiError, RushesClient, dashboardUrlFor } from "../mcp/client.js";
10
10
  import { openBrowser, runStdio } from "../mcp/stdio.js";
11
11
  import { VERSION } from "../server/app.js";
12
12
  import { BRING_IN_MAX } from "../server/found.js";
13
+ import { LABEL_MAX, oneLineOf } from "../core/labels.js";
14
+ import { LOG_AREAS, LOG_MAX, areaWord, byWord, localStamp, logMarkdown } from "../core/logText.js";
13
15
  import { markLabel } from "../core/schema.js";
16
+ import { formatTag } from "../core/formats.js";
14
17
  import { onLabel } from "../core/notes.js";
15
18
  import { setup } from "../setup/setup.js";
16
19
  import { realSetupEnv } from "../setup/env.js";
@@ -30,7 +33,11 @@ Usage
30
33
  rushes mcp run the MCP server over stdio
31
34
  rushes status [dir] tabs and open items
32
35
  rushes doctor [dir] [--json] check Node, ffmpeg, agent harnesses and this project
33
- rushes add version <file> --video NAME [--note TEXT]
36
+ rushes add version <file> --video NAME [--label TEXT] [--note TEXT]
37
+ --label: the cut's short label in the version list (48 characters)
38
+ rushes add format <file> [--video NAME] [--version V] [--label RATIO]
39
+ register another shape (aspect ratio) of a cut;
40
+ --label here is only a ratio hint such as 2.39:1, not the cut's label
34
41
  rushes add variant <music|sfx|voice> <file> --name NAME [--lane ID] [--round NAME] [--description TEXT]
35
42
  rushes add shots <file.json> --video NAME [--version V]
36
43
  rushes add file <path> --kind K [--name NAME] [--note TEXT] [--video V]
@@ -44,7 +51,12 @@ Usage
44
51
  rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME] [--film NAME]
45
52
  register files from inside the project folder (nothing is picked);
46
53
  exits 1 if any file can't come in
47
- rushes export notes write notes to exports/<slug>-notes-<date>.md
54
+ rushes export notes write notes and the Change Log to exports/<slug>-notes-<date>.md
55
+ and exports/change-log-<date>.md
56
+ rushes log [--limit N] [--area A] [--md] the Change Log, newest first (--md: as Markdown)
57
+ rushes log add <text> [--area A] add a line to the Change Log
58
+ flags first; text that starts with "-" goes after --:
59
+ rushes log add --area mix -- "-3 dB on the bed"
48
60
 
49
61
  Options
50
62
  --dir DIR project folder for commands that talk to the server (default: current folder)
@@ -55,6 +67,9 @@ const OPTIONS = {
55
67
  name: { type: "string" },
56
68
  video: { type: "string" },
57
69
  note: { type: "string" },
70
+ // Two meanings by command: `add version --label` is the cut's short label (§22.4);
71
+ // `add format --label` is a name for the ratio, such as 9:16 (§21.4). One option, read per command.
72
+ label: { type: "string" },
58
73
  lane: { type: "string" },
59
74
  round: { type: "string" },
60
75
  description: { type: "string" },
@@ -63,6 +78,9 @@ const OPTIONS = {
63
78
  batch: { type: "string" },
64
79
  kind: { type: "string" },
65
80
  film: { type: "string" },
81
+ limit: { type: "string" },
82
+ area: { type: "string" },
83
+ md: { type: "boolean" },
66
84
  json: { type: "boolean" },
67
85
  done: { type: "boolean" },
68
86
  "fix-t": { type: "string" },
@@ -319,13 +337,32 @@ export async function main(argv, io) {
319
337
  if (what === "version") {
320
338
  if (!a || !o.video)
321
339
  return usage(io, "rushes add version <file> --video NAME");
322
- const r = await (await client()).post("/api/versions", { video: o.video, file: resolve(io.cwd, a), note: o.note });
340
+ // The server refuses a longer label too, but only in a generic "Request body is invalid".
341
+ if (o.label !== undefined && Array.from(oneLineOf(o.label)).length > LABEL_MAX) {
342
+ io.err(`label is ${LABEL_MAX} characters at most: put the detail in note`);
343
+ return 2;
344
+ }
345
+ const r = await (await client()).post("/api/versions", { video: o.video, file: resolve(io.cwd, a), note: o.note, label: o.label });
323
346
  io.out(`Added ${r.video.name} ${r.version.id}`);
347
+ // A Rushes started by an older version ignores `label` and its reply has none.
348
+ if (o.label?.trim() && r.version.label === undefined)
349
+ io.err("An older Rushes is running and dropped the label: the cut was added without it. Run `rushes stop`, then open again.");
324
350
  // §19.5: the server says when this cut is likely to play badly in a browser.
325
351
  if (r.proxySuggested)
326
352
  io.out(`Proxy suggested: ${r.proxyReason}.${r.proxyJob ? " Making one now (autoProxy is on)." : " Create one from Picture."}`);
327
353
  return 0;
328
354
  }
355
+ if (what === "format") {
356
+ if (!a)
357
+ return usage(io, "rushes add format <file> [--video NAME] [--version V] [--label RATIO]");
358
+ const r = await (await client()).post("/api/formats", { file: resolve(io.cwd, a), video: o.video, version: addVersion, label: o.label });
359
+ io.out(`Added ${r.format.label} to ${r.video.name} ${r.version.id}`);
360
+ if (r.warning)
361
+ io.out(`Warning: ${r.warning}`);
362
+ if (r.labelNote)
363
+ io.out(`Label: ${r.labelNote}`);
364
+ return 0;
365
+ }
329
366
  if (what === "variant") {
330
367
  if (!a || !b || !o.name)
331
368
  return usage(io, "rushes add variant <music|sfx|voice> <file> --name NAME");
@@ -368,7 +405,7 @@ export async function main(argv, io) {
368
405
  io.out(`Added ${r.kind}: ${r.name}`);
369
406
  return 0;
370
407
  }
371
- return usage(io, "rushes add version|variant|shots|file ...");
408
+ return usage(io, "rushes add version|format|variant|shots|file ...");
372
409
  }
373
410
  case "lock": {
374
411
  const [video, lockVersion] = rest;
@@ -395,14 +432,16 @@ export async function main(argv, io) {
395
432
  const { notes } = await c.get(`/api/notes${q.size ? `?${q}` : ""}`);
396
433
  if (o.json)
397
434
  return io.out(JSON.stringify(notes, null, 2)), 0;
398
- // What an audio note is on (M4), resolved against the project, script and picks.
399
- const ctx = notes.some((n) => n.stage !== "picture" && n.stage !== "script") ? await c.get("/api/state") : null;
435
+ // What an audio note is on (M4) and a Picture note's format (§21.4, R4), from the state.
436
+ const state = notes.some((n) => n.stage !== "script") ? await c.get("/api/state") : null;
400
437
  for (const n of notes) {
401
- const label = ctx ? onLabel(n, ctx) : null;
438
+ const label = state ? onLabel(n, state) : null;
402
439
  const on = label ? `${stripControl(label)} ` : "";
440
+ const tag = state ? formatTag(n, state.project?.videos ?? []) : null;
441
+ const fmtCol = tag ? `${stripControl(tag)} ` : "";
403
442
  const shot = n.shot ? `shot ${String(n.shot.n).padStart(2, "0")} ` : "";
404
443
  const marks = n.marks?.length ? `${n.marks.map(markLabel).join(" · ")} ` : "";
405
- io.out(`${n.id} ${n.status === "done" ? "done" : "todo"} ${n.stage.padEnd(7)} ${when(n).padEnd(17)} ${on}${marks}${shot}${n.text}`);
444
+ io.out(`${n.id} ${n.status === "done" ? "done" : "todo"} ${n.stage.padEnd(7)} ${when(n).padEnd(17)} ${fmtCol}${on}${marks}${shot}${n.text}`);
406
445
  }
407
446
  if (!notes.length)
408
447
  io.out("No notes");
@@ -471,6 +510,8 @@ export async function main(argv, io) {
471
510
  return usage(io, "rushes export notes");
472
511
  const r = await (await client()).post("/api/exports/notes", {});
473
512
  io.out(`Exported notes to ${r.path}`);
513
+ if (r.changeLog)
514
+ io.out(`Exported the Change Log to ${r.changeLog}`);
474
515
  return 0;
475
516
  }
476
517
  case "reply": {
@@ -494,6 +535,54 @@ export async function main(argv, io) {
494
535
  io.out(`Replied to ${id}`);
495
536
  return 0;
496
537
  }
538
+ case "log": {
539
+ const logUsage = "rushes log [--limit N] [--area A] [--md] | rushes log add <text> [--area A]";
540
+ const [what, ...words] = rest;
541
+ const area = o.area;
542
+ if (area !== undefined && !LOG_AREAS.includes(area)) {
543
+ io.err(`--area must be one of ${LOG_AREAS.join(", ")} (got "${area}")`);
544
+ return usage(io, logUsage);
545
+ }
546
+ if (what === "add") {
547
+ const text = words.join(" ").trim();
548
+ if (!text)
549
+ return usage(io, 'rushes log add "text" [--area A]');
550
+ const r = await (await client()).post("/api/log", { text, ...(area ? { area } : {}) });
551
+ io.out(`Added to the Change Log: ${stripControl(r.entry.text)}`);
552
+ return 0;
553
+ }
554
+ if (what !== undefined)
555
+ return usage(io, logUsage);
556
+ const limit = o.limit === undefined ? (o.md ? LOG_MAX : 30) : /^\d+$/.test(o.limit) ? Number(o.limit) : NaN;
557
+ if (!(Number.isInteger(limit) && limit >= 1 && limit <= LOG_MAX)) {
558
+ io.err(`--limit must be a whole number from 1 to ${LOG_MAX} (got "${o.limit}")`);
559
+ return usage(io, logUsage);
560
+ }
561
+ const c = await client();
562
+ const q = new URLSearchParams({ limit: String(limit) });
563
+ if (area)
564
+ q.set("area", area);
565
+ const view = await c.get(`/api/log?${q}`);
566
+ if (o.md) {
567
+ const { name } = await c.get("/api/health");
568
+ io.out(logMarkdown({ project: name, entries: view.entries, undated: view.undated, dropped: view.dropped, earlier: view.earlier, ...(area ? { area: area } : {}), now: new Date() }).trimEnd());
569
+ return 0;
570
+ }
571
+ if (!view.entries.length && !view.undated.length)
572
+ return io.out(area ? `Nothing in ${areaWord(area)} yet.` : "Nothing in the Change Log yet."), 0;
573
+ for (const e of view.entries)
574
+ io.out(`${localStamp(new Date(e.at))} ${stripControl(areaWord(e.area)).padEnd(13)} ${stripControl(oneLineOf(e.text))} (${stripControl(byWord(e.by))})`);
575
+ if (view.earlier)
576
+ io.out(`${view.earlier} earlier (rushes log --limit ${Math.min(LOG_MAX, limit + view.earlier)}${area ? ` --area ${area}` : ""} shows them)`);
577
+ if (view.undated.length) {
578
+ io.out("Before the log:");
579
+ for (const u of view.undated)
580
+ io.out(` ${stripControl(oneLineOf(u.text))}`);
581
+ }
582
+ if (view.dropped)
583
+ io.out("Earlier entries were removed.");
584
+ return 0;
585
+ }
497
586
  default:
498
587
  io.err(`Unknown command "${cmd}"`);
499
588
  io.err(HELP);
@@ -546,13 +635,14 @@ function humanSize(bytes) {
546
635
  }
547
636
  return `${n.toFixed(1)} ${units[i]}`;
548
637
  }
549
- /** Drops C0 control characters (U+0000-U+001F) and DEL (U+007F) from a name or path before it
638
+ /** Drops C0 control characters (U+0000-U+001F), DEL (U+007F) and the C1 ones (U+0080-U+009F, among them
639
+ * the single-character CSI, U+009B) from a name or path before it
550
640
  * reaches a terminal (M5): an odd hand-edit or agent mistake could otherwise move the cursor,
551
641
  * clear the line, or ring the bell when `rushes assets` prints it. --json is untouched -- a
552
642
  * consumer parsing JSON gets the real value, control characters and all. */
553
643
  function stripControl(s) {
554
644
  // eslint-disable-next-line no-control-regex -- the whole point is to match control characters.
555
- return s.replace(/[\x00-\x1f\x7f]/g, "");
645
+ return s.replace(/[\x00-\x1f\x7f-\x9f]/g, "");
556
646
  }
557
647
  function when(n) {
558
648
  if (n.scope === "whole" || n.t === null)
@@ -1,3 +1,4 @@
1
+ import { chipOrder, versionFormats } from "./formats.js";
1
2
  import { EmptyBatchError } from "./errors.js";
2
3
  import { isChanged } from "./script.js";
3
4
  const STAGE_NAMES = {
@@ -26,7 +27,7 @@ export function createBatch(ctx, stage, now = new Date()) {
26
27
  noteIds: notes.map((n) => n.id),
27
28
  sectionIds: sections.map((s) => s.id),
28
29
  sentAt: now.toISOString(),
29
- prompt: buildPrompt(ctx.project.name, stage, id, notes.length, sections.length),
30
+ prompt: buildPrompt(ctx.project.name, stage, id, notes.length, sections.length, stage === "picture" ? formatLines(ctx.project, notes) : []),
30
31
  };
31
32
  ctx.batches.batches.push(batch);
32
33
  return batch;
@@ -35,7 +36,38 @@ export function createBatch(ctx, stage, now = new Date()) {
35
36
  // well as the notes, since fixing a note there usually means registering a new take or variant
36
37
  // and re-picking it, not just posting a new cut.
37
38
  const AUDIO_STAGES = ["voice", "music", "sfx", "mix"];
38
- export function buildPrompt(project, stage, batchId, notes, sections) {
39
+ const FORMAT_STEPS = "A note with a format is for that format only: fix it there and leave the others. An all-format note is for every format: say in your reply which formats you fixed. Register every shape of the new cut (rushes_add_version with formats, or rushes_add_format).";
40
+ /** §21.5: for a Picture batch, each cut with formats, its shapes and how many notes each has, then how to fix them. */
41
+ export function formatLines(project, notes) {
42
+ const lines = [];
43
+ const seen = new Set();
44
+ for (const n of notes) {
45
+ const key = `${n.video}\u0000${n.version}`;
46
+ if (seen.has(key))
47
+ continue;
48
+ seen.add(key);
49
+ const video = project.videos.find((v) => v.id === n.video);
50
+ const version = video?.versions.find((v) => v.id === n.version);
51
+ // The cut's own file is a shape beside the listed formats, even while its size is unknown (hand-edited).
52
+ const total = (version?.formats?.length ?? 0) + 1;
53
+ if (!video || !version || total < 2)
54
+ continue;
55
+ const views = versionFormats(version);
56
+ const main = views.find((f) => f.primary);
57
+ const ordered = chipOrder(views.filter((f) => !f.primary));
58
+ const names = main ? [`${main.label} (main)`, ...ordered.map((f) => f.label)].join(", ") : `${ordered.map((f) => f.label).join(", ")} and the cut's own file`;
59
+ const here = notes.filter((x) => x.video === n.video && x.version === n.version);
60
+ const counts = [
61
+ { label: "all formats", k: here.filter((x) => x.format === null).length },
62
+ ...(main ? [main, ...ordered] : ordered).map((f) => ({ label: f.label, k: here.filter((x) => x.format === f.id).length })),
63
+ ].filter((c) => c.k > 0);
64
+ lines.push(`${video.name} ${version.id} has ${total} formats: ${names}. Notes: ${counts.map((c) => `${c.k} for ${c.label}`).join(", ")}.`);
65
+ }
66
+ if (lines.length)
67
+ lines.push(FORMAT_STEPS);
68
+ return lines;
69
+ }
70
+ export function buildPrompt(project, stage, batchId, notes, sections, extra = []) {
39
71
  const parts = [];
40
72
  if (notes)
41
73
  parts.push(`${notes} note${notes === 1 ? "" : "s"}`);
@@ -51,7 +83,7 @@ export function buildPrompt(project, stage, batchId, notes, sections) {
51
83
  : AUDIO_STAGES.includes(stage)
52
84
  ? 'Use rushes_get_batch and rushes_get_picks, fix each note (marks such as "Fall" or "Quieter 3 dB" are part of the note), register the new variant, then rushes_reply.'
53
85
  : "Use rushes_get_batch, fix each note, then rushes_reply with a fixT for each and rushes_add_version for the new cut.";
54
- return `Work through ${STAGE_NAMES[stage]} batch ${batchId} on ${project}: ${parts.join(" and ")}.\n${steps}`;
86
+ return `Work through ${STAGE_NAMES[stage]} batch ${batchId} on ${project}: ${parts.join(" and ")}.\n${[...extra, steps].join("\n")}`;
55
87
  }
56
88
  export function latestBatch(file) {
57
89
  return file.batches[file.batches.length - 1];
@@ -0,0 +1,39 @@
1
+ // §23: a cue's optional source file -- the sample an agent placed at that cue. Checked where it
2
+ // comes in (an audio file, at most 1024 characters, so it can never open the allow-list to
3
+ // anything else) and served by /media only because it is registered (§15.5 applies unchanged).
4
+ import { InvalidError } from "./errors.js";
5
+ export const CUE_FILE_MAX = 1024;
6
+ /** The sample types a cue may name: the audio half of §15.5's outside-the-project list. */
7
+ export const CUE_FILE_EXT = new Set(["wav", "mp3", "m4a", "aac", "aif", "aiff", "flac", "ogg", "opus"]);
8
+ function extOf(file) {
9
+ const base = file.slice(Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")) + 1);
10
+ const dot = base.lastIndexOf(".");
11
+ return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
12
+ }
13
+ /** Whether `file` may be a cue's source: not empty, at most 1024 characters, no NUL, an audio extension. */
14
+ export function isCueFile(file) {
15
+ return file.length > 0 && file.length <= CUE_FILE_MAX && !file.includes("\0") && CUE_FILE_EXT.has(extOf(file));
16
+ }
17
+ /** `file` when it may be a cue's source; otherwise an InvalidError (400) naming the cue. */
18
+ export function checkCueFile(cueName, file) {
19
+ if (file.length > CUE_FILE_MAX)
20
+ throw new InvalidError(`Cue "${cueName}": its file path is over ${CUE_FILE_MAX} characters`);
21
+ if (!isCueFile(file)) {
22
+ throw new InvalidError(`Cue "${cueName}": "${file}" isn't an audio file. Send a .wav, .mp3, .m4a, .aac, .aif, .aiff, .flac, .ogg or .opus.`);
23
+ }
24
+ return file;
25
+ }
26
+ /**
27
+ * Every cue file the project names, once each, in manifest order. A stored one that isn't an
28
+ * audio file (a hand edit) is left out, so it is never served.
29
+ */
30
+ export function cueFiles(project) {
31
+ const out = new Set();
32
+ for (const l of project.lanes) {
33
+ for (const v of l.variants)
34
+ for (const c of v.cues)
35
+ if (c.file !== undefined && isCueFile(c.file))
36
+ out.add(c.file);
37
+ }
38
+ return [...out];
39
+ }