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/dist/cli/main.js CHANGED
@@ -9,7 +9,11 @@ import { AlreadyRunningError, canonicalRoot } from "../server/lock.js";
9
9
  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
+ 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";
12
15
  import { markLabel } from "../core/schema.js";
16
+ import { formatTag } from "../core/formats.js";
13
17
  import { onLabel } from "../core/notes.js";
14
18
  import { setup } from "../setup/setup.js";
15
19
  import { realSetupEnv } from "../setup/env.js";
@@ -17,7 +21,8 @@ import { runDoctor, realDoctorEnv } from "./doctor.js";
17
21
  export const HELP = `rushes ${VERSION}: a local review desk for video made with AI agents
18
22
 
19
23
  Usage
20
- rushes open [dir] [--port 4580] [--no-browser] start the review desk and open it
24
+ rushes open [dir] [--film NAME] [--port 4580] [--no-browser]
25
+ start the review desk, bring in the files that go with the cut, and open it
21
26
  rushes serve [dir] [--port 4580] [--idle-minutes N]
22
27
  start the server without a browser (stops after N idle minutes)
23
28
  rushes stop [dir] stop the project's running server
@@ -28,7 +33,11 @@ Usage
28
33
  rushes mcp run the MCP server over stdio
29
34
  rushes status [dir] tabs and open items
30
35
  rushes doctor [dir] [--json] check Node, ffmpeg, agent harnesses and this project
31
- 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
32
41
  rushes add variant <music|sfx|voice> <file> --name NAME [--lane ID] [--round NAME] [--description TEXT]
33
42
  rushes add shots <file.json> --video NAME [--version V]
34
43
  rushes add file <path> --kind K [--name NAME] [--note TEXT] [--video V]
@@ -38,7 +47,16 @@ Usage
38
47
  rushes notes [--stage S] [--status todo|done] [--batch ID] [--json]
39
48
  rushes reply <note-id> <text> [--done] [--fix-t SECONDS] [--fix-version V]
40
49
  rushes assets [--kind K] [--json] cuts, takes, variants, screenshots and library files
41
- rushes export notes write notes to exports/<slug>-notes-<date>.md
50
+ rushes scan [--film NAME] [--json] look through the folder for the files that go with the cut; also brings in the current set
51
+ rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME] [--film NAME]
52
+ register files from inside the project folder (nothing is picked);
53
+ exits 1 if any file can't come in
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"
42
60
 
43
61
  Options
44
62
  --dir DIR project folder for commands that talk to the server (default: current folder)
@@ -49,6 +67,9 @@ const OPTIONS = {
49
67
  name: { type: "string" },
50
68
  video: { type: "string" },
51
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" },
52
73
  lane: { type: "string" },
53
74
  round: { type: "string" },
54
75
  description: { type: "string" },
@@ -56,6 +77,10 @@ const OPTIONS = {
56
77
  status: { type: "string" },
57
78
  batch: { type: "string" },
58
79
  kind: { type: "string" },
80
+ film: { type: "string" },
81
+ limit: { type: "string" },
82
+ area: { type: "string" },
83
+ md: { type: "boolean" },
59
84
  json: { type: "boolean" },
60
85
  done: { type: "boolean" },
61
86
  "fix-t": { type: "string" },
@@ -185,10 +210,29 @@ export async function main(argv, io) {
185
210
  if (cmd === "open" && !o["no-browser"])
186
211
  (io.openBrowser ?? openBrowser)(url);
187
212
  };
213
+ // §20.1: opening looks through the folder and brings in the current set, then says what it did.
214
+ // The desk is open either way, so a scan that fails says nothing.
215
+ const lookThrough = async (url) => {
216
+ if (cmd !== "open")
217
+ return;
218
+ io.err(LOOKING);
219
+ try {
220
+ const r = await new RushesClient(url).post("/api/found/scan", { wait: true, ...(o.film ? { film: o.film } : {}) });
221
+ if (r.added?.length)
222
+ io.out(broughtLine(r.added));
223
+ const left = foundTotal(r.found);
224
+ if (left)
225
+ io.out(`Found, left for you: ${count(left, "file")} \u2014 open Assets \u203a Found.`);
226
+ }
227
+ catch {
228
+ // Nothing to add to the line above.
229
+ }
230
+ };
188
231
  const already = async (url) => {
189
232
  const dashboardUrl = await dashboardUrlFor(url);
190
233
  io.out(`Rushes is already running for ${root}\n${dashboardUrl}`);
191
234
  show(dashboardUrl);
235
+ await lookThrough(url);
192
236
  return 0;
193
237
  };
194
238
  const running = await findServer(root);
@@ -209,13 +253,17 @@ export async function main(argv, io) {
209
253
  }
210
254
  io.out(`Rushes is running for ${root}\n${s.dashboardUrl}`);
211
255
  show(s.dashboardUrl);
212
- if (io.onServer)
213
- return io.onServer(s), 0;
214
- // Exit once the server closes for any reason: a signal, `rushes stop`, or the idle timer.
215
- void s.closed.then(() => process.exit(0));
216
- const stopSig = () => void s.close();
217
- process.once("SIGINT", stopSig);
218
- process.once("SIGTERM", stopSig);
256
+ if (io.onServer) {
257
+ io.onServer(s);
258
+ }
259
+ else {
260
+ // Exit once the server closes for any reason: a signal, `rushes stop`, or the idle timer.
261
+ void s.closed.then(() => process.exit(0));
262
+ const stopSig = () => void s.close();
263
+ process.once("SIGINT", stopSig);
264
+ process.once("SIGTERM", stopSig);
265
+ }
266
+ await lookThrough(s.url);
219
267
  return 0;
220
268
  }
221
269
  case "stop": {
@@ -289,13 +337,32 @@ export async function main(argv, io) {
289
337
  if (what === "version") {
290
338
  if (!a || !o.video)
291
339
  return usage(io, "rushes add version <file> --video NAME");
292
- 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 });
293
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.");
294
350
  // §19.5: the server says when this cut is likely to play badly in a browser.
295
351
  if (r.proxySuggested)
296
352
  io.out(`Proxy suggested: ${r.proxyReason}.${r.proxyJob ? " Making one now (autoProxy is on)." : " Create one from Picture."}`);
297
353
  return 0;
298
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
+ }
299
366
  if (what === "variant") {
300
367
  if (!a || !b || !o.name)
301
368
  return usage(io, "rushes add variant <music|sfx|voice> <file> --name NAME");
@@ -338,7 +405,7 @@ export async function main(argv, io) {
338
405
  io.out(`Added ${r.kind}: ${r.name}`);
339
406
  return 0;
340
407
  }
341
- return usage(io, "rushes add version|variant|shots|file ...");
408
+ return usage(io, "rushes add version|format|variant|shots|file ...");
342
409
  }
343
410
  case "lock": {
344
411
  const [video, lockVersion] = rest;
@@ -365,14 +432,16 @@ export async function main(argv, io) {
365
432
  const { notes } = await c.get(`/api/notes${q.size ? `?${q}` : ""}`);
366
433
  if (o.json)
367
434
  return io.out(JSON.stringify(notes, null, 2)), 0;
368
- // What an audio note is on (M4), resolved against the project, script and picks.
369
- 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;
370
437
  for (const n of notes) {
371
- const label = ctx ? onLabel(n, ctx) : null;
438
+ const label = state ? onLabel(n, state) : null;
372
439
  const on = label ? `${stripControl(label)} ` : "";
440
+ const tag = state ? formatTag(n, state.project?.videos ?? []) : null;
441
+ const fmtCol = tag ? `${stripControl(tag)} ` : "";
373
442
  const shot = n.shot ? `shot ${String(n.shot.n).padStart(2, "0")} ` : "";
374
443
  const marks = n.marks?.length ? `${n.marks.map(markLabel).join(" · ")} ` : "";
375
- 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}`);
376
445
  }
377
446
  if (!notes.length)
378
447
  io.out("No notes");
@@ -390,12 +459,59 @@ export async function main(argv, io) {
390
459
  io.out("No assets");
391
460
  return 0;
392
461
  }
462
+ case "scan": {
463
+ const c = await client();
464
+ io.err(LOOKING);
465
+ const r = await c.post("/api/found/scan", { wait: true, ...(o.film ? { film: o.film } : {}) });
466
+ const { files } = await c.get("/api/found");
467
+ if (o.json)
468
+ return io.out(JSON.stringify({ files, counts: r.found ?? null, broughtIn: r.added ?? [], alreadyIn: r.alreadyIn ?? [], failed: r.failed ?? [], ...(r.scanning ? { scanning: true } : {}) }, null, 2)), 0;
469
+ if (r.added?.length)
470
+ io.out(broughtLine(r.added));
471
+ const left = foundTotal(r.found);
472
+ if (!left && !r.added?.length)
473
+ return io.out("Nothing found in this folder."), 0;
474
+ if (left) {
475
+ const kinds = Object.entries(r.found).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k === "cut" && n !== 1 ? "cuts" : k}`);
476
+ io.out(`Found, left for you: ${count(left, "file")} (${kinds.join(", ")})`);
477
+ for (const f of files.slice(0, SCAN_ROWS)) {
478
+ const why = f.reasons.length ? ` ${stripControl(f.reasons.join(" \u00b7 "))}` : "";
479
+ io.out(` ${f.kind.padEnd(6)} ${f.score === null ? "-" : String(f.score)} ${stripControl(f.path)}${why}`);
480
+ }
481
+ if (files.length > SCAN_ROWS)
482
+ io.out(` and ${files.length - SCAN_ROWS} more (rushes scan --json lists them all)`);
483
+ }
484
+ return 0;
485
+ }
486
+ case "bring-in": {
487
+ const bringInUsage = "rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME]";
488
+ if (!rest.length)
489
+ return usage(io, bringInUsage);
490
+ if (o.kind !== undefined && !["voice", "music", "sfx", "cut", "doc"].includes(o.kind)) {
491
+ io.err(`--kind must be voice, music, sfx, cut or doc (got "${o.kind}")`);
492
+ return usage(io, bringInUsage);
493
+ }
494
+ if (rest.length > BRING_IN_MAX) {
495
+ io.err(`Up to ${BRING_IN_MAX} files at a time (and 12 of a kind), so the tabs stay quick. You gave ${rest.length}: bring the rest in with a second command.`);
496
+ return usage(io, bringInUsage);
497
+ }
498
+ // Paths are taken from the folder the command runs in; the server checks they're inside the project.
499
+ const files = rest.map((f) => ({ path: resolve(io.cwd, f), ...(o.kind ? { kind: o.kind } : {}), ...(o.round ? { round: o.round } : {}) }));
500
+ const r = await (await client()).post("/api/found/bring-in", { files, ...(o.film ? { film: o.film } : {}) });
501
+ for (const a of r.added)
502
+ io.out(`Brought in: ${stripControl(a.path)} (${a.kind})`);
503
+ for (const f of r.failed)
504
+ io.err(`Not brought in: ${stripControl(f.path)}: ${f.reason}`);
505
+ return r.failed.length ? 1 : 0;
506
+ }
393
507
  case "export": {
394
508
  const [what] = rest;
395
509
  if (what !== "notes")
396
510
  return usage(io, "rushes export notes");
397
511
  const r = await (await client()).post("/api/exports/notes", {});
398
512
  io.out(`Exported notes to ${r.path}`);
513
+ if (r.changeLog)
514
+ io.out(`Exported the Change Log to ${r.changeLog}`);
399
515
  return 0;
400
516
  }
401
517
  case "reply": {
@@ -419,6 +535,54 @@ export async function main(argv, io) {
419
535
  io.out(`Replied to ${id}`);
420
536
  return 0;
421
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
+ }
422
586
  default:
423
587
  io.err(`Unknown command "${cmd}"`);
424
588
  io.err(HELP);
@@ -430,6 +594,23 @@ export async function main(argv, io) {
430
594
  return 1;
431
595
  }
432
596
  }
597
+ /** Said on stderr while a scan is waited on, which can take several seconds on a big folder. */
598
+ const LOOKING = "Looking through the folder\u2026";
599
+ /** How many candidate rows `rushes scan` prints; --json has them all. */
600
+ const SCAN_ROWS = 10;
601
+ function count(n, word) {
602
+ return `${n} ${word}${n === 1 ? "" : "s"}`;
603
+ }
604
+ /** Everything a scan left, by kind, as one number. */
605
+ function foundTotal(counts) {
606
+ return Object.values(counts ?? {}).reduce((sum, n) => sum + n, 0);
607
+ }
608
+ /** "Brought in: a.wav (voice), b.wav (music)", the first few and then how many more. */
609
+ function broughtLine(added) {
610
+ const shown = added.slice(0, 6).map((a) => `${stripControl(a.path)} (${a.kind})`);
611
+ const more = added.length > 6 ? `, and ${added.length - 6} more` : "";
612
+ return `Brought in: ${shown.join(", ")}${more}`;
613
+ }
433
614
  function usage(io, line) {
434
615
  io.err(`Usage: ${line}`);
435
616
  return 2;
@@ -454,13 +635,14 @@ function humanSize(bytes) {
454
635
  }
455
636
  return `${n.toFixed(1)} ${units[i]}`;
456
637
  }
457
- /** 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
458
640
  * reaches a terminal (M5): an odd hand-edit or agent mistake could otherwise move the cursor,
459
641
  * clear the line, or ring the bell when `rushes assets` prints it. --json is untouched -- a
460
642
  * consumer parsing JSON gets the real value, control characters and all. */
461
643
  function stripControl(s) {
462
644
  // eslint-disable-next-line no-control-regex -- the whole point is to match control characters.
463
- return s.replace(/[\x00-\x1f\x7f]/g, "");
645
+ return s.replace(/[\x00-\x1f\x7f-\x9f]/g, "");
464
646
  }
465
647
  function when(n) {
466
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];
@@ -1,3 +1,4 @@
1
+ import { formatTag } from "./formats.js";
1
2
  import { slugify } from "./ids.js";
2
3
  import { onLabel } from "./notes.js";
3
4
  import { markLabel } from "./schema.js";
@@ -42,14 +43,17 @@ function noteTime(t, tOut) {
42
43
  function continued(text, indent) {
43
44
  return text.split("\n").join(`\n${indent}`);
44
45
  }
45
- function noteLines(n, ctx) {
46
+ function noteLines(n, ctx, videos) {
46
47
  // What an audio note is on (M4): "Music · Warm keys", "S2 · Take 1", "Whole mix" ...
47
48
  const label = onLabel(n, ctx);
48
49
  const on = label ? ` · ${label}` : "";
50
+ // §21.4, R4: a Picture note's format, "All" beside it on a cut with formats; nothing on a one-format cut.
51
+ const tag = formatTag(n, videos);
52
+ const fmtPart = tag ? ` · ${tag}` : "";
49
53
  const marks = n.marks.length ? ` · ${n.marks.map(markLabel).join(" · ")}` : "";
50
54
  const shot = n.shot ? ` · shot ${pad(n.shot.n)}` : "";
51
55
  const status = n.status === "done" ? "done" : "to do";
52
- const lines = [`- **${noteTime(n.t, n.tOut)}**${on}${marks}${shot} · ${status} — ${continued(n.text, " ")}`];
56
+ const lines = [`- **${noteTime(n.t, n.tOut)}**${fmtPart}${on}${marks}${shot} · ${status} — ${continued(n.text, " ")}`];
53
57
  if (n.reply)
54
58
  lines.push(` - Reply: ${continued(n.reply, " ")}`);
55
59
  if (n.grab)
@@ -92,7 +96,7 @@ export function notesMarkdown(project, notes, now, script = { sections: [] }, pi
92
96
  continue;
93
97
  lines.push("", `### ${video.name} · ${version.id}`);
94
98
  for (const n of group) {
95
- lines.push(...noteLines(n, ctx));
99
+ lines.push(...noteLines(n, ctx, project.videos));
96
100
  matched.add(n);
97
101
  }
98
102
  }
@@ -116,12 +120,12 @@ export function notesMarkdown(project, notes, now, script = { sections: [] }, pi
116
120
  for (const g of orphanGroups.values()) {
117
121
  lines.push("", `### ${g.label} (removed)`);
118
122
  for (const n of [...g.notes].sort(byTimecode))
119
- lines.push(...noteLines(n, ctx));
123
+ lines.push(...noteLines(n, ctx, project.videos));
120
124
  }
121
125
  }
122
126
  else {
123
127
  for (const n of stageNotes)
124
- lines.push(...noteLines(n, ctx));
128
+ lines.push(...noteLines(n, ctx, project.videos));
125
129
  }
126
130
  }
127
131
  return lines.join("\n") + "\n";
@@ -0,0 +1,159 @@
1
+ /** §21.3's standard ratios, as [width, height]. */
2
+ export const STANDARD_RATIOS = [
3
+ [1, 1], [4, 5], [5, 4], [4, 3], [3, 4], [3, 2], [2, 3], [16, 9], [9, 16], [21, 9], [9, 21],
4
+ ];
5
+ /** A format id: the label with ":" as "x", e.g. "9x16", "2.39x1", "10x7". */
6
+ export const FORMAT_ID_RE = /^\d+(?:\.\d+)?x\d+(?:\.\d+)?$/;
7
+ /** The most shapes one cut can have, the primary included (ruling R3). */
8
+ export const MAX_FORMATS = 8;
9
+ /** The order the chips always take (§21.5), so a chip never moves between projects. */
10
+ export const CHIP_ORDER = ["9x16", "4x5", "1x1", "4x3", "16x9"];
11
+ /** The largest side, in pixels, that counts as a picture size (a guard against nonsense, not a codec limit). */
12
+ export const MAX_PICTURE_SIDE = 100000;
13
+ /** A picture size: two whole numbers, each from 1 to MAX_PICTURE_SIDE. */
14
+ export function isPictureSize(width, height) {
15
+ return [width, height].every((n) => Number.isInteger(n) && n >= 1 && n <= MAX_PICTURE_SIDE);
16
+ }
17
+ function gcd(a, b) {
18
+ while (b)
19
+ [a, b] = [b, a % b];
20
+ return a;
21
+ }
22
+ /** 2.388 -> "2.39", 2.4 -> "2.4", 2 -> "2". */
23
+ const decimal = (n) => String(Number(n.toFixed(2)));
24
+ /** R13: the long side over the short, to two decimals: "2.39:1", "1:2.39". */
25
+ const decimalLabel = (r) => (r >= 1 ? `${decimal(r)}:1` : `1:${decimal(1 / r)}`);
26
+ /** 1% as a log ratio: |ln(a/b)| is the same for a landscape picture and its portrait twin. */
27
+ const SNAP = Math.log(1.01) + 1e-12;
28
+ /** The standard ratio nearest `r`, and how far off it is: |ln(r / standard)|, so 16:9 and 9:16 mirror. */
29
+ function nearestStandard(r) {
30
+ let best = null;
31
+ let err = Infinity;
32
+ for (const s of STANDARD_RATIOS) {
33
+ const e = Math.abs(Math.log(r / (s[0] / s[1])));
34
+ if (e < err) {
35
+ err = e;
36
+ best = s;
37
+ }
38
+ }
39
+ return { best, err };
40
+ }
41
+ /**
42
+ * §21.3: the label for a picture `width` × `height` (its shape on screen). The nearest standard
43
+ * ratio within 1%, otherwise the reduced fraction when both terms are 32 or less, otherwise a
44
+ * decimal with the long side over the short (R13): "2.39:1", "1:2.39".
45
+ */
46
+ export function ratioLabel(width, height) {
47
+ if (!isPictureSize(width, height))
48
+ throw new RangeError(`Not a picture size: ${width}×${height}`);
49
+ const r = width / height;
50
+ const { best, err } = nearestStandard(r);
51
+ if (best && err <= SNAP)
52
+ return `${best[0]}:${best[1]}`;
53
+ const g = gcd(width, height);
54
+ if (width / g <= 32 && height / g <= 32)
55
+ return `${width / g}:${height / g}`;
56
+ // The long side over the short, worked out the same way for a picture and its portrait twin.
57
+ return width >= height ? `${decimal(width / height)}:1` : `1:${decimal(height / width)}`;
58
+ }
59
+ export const ratioId = (label) => label.replace(":", "x");
60
+ export const labelOfId = (id) => id.replace("x", ":");
61
+ /** "9:16" -> 0.5625; null for anything that isn't "a:b" with both terms above 0. */
62
+ export function ratioValue(label) {
63
+ const m = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/.exec(label.trim());
64
+ if (!m)
65
+ return null;
66
+ const a = Number(m[1]);
67
+ const b = Number(m[2]);
68
+ return a > 0 && b > 0 ? a / b : null;
69
+ }
70
+ const isStandard = (label) => STANDARD_RATIOS.some(([a, b]) => `${a}:${b}` === label);
71
+ /** The longest a label can be (it becomes a format id, which the schema caps at 16 characters). */
72
+ const MAX_LABEL = 16;
73
+ /**
74
+ * §21.4's `label`, which is only a hint (R10). It is used only when the measured ratio isn't a
75
+ * standard one, the hint isn't itself within 1% of a standard ratio (that would be §21.3's job, and
76
+ * a render can't be labelled as a ratio it isn't), and the hint is within 2% of the measured shape.
77
+ * A hint that is used is rewritten into the canonical R13 form ("12:5", "2.40:1" and "2.4:1.0"
78
+ * all become "2.4:1"), so two spellings can never make two ids for one shape. Otherwise the
79
+ * measured label stands, with a note saying why.
80
+ */
81
+ export function settleLabel(width, height, hint) {
82
+ const measured = ratioLabel(width, height);
83
+ const given = hint?.trim() ?? "";
84
+ if (given === "" || given === measured)
85
+ return { label: measured, note: null };
86
+ if (given.length > MAX_LABEL)
87
+ return { label: measured, note: `The label is too long to be a ratio, so Rushes used the measured ${measured}.` };
88
+ const v = ratioValue(given);
89
+ if (v === null)
90
+ return { label: measured, note: `"${given}" isn't a ratio like 2.39:1, so Rushes used the measured ${measured}.` };
91
+ if (isStandard(measured))
92
+ return { label: measured, note: `The file measures ${measured}, a standard ratio, so the label "${given}" wasn't needed.` };
93
+ const standard = nearestStandard(v);
94
+ if (standard.best && standard.err <= SNAP) {
95
+ return { label: measured, note: `"${given}" is a standard ratio, and the file isn't one, so Rushes used the measured ${measured}.` };
96
+ }
97
+ const r = width / height;
98
+ if (Math.abs(Math.log(v / r)) > Math.log(1.02))
99
+ return { label: measured, note: `The file measures ${measured}, too far from "${given}" to use it.` };
100
+ const canonical = decimalLabel(v);
101
+ return { label: canonical, note: canonical === given ? null : `Rushes wrote the label "${given}" as ${canonical}.` };
102
+ }
103
+ /**
104
+ * Final review M1: two picture sizes are one shape when their ratios are within 1% of each other
105
+ * (|ln(a/b)|, so a landscape pair and its portrait twin compare alike), whatever labels they got:
106
+ * 1920×800 ("12:5") and 1920×804 ("2.39:1") are one shape.
107
+ */
108
+ export function sameShape(a, b) {
109
+ return Math.abs(Math.log((a.width / a.height) / (b.width / b.height))) <= SNAP;
110
+ }
111
+ /** §21.5: 9:16, 4:5, 1:1, 4:3, 16:9, then anything else from narrow to wide (width over height). */
112
+ export function chipOrder(list) {
113
+ const rank = (f) => {
114
+ const i = CHIP_ORDER.indexOf(f.id);
115
+ return i === -1 ? CHIP_ORDER.length : i;
116
+ };
117
+ return [...list].sort((a, b) => rank(a) - rank(b) || a.width / a.height - b.width / b.height || a.id.localeCompare(b.id));
118
+ }
119
+ /**
120
+ * A version's shapes: the primary first (§21.2 (2): its ratio is read from its own size), then
121
+ * the formats as stored. While the primary's size is unknown the primary is left out (never
122
+ * guessed), unless `fallback` (the player's measured size, R2) gives it; the listed formats stay.
123
+ */
124
+ export function versionFormats(v, fallback) {
125
+ const stored = v.width !== null && v.height !== null && isPictureSize(v.width, v.height) ? { width: v.width, height: v.height } : null;
126
+ const size = stored ?? (fallback && isPictureSize(fallback.width, fallback.height) ? fallback : null);
127
+ const rest = v.formats.map((f) => ({ id: f.id, label: f.label, file: f.file, width: f.width, height: f.height, duration: f.duration, fps: f.fps, primary: false }));
128
+ if (!size)
129
+ return rest;
130
+ const label = ratioLabel(size.width, size.height);
131
+ return [{ id: ratioId(label), label, file: v.file, width: size.width, height: size.height, duration: v.duration, fps: v.fps, primary: true }, ...rest];
132
+ }
133
+ /** §21.3: "9:16 is 8.4 s; the cut is 8.0 s" when a format's length is more than 0.1 s off the cut's. */
134
+ export function durationWarning(label, formatDuration, cutDuration) {
135
+ if (formatDuration === null || cutDuration === null)
136
+ return null;
137
+ if (Math.abs(formatDuration - cutDuration) <= 0.1 + 1e-9)
138
+ return null;
139
+ return `${label} is ${formatDuration.toFixed(1)} s; the cut is ${cutDuration.toFixed(1)} s`;
140
+ }
141
+ /** §21.2 (5): does `note` show while `current` is on screen? `current` is null on a one-format cut. */
142
+ export function noteShowsOn(note, current) {
143
+ return current === null || note.format === null || note.format === current;
144
+ }
145
+ /**
146
+ * The tag a Picture note carries in export, the CLI and the list (R4): its format's label, "All"
147
+ * on a cut with two or more formats, otherwise null (a one-format cut reads as it always did).
148
+ */
149
+ export function formatTag(note, videos) {
150
+ if (note.stage !== "picture")
151
+ return null;
152
+ // Null-safe: the CLI and agents read data from a 0.2.x server too, whose notes have no `format` and
153
+ // whose versions have no `formats` (review I1).
154
+ if (note.format != null)
155
+ return labelOfId(note.format);
156
+ const version = videos.find((v) => v.id === note.video)?.versions.find((v) => v.id === note.version);
157
+ // Any listed format means two or more shapes, whether or not the primary's size is known.
158
+ return (version?.formats?.length ?? 0) >= 1 ? "All" : null;
159
+ }