fablecut 1.12.0 → 1.13.0

package/color.js

@@ -42,16 +42,20 @@
      layers: [{ name?, on?, qualifier?, mask?, …grade keys }]
      qualifier: { hue?: [centre°, width°, soft°], sat?: [lo, hi, soft],
                   luma?: [lo, hi, soft], invert? }   — measured on the layer's input
-     mask: { shape: ellipse | rect | poly, x, y (centre, 0…1 of the picture),
+     mask: { shape: ellipse | rect | poly | bezier, x, y (centre, 0…1 of the picture),
              w, h (size, 0…1), rotation°, feather (0…0.5 of the height),
              invert?, points?: [[dx, dy], …] (poly, relative to x, y),
+             bezier: [[dx, dy, inX?, inY?, outX?, outY?], …] — anchors with
+             handles, the outline mask.js draws (a free-hand stroke,
+             { shape: "freehand", stroke: [[u, v], …] }, is fitted into one),
              keys?: [{ t, ease?, x?, y?, w?, h?, rotation?, feather? }] }
    matte = qualifier × mask (each 1 when absent); out = mix(in, graded, matte). */
 (function (root, factory) {
-  const api = factory();
-  if (typeof module === "object" && module.exports) module.exports = api;
+  const node = typeof module === "object" && module.exports;
+  const api = factory(node ? require("./mask") : root.FableCutMask);
+  if (node) module.exports = api;
   else root.FableCutColor = api;
-})(typeof self !== "undefined" ? self : this, function () {
+})(typeof self !== "undefined" ? self : this, function (MaskLib) {
   "use strict";
 
   const WHEELS = ["lift", "gamma", "gain", "offset"];
@@ -91,7 +95,9 @@
   const HUE_N = 360;          // hue-curve lookup-table size (also sat 0…1 for satLuma)
   const MAX_LAYERS = 8;
   const MAX_POLY = 16;
-  const MASK_SHAPES = ["ellipse", "rect", "poly"];
+  const MAX_BEZIER = 24;      // bezier anchors on a grade mask
+  const MAX_OUTLINE = 96;     // the flattened outline the shader walks
+  const MASK_SHAPES = ["ellipse", "rect", "poly", "bezier"];
   const MASK_KEYED = ["x", "y", "w", "h", "rotation", "feather"];
   const KEY_RANGE = { x: [-1, 2], y: [-1, 2], w: [0.001, 4], h: [0.001, 4], rotation: [-720, 720], feather: [0, 0.5] };
   const WB_STOPS = 1 / 100;   // temp / tint ±100 → ±1 stop per channel
@@ -487,6 +493,12 @@
     if (m == null) return null;
     const bad = (msg) => { if (strict) throw new Error(`${where}.mask${msg}`); return null; };
     if (typeof m !== "object" || Array.isArray(m)) return bad(" must be {shape, x, y, w, h, rotation?, feather?, invert?}");
+    if (m.shape === "freehand") {
+      if (!Array.isArray(m.stroke) || m.stroke.length < 3 || m.stroke.some((p) => !Array.isArray(p) || !isNum(p[0]) || !isNum(p[1])))
+        return bad(".stroke must be at least 3 [u, v] points (fractions of the picture)");
+      m = { ...m, ...MaskLib.fitStroke(m.stroke, m.aspect, MAX_BEZIER), shape: "bezier" };
+      delete m.stroke; delete m.aspect;
+    }
     const shape = m.shape == null ? "ellipse" : m.shape;
     if (!MASK_SHAPES.includes(shape)) return bad(`.shape must be ${MASK_SHAPES.join(" | ")}`);
     for (const k of Object.keys(m)) if (![...MASK_KEYED, "shape", "invert", "points", "keys"].includes(k)) bad(`.${k}: unknown key`);
@@ -509,6 +521,11 @@
       if (!Array.isArray(pts) || pts.length < 3 || pts.length > MAX_POLY || pts.some((p) => !Array.isArray(p) || p.length !== 2 || !p.every(isNum)))
         return bad(`.points must be 3…${MAX_POLY} [dx, dy] pairs around x, y (fractions of the picture)`);
       out.points = pts.map(([a, b]) => [+clamp(a, -2, 2).toFixed(4), +clamp(b, -2, 2).toFixed(4)]);
+    } else if (shape === "bezier") {
+      const pts = m.points;
+      if (!Array.isArray(pts) || pts.length < 3 || pts.length > MAX_BEZIER || pts.some((p) => !Array.isArray(p) || (p.length !== 2 && p.length !== 6) || !p.every(isNum)))
+        return bad(`.points must be 3…${MAX_BEZIER} anchors [dx, dy] or [dx, dy, inX, inY, outX, outY] around x, y (fractions of the picture)`);
+      out.points = pts.map((p) => p.map((v) => +clamp(v, -2, 2).toFixed(4)));
     }
     if (m.keys != null) {
       if (!Array.isArray(m.keys)) return bad(".keys must be a list of {t, x?, y?, w?, h?, rotation?, feather?}");
@@ -596,10 +613,26 @@
       const qx = Math.abs(px) - rx, qy = Math.abs(py) - ry;
       return Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) + Math.min(Math.max(qx, qy), 0);
     }
-    if (m.shape === "poly") return polyDist(m.points.map(([a, b]) => [a * aspect, b]), px, py);
+    if (m.shape === "poly" || m.shape === "bezier") return polyDist(outlineAt(m, aspect), px, py);
     const k0 = Math.hypot(px / rx, py / ry), k1 = Math.hypot(px / (rx * rx), py / (ry * ry));
     return k0 < 1e-6 ? -Math.min(rx, ry) : k0 * (k0 - 1) / k1;
   }
+  /** A bezier mask's outline as a polygon around its centre (fractions of the
+   *  picture, unrotated) — at most MAX_OUTLINE corners, the shader's budget. */
+  /** The poly / bezier outline in aspect-scaled units, cached per points array — the CPU path asks per pixel. */
+  const outlines = new WeakMap();
+  function outlineAt(m, aspect) {
+    let o = outlines.get(m.points);
+    if (!o || o.aspect !== aspect) {
+      o = { aspect, pts: (m.shape === "bezier" ? bezierOutline(m) : m.points).map(([a, b]) => [a * aspect, b]) };
+      outlines.set(m.points, o);
+    }
+    return o.pts;
+  }
+  function bezierOutline(m) {
+    const A = MaskLib.anchors({ shape: "bezier", x: 0, y: 0, scale: 1, rotation: 0, points: m.points }, 1, 1);
+    return MaskLib.flatten(A, Math.max(1, Math.min(16, Math.floor(MAX_OUTLINE / A.length))));
+  }
   function polyDist(pts, px, py) {
     let d = (px - pts[0][0]) ** 2 + (py - pts[0][1]) ** 2, s = 1;
     for (let i = 0, j = pts.length - 1; i < pts.length; j = i, i++) {
@@ -757,10 +790,10 @@
       u.uMRot = m ? m.rotation * Math.PI / 180 : 0;
       u.uMFeather = m ? Math.max(0.002, m.feather) : 0.002;
       u.uMInv = m && m.invert ? 1 : 0;
-      const pts = new Float32Array(MAX_POLY * 2);
-      if (m && m.points) m.points.forEach(([a, b], i) => { pts[i * 2] = a; pts[i * 2 + 1] = b; });
+      const pts = new Float32Array(MAX_OUTLINE * 2), P = m && m.points ? (m.shape === "bezier" ? bezierOutline(m) : m.points) : [];
+      P.forEach(([a, b], i) => { pts[i * 2] = a; pts[i * 2 + 1] = b; });
       u.uMPts = pts;
-      u.uMN = m && m.points ? m.points.length : 0;
+      u.uMN = P.length;
       passes.push(u);
     }
     return passes;
@@ -800,10 +833,10 @@ uniform int uLayer, uMatte, uPremul;   // layer pass: mix by its matte · show t
 uniform int uQOn, uQInv;
 uniform ivec3 uQUse;                   // hue, sat, luma ranges in use
 uniform vec3 uQHue, uQSat, uQLuma;     // hue: centre, half width, soft (turns) · sat / luma: low, high, soft
-uniform int uMShape, uMInv, uMN;       // 0 none · 1 ellipse · 2 rect · 3 poly
+uniform int uMShape, uMInv, uMN;       // 0 none · 1 ellipse · 2 rect · 3 poly · 4 bezier (flattened)
 uniform vec2 uMC, uMW;
 uniform float uMRot, uMFeather, uAspect;
-uniform vec2 uMPts[${MAX_POLY}];
+uniform vec2 uMPts[${MAX_OUTLINE}];
 in vec2 vPos;
 out vec4 outColor;
 vec4 lutAt(sampler2D t, int n, float x) {
@@ -862,10 +895,10 @@ float maskDist(vec2 uv) {
     vec2 q = abs(p) - r;
     return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0);
   }
-  if (uMShape == 3) {
+  if (uMShape >= 3) {
     vec2 v0 = uMPts[0] * vec2(uAspect, 1.0);
     float dd = dot(p - v0, p - v0), s = 1.0;
-    for (int i = 0; i < ${MAX_POLY}; i++) {
+    for (int i = 0; i < ${MAX_OUTLINE}; i++) {
       if (i >= uMN) break;
       int j = i == 0 ? uMN - 1 : i - 1;
       vec2 vi = uMPts[i] * vec2(uAspect, 1.0), vj = uMPts[j] * vec2(uAspect, 1.0);
@@ -1034,7 +1067,7 @@ void main() {
     GRADE_PARAMS, GRADE_KEYS, WHEELS, GRADE_VERT, GRADE_FRAG, SKIN_ANGLE,
     CURVE_CHANNELS, HUE_CURVES, HUE_KEYS, CURVE_N, HUE_N, BAND,
     normalizeGrade, fullGrade, isNeutral, mergeGrade, summarizeGrade, withoutCurves,
-    MAX_LAYERS, MAX_POLY, MASK_SHAPES, MASK_KEYED, mergeLayer, layerGrade, maskAt, gradeAt, qualAlpha, maskAlpha, maskDist, gradePasses,
+    MAX_LAYERS, MAX_POLY, MAX_BEZIER, MASK_SHAPES, MASK_KEYED, mergeLayer, layerGrade, maskAt, gradeAt, qualAlpha, maskAlpha, maskDist, gradePasses,
     monotone, curveFn, rgbToHsv, hsvToRgb,
     wbGains, solveWhiteBalance, srgbToLinear, linearToSrgb, wheelToRgb, rgbToWheel, ycbcr,
     prepareGrade, gradePixel, gradeImageData, gradeUniforms,

package/edit-ops.js

@@ -19,10 +19,11 @@
    `forDoc(doc, opts)` builds the env from the document itself (its tracks,
    lockedTracks and untargetedTracks) for headless callers. */
 (function (root, factory) {
-  const api = factory();
-  if (typeof module === "object" && module.exports) module.exports = api;
+  const node = typeof module === "object" && module.exports;
+  const api = factory(node ? require("./mask") : root.FableCutMask, node ? require("./tracker") : root.FableCutTracker);
+  if (node) module.exports = api;
   else root.FableCutEdit = api;
-})(typeof self !== "undefined" ? self : this, function () {
+})(typeof self !== "undefined" ? self : this, function (MaskLib, TrackLib) {
   "use strict";
 
   const MIN_DUR = 0.05;
@@ -92,6 +93,20 @@
     }
     return Object.keys(out).length ? out : undefined;
   }
+  /** A clip's head moved by `offset` s: its mask keys and track samples follow, like shiftKF does for keyframes. */
+  function shiftMasks(c, offset) {
+    if (!offset || !c.props) return;
+    const ms = c.props.masks, ts = c.props.tracks;
+    if (MaskLib && Array.isArray(ms)) {
+      const next = MaskLib.shiftKeys(ms, offset);
+      if (next !== ms) c.props = { ...c.props, masks: next };
+    }
+    if (TrackLib && Array.isArray(ts)) {
+      const next = TrackLib.shiftTracks(ts, offset);
+      c.props = { ...c.props };
+      if (next.length) c.props.tracks = next; else delete c.props.tracks;
+    }
+  }
   /** Default stereo pan for an isolated linked stem (L −1, R +1, else center). */
   function defaultPanForChannel(ch) {
     if (ch === 0) return -1;
@@ -190,6 +205,7 @@
         linkedId: undefined,
         linkGroup: undefined,
       };
+      shiftMasks(right, cut);
       c.duration = cut;
       c.keyframes = shiftKF(c.keyframes, 0, cut);
       c.transitionOut = undefined;
@@ -274,6 +290,7 @@
           else c.in = 0;
           c.duration -= dIn;
           c.keyframes = shiftKF(c.keyframes, dIn, c.duration);
+          shiftMasks(c, dIn);
           c.transitionIn = undefined;
           changed++;
         }
@@ -559,6 +576,7 @@
               c.start = +t1.toFixed(4);
               c.transitionIn = undefined;
               c.keyframes = shiftKF(c.keyframes, t1 - oldStart, c.duration);
+              shiftMasks(c, t1 - oldStart);
             } else {
               // Stubs on both sides → effectively inside the window.
               drop(c);
@@ -595,6 +613,7 @@
           c.start = +t1.toFixed(4);
           c.transitionIn = undefined;
           c.keyframes = shiftKF(c.keyframes, t1 - oldStart, c.duration);
+          shiftMasks(c, t1 - oldStart);
         }
       }
     }
@@ -710,6 +729,7 @@
         if (isMediaClip(x)) x.in = +(x.in + d * clipSpeed(x)).toFixed(4);
         x.duration = +(x.duration - d).toFixed(4);
         x.keyframes = shiftKF(x.keyframes, d, x.duration);
+        shiftMasks(x, d);
         clampTransitions(x);
       }
     }
@@ -885,6 +905,7 @@
           x.in = +Math.max(0, x.in - e2 * sp).toFixed(4);
           x.duration = +(x.duration + e2).toFixed(4);
           x.keyframes = shiftKF(x.keyframes, -e2, x.duration);
+          shiftMasks(x, -e2);
         }
       }
       d = +Math.min(d, a.duration, b.duration).toFixed(3);
@@ -956,7 +977,7 @@
 
   return {
     MIN_DUR, MIN_TRANS_DUR, CROSSFADE_DUR, GAP_EPS, TRIM_LOCKED, DEFAULT_TRACKS,
-    clipEnd, clipSpeed, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, defaultPanForChannel,
+    clipEnd, clipSpeed, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, shiftMasks, defaultPanForChannel,
     create, forDoc,
   };
 });

package/export-jobs.js

@@ -103,14 +103,15 @@ function createExportJobs(opts) {
 
   return {
     /** Queue an export. where: auto (open tab, else headless) · tab · headless.
-     *  kind "scopes" measures one still at `time` instead (fablecut_scopes). */
-    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null }) {
+     *  kind "scopes" measures one still at `time` instead (fablecut_scopes);
+     *  kind "track" follows a region of a clip and saves it (fablecut_track). */
+    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null, mask = null, track = null }) {
       if (!["auto", "tab", "headless"].includes(where)) throw Object.assign(new Error("where must be auto, tab or headless"), { code: 400 });
-      if (kind !== "export" && kind !== "scopes") throw Object.assign(new Error("kind must be export or scopes"), { code: 400 });
+      if (!["export", "scopes", "track"].includes(kind)) throw Object.assign(new Error("kind must be export, scopes or track"), { code: 400 });
       if (time != null && !(Number.isFinite(time) && time >= 0)) throw Object.assign(new Error("time must be seconds ≥ 0"), { code: 400 });
       if (range != null && range !== "entire" && range !== "in-out") throw Object.assign(new Error("range must be \"entire\" or \"in-out\""), { code: 400 });
       const busy = [...jobs.values()].find((j) => !isEnded(j));
-      if (busy) throw Object.assign(new Error(`${busy.kind === "scopes" ? "scope reading" : "export"} ${busy.id} is still ${busy.status} — wait for it, or cancel it`), { code: 409 });
+      if (busy) throw Object.assign(new Error(`${busy.kind === "scopes" ? "scope reading" : busy.kind === "track" ? "tracking job" : "export"} ${busy.id} is still ${busy.status} — wait for it, or cancel it`), { code: 409 });
       const tabs = opts.editors();
       if (where === "tab" && !tabs) throw Object.assign(new Error("no editor tab is open — open the editor, or use where:\"headless\""), { code: 409 });
       const now = Date.now();
@@ -118,6 +119,8 @@ function createExportJobs(opts) {
         id: "x_" + Math.random().toString(36).slice(2, 10), kind, status: "pending", progress: 0,
         range: range || null, profile: profile || null, time: time ?? null, revision: Number.isFinite(revision) ? revision : null,
         matte: kind === "scopes" && matte ? { clip: String(matte.clip), layer: matte.layer } : null,
+        mask: kind === "scopes" && mask ? { clip: String(mask.clip) } : null,
+        track: kind === "track" && track ? track : null,
         via: where === "headless" || (where === "auto" && !tabs) ? "headless" : "tab",
         created: now, updated: now,
       };
@@ -129,7 +132,7 @@ function createExportJobs(opts) {
     },
     get(id) { const j = jobs.get(id); return j ? view(j) : null; },
     /** What a tab needs to run the job (headless pages fetch it by id). */
-    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, status: j.status } : null; },
+    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, mask: j.mask || null, track: j.track || null, status: j.status } : null; },
     /** First tab to claim a pending job runs it. */
     claim(id) {
       const j = jobs.get(id);

package/index.html

@@ -394,14 +394,20 @@
         <tr><td><kbd>Z</kbd></td><td>Zoom to selected clip(s)</td></tr>
         <tr><td><kbd>Alt</kbd>+<kbd>Z</kbd></td><td>Zoom to IN–OUT work area</td></tr>
         <tr><td><kbd>⇧</kbd>+<kbd>Z</kbd></td><td>Zoom timeline to fit</td></tr>
-        <tr><td><kbd>Ctrl</kbd>+<kbd>Z</kbd> / <kbd>Ctrl</kbd>+<kbd>⇧</kbd>+<kbd>Z</kbd></td><td>Undo / redo</td></tr>
+        <tr><td><kbd>Ctrl</kbd>+<kbd>Z</kbd> / <kbd>Ctrl</kbd>+<kbd>⇧</kbd>+<kbd>Z</kbd></td><td>Undo / redo (also <kbd>Ctrl</kbd>+<kbd>Y</kbd>)</td></tr>
         <tr><td><kbd>Ctrl</kbd>+wheel</td><td>Zoom timeline at cursor</td></tr>
         <tr><td>Audio volume line</td><td>Drag to change the level · <kbd>Ctrl/Cmd</kbd>+click adds a keyframe · <kbd>Alt</kbd>+click or double-click removes one · corner grips drag fades</td></tr>
         <tr class="keys-head"><td colspan="2">Color workspace</td></tr>
         <tr><td>Colour wheel</td><td>Drag to tint (<kbd>⇧</kbd> = fine) · double-click resets the colour · double-click a label or slider name to reset it</td></tr>
         <tr><td>WB pick / Pick</td><td>Click the monitor to balance, to mark a colour on the curves, or to select it in a layer's qualifier · <kbd>Esc</kbd> cancels</td></tr>
         <tr><td>Curves</td><td>Click adds a point on the curve · drag moves it · double-click removes it</td></tr>
-        <tr><td>Layer mask on the monitor</td><td>Drag inside to move · handles resize · the knob rotates (<kbd>⇧</kbd> snaps to 15°) · poly: <kbd>Ctrl/Cmd</kbd>+click adds a point, double-click removes one</td></tr>
+        <tr><td>Layer mask on the monitor</td><td>Drag inside to move · handles resize · the knob rotates (<kbd>⇧</kbd> snaps to 15°) · poly / bezier: <kbd>Ctrl/Cmd</kbd>+click adds a point, double-click removes one · <b>Draw</b>: drag a free-hand outline</td></tr>
+        <tr class="keys-head"><td colspan="2">Masks (Inspector → Masks)</td></tr>
+        <tr><td>Pen</td><td>Click to place points, drag while placing to pull curve handles · click the first point or <kbd>Enter</kbd> closes · <kbd>Ctrl</kbd>+<kbd>Z</kbd> / <kbd>Backspace</kbd> removes the last point, <kbd>Ctrl</kbd>+<kbd>⇧</kbd>+<kbd>Z</kbd> puts it back · <kbd>Esc</kbd> cancels</td></tr>
+        <tr><td>Draw</td><td>Drag a free-hand outline — it becomes an editable bezier</td></tr>
+        <tr><td>Mask on the monitor</td><td>Drag inside to move · edge handles resize · the knob rotates (<kbd>⇧</kbd> snaps to 15°) · drag a point or its handles (<kbd>Alt</kbd> breaks the pair) · <kbd>Alt</kbd>+drag a point pulls new handles · <kbd>Ctrl/Cmd</kbd>+click the outline adds a point · double-click a point removes it · <kbd>Esc</kbd> deselects</td></tr>
+        <tr class="keys-head"><td colspan="2">Tracking (Inspector → Tracking, or a mask's Track buttons)</td></tr>
+        <tr><td>Track point</td><td>Click the spot to follow on the monitor — it tracks from the playhead to the clip's end · <kbd>Esc</kbd> cancels the pick, or stops a track that is running (what was tracked so far is kept)</td></tr>
       </table>
     </div>
     <div class="dialog-actions"><button class="btn primary" id="btnCloseHelp">Close</button></div>
@@ -413,6 +419,8 @@
 <script src="loudness.js"></script>
 <script src="ducking.js"></script>
 <script src="audio-fx.js"></script>
+<script src="mask.js"></script>
+<script src="tracker.js"></script>
 <script src="color.js"></script>
 <script src="edit-ops.js"></script>
 <script src="app.js"></script>