@vosjs/cli 0.81.0 → 0.82.0

package/README.md

@@ -452,6 +452,8 @@ Not sure of a selector? `vos look <url>` (with the take's `--session` or `--stor
 
 **Pinned layers.** A layer ABOUT something on the page names it, and the lowering keeps the two together: `"pin": { "step": "copy", "side": "auto", "mark": "ring", "leader": true }` on any overlay kind places the layer a gap off one side of that step's element and carries it with the element as the camera moves (the layer keeps its screen size; only its place follows). One of `step` (a recorder step's `id`, else its index), `press` (SOURCE seconds; the nearest press names the element, for a human recording) or `rect` (video fractions) names the referent. `side` is `auto` (the first of right, left, below, above whose box fits inside the frame through the layer's life) or a side by name; `gap` is design px (24); `mark` is `ring` or `underline`, a standing highlight on the referent for the layer's life; `leader` draws a hairline from the layer to the referent; `color` is their ink. `transform.x/y` stay the fallback for a pin that cannot resolve, and `vos validate` says why (an unknown step, a step that touched nothing, a scroll inside the layer's window). A layer that cannot name its referent is a caption: place it in the margin, never over the app.
 
+**How long a caption stays.** The captions `vos plan --motion` and `--captions` land are about their steps: each lands as its step begins and leaves as the step ends, or once its words are read when that is later (17 characters a second, the subtitle standard, 1.2 to 3 s), so it never lingers over the steps after it. A caption whose words outlast its step is named in the done line with how long it stays past the step; shorter words, or more time on the step (its `ms`, then a re-record), let it leave with it. Cutting its duration instead only takes the time its words need. It gives way to the next caption 0.1 s before it and never outlives the clip it starts in; one with too little room to be read is dropped and named in the done line, with the room it needs.
+
 **Captions anchored to a step.** A layer's TIME can name a step the way a pin names its place: `"anchor": { "step": "share", "media": "m1", "at": "end", "offset": 0.2 }` starts the layer where that step plays in the cut. The lowering maps the step's moment (its `tStart`, or `tEnd` with `at: "end"`, in `meta.steps` of the media `media` names; absent = the primary) through the segments, speed spans and freezes exactly as a source-anchored span is mapped, then adds `offset` in OUTPUT seconds, so a trim, a speed change or a re-record moves the caption with its step and nobody recomputes a `start`. `start` is the fallback when the step is missing, skipped or cut out, and an anchored layer may leave it out: one whose step then resolves nowhere plays nowhere, which `vos validate` refuses, naming the step. `duration` is the layer's own; on a cut that replays the step's seconds the layer starts in the pass where the step plays the longest (the first on a tie), so a caption about a step lands in the main play rather than a short cold open. A text layer's `{elapsed}` fills with the anchored step's off-camera wait when the recorder kept one (the entry of `meta.skips` that names it, else `offCameraMs` on the step; never a step's own `ms`, which is its reading time), and a step that waited for nothing itself (the beat that lands after an await) reads the nearest earlier wait on its media, which validate notes, as a rounded duration: `"{elapsed} later"` renders `12 minutes later`. `vos validate` says when an anchor cannot resolve (and which fallback plays), when `{elapsed}` has no wait at or before its step to fill from, when two captions are on screen at the same time, naming both, and when a layer anchored to one media's step starts over another media's footage (a caption landed after its gesture, then the footage after that step trimmed away). A document without an anchor lowers exactly as before. Not the re-record `anchor` on spans, which only `vos plan --reuse` reads.
 
 **Image and video overlays.** Media kinds on the same lane: `{ "id": "m0", "kind": "image" | "video", "start": 2, "duration": 4, "key": "/logo.png", "width": 0.35, "radius": 12, "opacity": 1, "loop": false, "transform": { … } }`. `key` is a file inside the take directory (`"/logo.png"`) or a URL; `width` is a fraction of the frame width, height follows the media's aspect; corners in design px. Video time is clip-local and muted by design; soundtracks belong to `doc.audio`.

package/dist/{chunk-S3RI2SHH.js → chunk-5VGIQKVT.js}

@@ -4150,6 +4150,7 @@ import {
   migrateMotion,
   momentOutputs as momentOutputs2,
   ratedSegments as ratedSegments4,
+  resolveAnchor as resolveLayerAnchor,
   sameMedia,
   spanOutputExtent as spanOutputExtent3
 } from "@vosjs/studio-core";
@@ -4158,6 +4159,14 @@ import {
 var CAPTION_MAX = 3;
 var CAPTION_MIN = 1.2;
 var CAPTION_GAP = 0.1;
+var READ_CHARS_PER_SECOND = 17;
+function readingSeconds(text) {
+  const chars = text.trim().replace(/\s+/g, " ").length;
+  return Math.min(
+    CAPTION_MAX,
+    Math.max(CAPTION_MIN, chars / READ_CHARS_PER_SECOND)
+  );
+}
 function fitCaptions(items, slotOf, opts = {}) {
   const max = opts.max ?? CAPTION_MAX;
   const min = opts.min ?? CAPTION_MIN;
@@ -4170,7 +4179,11 @@ function fitCaptions(items, slotOf, opts = {}) {
     const { item, slot } = ordered[i];
     const clipRoom = slot.end - slot.start;
     const nextRoom = nextStart - gap - slot.start;
-    const duration = Math.min(max, clipRoom, nextRoom);
+    const ownRoom = slot.until === void 0 ? Infinity : Math.max(
+      slot.until - slot.start,
+      slot.text === void 0 ? min : readingSeconds(slot.text)
+    );
+    const duration = Math.min(max, clipRoom, nextRoom, ownRoom);
     if (duration < min - 1e-9) {
       dropped.unshift({
         item,
@@ -4178,11 +4191,19 @@ function fitCaptions(items, slotOf, opts = {}) {
       });
       continue;
     }
-    kept.unshift({ item, duration: +duration.toFixed(3) });
+    const held = slot.until === void 0 ? 0 : duration - (slot.until - slot.start);
+    kept.unshift({
+      item,
+      duration: +duration.toFixed(3),
+      ...held > 0.05 ? { held: +held.toFixed(2) } : {}
+    });
     nextStart = slot.start;
   }
   return { kept, dropped };
 }
+function heldLine(label, held) {
+  return `${label} stays ${held.toFixed(2)}s past its step to be read; to let it leave with the step, shorten its words (17 characters read in a second) or give its step more time (its ms, then record again). Do not cut its duration: the words need that time`;
+}
 
 // src/plugin/moments.ts
 import {
@@ -4343,6 +4364,7 @@ function proposeMotion(input, opts) {
   const { words: words2, launch, catalog } = opts;
   const notes = [];
   const skipped = [];
+  const held = [];
   const footage = outputLength(doc);
   const range2 = [0, footage];
   const entrance = launch.entrance;
@@ -4459,15 +4481,37 @@ function proposeMotion(input, opts) {
         (s) => c.id !== void 0 && s.id === c.id || s.step === c.step
       );
       if (!step || step.skipped) continue;
-      const t = stepOutputTime(rated, step, 0.2);
+      const ref = step.id ?? step.step;
+      const t = resolveLayerAnchor(doc, { step: ref, at: "start" }, rated).start;
       if (t === null || t < 0 || t >= footage) continue;
-      beats.push({ caption: c, t: +t.toFixed(3) });
+      const until = resolveLayerAnchor(
+        doc,
+        { step: ref, at: "end" },
+        rated
+      ).start;
+      beats.push({
+        caption: c,
+        t: +t.toFixed(3),
+        ...until !== null ? { until } : {}
+      });
     }
-    const fit = fitCaptions(beats, (b) => ({ start: b.t, end: footage }), {
-      max: CAPTION_BEAT_MAX
-    });
+    const fit = fitCaptions(
+      beats,
+      (b) => ({
+        start: b.t,
+        end: footage,
+        ...b.until !== void 0 ? { until: b.until } : {},
+        text: b.caption.caption
+      }),
+      { max: CAPTION_BEAT_MAX }
+    );
     for (const { item, why } of fit.dropped)
       skipped.push(`caption for step ${item.caption.step}: ${why}`);
+    for (const k of fit.kept)
+      if (k.held)
+        held.push(
+          heldLine(`the caption for step ${k.item.caption.step}`, k.held)
+        );
     for (const { item, duration } of fit.kept)
       captionClips.push(
         houseCaption(
@@ -4531,7 +4575,7 @@ function proposeMotion(input, opts) {
     if (times.length) notes.push(`${times.length} click sound(s)`);
   }
   doc.audio = clips;
-  return { doc, notes, skipped };
+  return { doc, notes, skipped, held };
 }
 function destinationMechanics(d, doc) {
   const set = [];
@@ -6754,7 +6798,7 @@ import {
 import {
   docFreezes,
   ratedSegments as ratedSegments6,
-  resolveAnchor as resolveLayerAnchor
+  resolveAnchor as resolveLayerAnchor2
 } from "@vosjs/studio-core";
 var MIN_SPAN = 0.15;
 var AFTER_STEP = 1;
@@ -7050,7 +7094,7 @@ function retimeOverlays(prev, next, report) {
   };
   return overlays.map((o) => {
     if (o.anchor && typeof o.anchor === "object") {
-      const r = resolveLayerAnchor(next, o.anchor, newPieces);
+      const r = resolveLayerAnchor2(next, o.anchor, newPieces);
       if (r.start === null) {
         report.flagged.push(
           o.start === void 0 ? `overlay ${o.id}: anchored to step ${String(o.anchor.step)}, which is missing, skipped or cut in the new recording \u2014 it has no start to fall back to, so it plays nowhere; re-anchor it or give it a start` : `overlay ${o.id}: anchored to step ${String(o.anchor.step)}, which is missing, skipped or cut in the new recording \u2014 it plays at its fallback ${o.start.toFixed(2)}s; re-anchor or re-place it`
@@ -7337,7 +7381,11 @@ async function planTake(dir, opts = {}) {
   if (opts.motion && (fresh || opts.motion.again)) {
     const proposed = proposeMotion(doc, opts.motion);
     doc = proposed.doc;
-    motion = { notes: proposed.notes, skipped: proposed.skipped };
+    motion = {
+      notes: proposed.notes,
+      skipped: proposed.skipped,
+      held: proposed.held
+    };
   }
   if (opts.still != null) doc.still = opts.still;
   await writeJson(take.paths.doc, doc, true);
@@ -14659,6 +14707,7 @@ import {
   docMediaList as docMediaList2,
   findStep as findStep3,
   mediaKey,
+  overlayPlainText,
   ratedSegments as ratedSegments8,
   resolveAnchor as resolveAnchor5,
   segmentOutputExtents as segmentOutputExtents2
@@ -14744,7 +14793,12 @@ function captionOf(step, actions, script, recorded = []) {
 }
 var safeId = (v) => String(v).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "step";
 function landStepCaptions(doc, actions, opts = {}) {
-  const report = { landed: [], skipped: [], uncaptioned: [] };
+  const report = {
+    landed: [],
+    skipped: [],
+    held: [],
+    uncaptioned: []
+  };
   const mine = (o) => !opts.only || opts.only.has(mediaKey(o.anchor?.media));
   const kept = (doc.overlays ?? []).filter(
     (o) => o.from !== STEP_CAPTIONS_FROM || !mine(o)
@@ -14763,6 +14817,7 @@ function landStepCaptions(doc, actions, opts = {}) {
   };
   const ends = /* @__PURE__ */ new Map();
   const labels = /* @__PURE__ */ new Map();
+  const untils = /* @__PURE__ */ new Map();
   const spoken = (media, step, steps) => kept.some((o) => {
     if (o.kind !== "text" || o.preset !== "caption") return false;
     if (o.anchor && mediaKey(o.anchor.media) === media)
@@ -14815,6 +14870,8 @@ function landStepCaptions(doc, actions, opts = {}) {
         from: STEP_CAPTIONS_FROM
       };
       ends.set(clip, end);
+      const stepEnd = resolveAnchor5(doc, { ...anchor, at: "end" }, rated);
+      if (stepEnd.start !== null) untils.set(clip, stepEnd.start);
       labels.set(clip, label);
       fresh.push(clip);
       report.landed.push({
@@ -14828,12 +14885,17 @@ function landStepCaptions(doc, actions, opts = {}) {
   }
   const fit = fitCaptions(fresh, (c) => ({
     start: c.start,
-    end: ends.get(c) ?? footageEnd
+    end: ends.get(c) ?? footageEnd,
+    ...untils.has(c) ? { until: untils.get(c) } : {},
+    ...c.kind === "text" ? { text: overlayPlainText(c) } : {}
   }));
   for (const { item, why } of fit.dropped) {
     report.skipped.push(`${labels.get(item) ?? item.id}: ${why}`);
     report.landed = report.landed.filter((l) => l.id !== item.id);
   }
+  for (const k of fit.kept)
+    if (k.held)
+      report.held.push(heldLine(labels.get(k.item) ?? k.item.id, k.held));
   const landedClips = fit.kept.map(({ item, duration }) => {
     item.duration = duration;
     return item;
@@ -16335,6 +16397,7 @@ async function cmdJoin(argv) {
   let captions = null;
   if (withCaptions) {
     captions = landStepCaptions(plan.doc, plan.actions, { only });
+    for (const line of captions.held) plan.notes.push(line);
     for (const k of captions.uncaptioned)
       plan.notes.push(
         `no step in ${labelOf.get(k) ?? `media ${k}`} carries a caption`
@@ -16462,7 +16525,7 @@ import {
   freezeOutputExtents,
   mediaKey as mediaKey5,
   migrateMotion as migrateMotion4,
-  overlayPlainText,
+  overlayPlainText as overlayPlainText2,
   longestOutputExtent as longestOutputExtent3,
   ratedSegments as ratedSegments11,
   resolveOverlayAnchors as resolveOverlayAnchors2,
@@ -16576,7 +16639,7 @@ function takeTimeline(rawDoc, actions = /* @__PURE__ */ new Map()) {
     const start = o.start;
     if (start === void 0) return [];
     const raw = rawById.get(o.id);
-    const text = o.kind === "text" ? overlayPlainText(o) : o.kind === "html" ? void 0 : o.key;
+    const text = o.kind === "text" ? overlayPlainText2(o) : o.kind === "html" ? void 0 : o.key;
     return [
       {
         id: o.id,
@@ -19328,7 +19391,8 @@ async function cmdPlan(argvIn) {
   const zoomManual = s.doc.zoom.length - zoomAuto;
   const captionLines = captions ? `
   ${captions.landed.length} step caption${captions.landed.length === 1 ? "" : "s"} anchored to their steps` + (captions.skipped.length ? `
-  not landed: ${captions.skipped.join("; ")}` : "") + (captions.uncaptioned.length ? `
+  not landed: ${captions.skipped.join("; ")}` : "") + (captions.held.length ? `
+  ${captions.held.join("\n  ")}` : "") + (captions.uncaptioned.length ? `
   no step in ${captions.uncaptioned.length === 1 && captions.uncaptioned[0] === "" ? "this take" : captions.uncaptioned.map((m) => m ? `media ${m}` : "the primary").join(", ")} carries a caption` : "") : "";
   const layoutLines = s.layout ? `
   layout from ${s.styleFrom}: ${[
@@ -19339,7 +19403,8 @@ async function cmdPlan(argvIn) {
     ${s.layout.notes.join("\n    ")}` : "") : "";
   const motionLines = s.motion ? (s.motion.notes.length ? `
   proposed: ${s.motion.notes.join(", ")}` : "") + (s.motion.skipped.length ? `
-  not proposed: ${s.motion.skipped.join("; ")}` : "") : "";
+  not proposed: ${s.motion.skipped.join("; ")}` : "") + (s.motion.held.length ? `
+  ${s.motion.held.join("\n  ")}` : "") : "";
   const reuseLines = s.reuse ? `
   reused ${s.reuse.from}: ${s.reuse.anchored} anchored + ${s.reuse.mapped} mapped span(s)` + (s.reuse.flagged.length ? `
   flagged:
@@ -20617,4 +20682,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-S3RI2SHH.js.map
+//# sourceMappingURL=chunk-5VGIQKVT.js.map