@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Anay Dhawan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,63 @@
+# @openvidstudio/mcp-server
+
+Code-based video generation. An MCP server that lets an AI coding agent make a video of your real
+product: a real browser captures your app, and the agent plans, narrates, scores and renders the
+video on your machine. Every frame of your product is a real capture, never a generated mockup.
+
+## Three kinds of video
+
+- **Demos of your product.** The agent opens your running app, films what it does, and cuts the clips
+  to a plan you approve first. A browser, a desktop app, a phone or a terminal.
+- **Director mode.** Ask for the peak or mid creative level and the agent writes a brief before it
+  builds anything, then moves the camera on purpose, picks a transition for every cut and scores the
+  film with original music that has no drums.
+- **Lessons (Supernova).** One maths, physics or computer science concept in up to two minutes,
+  vertical, always in the same seven beats, with formulas built line by line.
+
+## Install
+
+Add the server to your MCP client's config and restart the client. For Claude Code that is
+`.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "openvidstudio": {
+      "command": "npx",
+      "args": ["-y", "@openvidstudio/mcp-server"]
+    }
+  }
+}
+```
+
+On native Windows some clients need the command wrapped: `"command": "cmd"` with
+`"args": ["/c", "npx", "-y", "@openvidstudio/mcp-server"]`.
+
+Then ask your agent to run `preflight`. It checks your machine and names the fix for anything that is
+missing.
+
+## What you need
+
+| What | Minimum | Needed for |
+| --- | --- | --- |
+| Node.js | 20 | Runs the server |
+| ffmpeg | 4.0 | Sound effects, audio checks, pulling frames back out of a render |
+| Chromium (via Playwright) | current | The browser capture drives |
+| Your app, running | reachable URL | Demos and director mode. A lesson needs no app |
+| edge-tts | 7.3 or newer, Python 3.8+ | Narration. Required for lessons |
+| numpy, scipy, soundfile, pyloudnorm, matplotlib | current, Python 3.8+ | `compose_score`, the original-score tool |
+
+## Documentation
+
+The pipeline docs ship in this package (`docs/`) and are online at
+https://openvidstudio.vercel.app/docs. Start with `OVERVIEW.md`; `SUPERNOVA.md` and `SCRIPT.md` cover
+lessons, and `TOOLS.md` lists every tool.
+
+- Source, issues and the changelog: https://github.com/AnayDhawan/openvidstudio
+- Site: https://openvidstudio.vercel.app
+
+## License
+
+Apache-2.0 for openvidstudio's own code. Videos render through Remotion, which has its own license:
+free for individuals, non-profits, evaluation use and for-profit companies with up to three employees.
+A larger company needs a Remotion Company License: https://www.remotion.pro/license

package/dist/api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The programmatic surface.
+ *
+ * Everything here is also an MCP tool, and an agent should reach it that way. This exists
+ * for the cases where there is no agent in the loop: a CI job diffing a render against the
+ * last accepted one, a cron job checking whether a docs clip still matches its page. Those
+ * want a function, not a stdio protocol handshake.
+ *
+ * Deliberately a short list rather than everything: the tools that draft, scaffold, or
+ * write a manifest are the ones that need an agent's judgement and a human's approval, and
+ * exposing them here would be inviting a script to skip both.
+ */
+export { runVisualRegression, buildRegressionMarkdown } from "./tools/visualRegression";
+export type { VisualRegressionInput, VisualRegressionResult, BeatRegression } from "./tools/visualRegression";
+export { runDocsDrift, inferBindings } from "./tools/docsDrift";
+export type { DocsDriftInput, DocsDriftResult, DriftFinding, DriftBinding } from "./tools/docsDrift";
+export { runRenderVideo } from "./tools/renderVideo";
+export type { RenderVideoInput, RenderVideoResult } from "./tools/renderVideo";
+export { runExportRendition, STORE_DEVICES } from "./tools/exportRendition";
+export type { ExportRenditionInput, ExportRenditionResult } from "./tools/exportRendition";
+export { runReformatVertical } from "./tools/reformatVertical";
+export type { ReformatVerticalInput, ReformatVerticalResult } from "./tools/reformatVertical";
+export { runPlanShots } from "./tools/planShots";
+export type { PlanShotsInput, PlanShotsResult, ShotCandidate } from "./tools/planShots";
+export { runReleaseDiff } from "./tools/releaseDiff";
+export type { ReleaseDiffInput, ReleaseDiffResult, RouteChange } from "./tools/releaseDiff";
+export { compareFrames, judgeDrift } from "./frameDiff";
+export type { FrameComparison, DriftVerdict } from "./frameDiff";

package/dist/api.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.judgeDrift = exports.compareFrames = exports.runReleaseDiff = exports.runPlanShots = exports.runReformatVertical = exports.STORE_DEVICES = exports.runExportRendition = exports.runRenderVideo = exports.inferBindings = exports.runDocsDrift = exports.buildRegressionMarkdown = exports.runVisualRegression = void 0;
+/**
+ * The programmatic surface.
+ *
+ * Everything here is also an MCP tool, and an agent should reach it that way. This exists
+ * for the cases where there is no agent in the loop: a CI job diffing a render against the
+ * last accepted one, a cron job checking whether a docs clip still matches its page. Those
+ * want a function, not a stdio protocol handshake.
+ *
+ * Deliberately a short list rather than everything: the tools that draft, scaffold, or
+ * write a manifest are the ones that need an agent's judgement and a human's approval, and
+ * exposing them here would be inviting a script to skip both.
+ */
+var visualRegression_1 = require("./tools/visualRegression");
+Object.defineProperty(exports, "runVisualRegression", { enumerable: true, get: function () { return visualRegression_1.runVisualRegression; } });
+Object.defineProperty(exports, "buildRegressionMarkdown", { enumerable: true, get: function () { return visualRegression_1.buildRegressionMarkdown; } });
+var docsDrift_1 = require("./tools/docsDrift");
+Object.defineProperty(exports, "runDocsDrift", { enumerable: true, get: function () { return docsDrift_1.runDocsDrift; } });
+Object.defineProperty(exports, "inferBindings", { enumerable: true, get: function () { return docsDrift_1.inferBindings; } });
+var renderVideo_1 = require("./tools/renderVideo");
+Object.defineProperty(exports, "runRenderVideo", { enumerable: true, get: function () { return renderVideo_1.runRenderVideo; } });
+var exportRendition_1 = require("./tools/exportRendition");
+Object.defineProperty(exports, "runExportRendition", { enumerable: true, get: function () { return exportRendition_1.runExportRendition; } });
+Object.defineProperty(exports, "STORE_DEVICES", { enumerable: true, get: function () { return exportRendition_1.STORE_DEVICES; } });
+var reformatVertical_1 = require("./tools/reformatVertical");
+Object.defineProperty(exports, "runReformatVertical", { enumerable: true, get: function () { return reformatVertical_1.runReformatVertical; } });
+var planShots_1 = require("./tools/planShots");
+Object.defineProperty(exports, "runPlanShots", { enumerable: true, get: function () { return planShots_1.runPlanShots; } });
+var releaseDiff_1 = require("./tools/releaseDiff");
+Object.defineProperty(exports, "runReleaseDiff", { enumerable: true, get: function () { return releaseDiff_1.runReleaseDiff; } });
+var frameDiff_1 = require("./frameDiff");
+Object.defineProperty(exports, "compareFrames", { enumerable: true, get: function () { return frameDiff_1.compareFrames; } });
+Object.defineProperty(exports, "judgeDrift", { enumerable: true, get: function () { return frameDiff_1.judgeDrift; } });

package/dist/audioTick.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Finds a ticking-clock pattern in audio: short high-frequency bursts that repeat evenly.
+ * A hat on every off-beat, a tick on every beat, or a pluck that never rests all sound like
+ * a clock under a voiceover, whatever instrument plays them.
+ *
+ * The audio is decoded to mono, high-passed at 5 kHz, and turned into a 1 ms RMS envelope.
+ * The slow trend (a 100 ms moving average: decays, section changes, speech phrasing) is
+ * removed so only fast bursts are left, and the envelope's autocorrelation is read at lags
+ * of 150 to 800 ms, which covers a tick every beat or every eighth note from about 75 to 400
+ * bpm. Measured on real files: clean beds and narrated videos score 0.03 to 0.18, a hat and
+ * tick grid scores 0.4 to 0.99.
+ *
+ * compose-score.py runs the same measurement on its own mix (hf_periodicity), so a score is
+ * checked when it is made and the final audio is checked again when the video is finalized.
+ */
+export declare const TICK_LAG_MIN_MS = 150;
+export declare const TICK_LAG_MAX_MS = 800;
+export declare const TICK_THRESHOLD = 0.3;
+export interface AudioTickResult {
+    /** Strongest normalized autocorrelation of the high-frequency envelope between the two lags. */
+    peak: number;
+    /** The lag of that peak in milliseconds, or null when the audio was too short to measure. */
+    lagMs: number | null;
+    verdict: "ok" | "periodic";
+    thresholdPeak: number;
+    note?: string;
+}
+/** Pure analysis of audio that has already been high-passed at 5 kHz. */
+export declare function analyzeTickEnvelope(samples: Float32Array, sampleRate: number): AudioTickResult;
+/** Decodes a media file's audio through ffmpeg and measures it. Returns null when there is no audio to read. */
+export declare function measureAudioTick(file: string, cwd?: string): Promise<AudioTickResult | null>;
+/** One plain sentence for a finalize_video note, or null when nothing was found. */
+export declare function describeTick(r: AudioTickResult | null): string | null;

package/dist/audioTick.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TICK_THRESHOLD = exports.TICK_LAG_MAX_MS = exports.TICK_LAG_MIN_MS = void 0;
+exports.analyzeTickEnvelope = analyzeTickEnvelope;
+exports.measureAudioTick = measureAudioTick;
+exports.describeTick = describeTick;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Finds a ticking-clock pattern in audio: short high-frequency bursts that repeat evenly.
+ * A hat on every off-beat, a tick on every beat, or a pluck that never rests all sound like
+ * a clock under a voiceover, whatever instrument plays them.
+ *
+ * The audio is decoded to mono, high-passed at 5 kHz, and turned into a 1 ms RMS envelope.
+ * The slow trend (a 100 ms moving average: decays, section changes, speech phrasing) is
+ * removed so only fast bursts are left, and the envelope's autocorrelation is read at lags
+ * of 150 to 800 ms, which covers a tick every beat or every eighth note from about 75 to 400
+ * bpm. Measured on real files: clean beds and narrated videos score 0.03 to 0.18, a hat and
+ * tick grid scores 0.4 to 0.99.
+ *
+ * compose-score.py runs the same measurement on its own mix (hf_periodicity), so a score is
+ * checked when it is made and the final audio is checked again when the video is finalized.
+ */
+exports.TICK_LAG_MIN_MS = 150;
+exports.TICK_LAG_MAX_MS = 800;
+exports.TICK_THRESHOLD = 0.3;
+const TREND_WINDOW_MS = 100;
+const MIN_SECONDS = 2;
+const ANALYSIS_RATE = 32000;
+/** Pure analysis of audio that has already been high-passed at 5 kHz. */
+function analyzeTickEnvelope(samples, sampleRate) {
+    const base = { thresholdPeak: exports.TICK_THRESHOLD };
+    if (samples.length < sampleRate * MIN_SECONDS) {
+        return { ...base, peak: 0, lagMs: null, verdict: "ok", note: "shorter than two seconds, not measured" };
+    }
+    const block = Math.max(1, Math.round(sampleRate / 1000));
+    const n = Math.floor(samples.length / block);
+    const env = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        let sum = 0;
+        const from = i * block;
+        for (let j = 0; j < block; j++) {
+            const v = samples[from + j];
+            sum += v * v;
+        }
+        env[i] = Math.sqrt(sum / block);
+    }
+    // Detrend with a centered moving average, using prefix sums.
+    const prefix = new Float64Array(n + 1);
+    for (let i = 0; i < n; i++)
+        prefix[i + 1] = prefix[i] + env[i];
+    const half = Math.floor(TREND_WINDOW_MS / 2);
+    const detrended = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const lo = Math.max(0, i - half);
+        const hi = Math.min(n, i + half);
+        detrended[i] = env[i] - (prefix[hi] - prefix[lo]) / (hi - lo);
+    }
+    let energy = 0;
+    for (let i = 0; i < n; i++)
+        energy += detrended[i] * detrended[i];
+    if (energy <= 1e-18)
+        return { ...base, peak: 0, lagMs: null, verdict: "ok", note: "silent in the measured band" };
+    const maxLag = Math.min(exports.TICK_LAG_MAX_MS, n - 1);
+    let best = -Infinity;
+    let bestLag = exports.TICK_LAG_MIN_MS;
+    for (let lag = exports.TICK_LAG_MIN_MS; lag <= maxLag; lag++) {
+        let acc = 0;
+        for (let i = 0; i + lag < n; i++)
+            acc += detrended[i] * detrended[i + lag];
+        const r = acc / energy;
+        if (r > best) {
+            best = r;
+            bestLag = lag;
+        }
+    }
+    const peak = Number(best.toFixed(3));
+    return { ...base, peak, lagMs: bestLag, verdict: peak >= exports.TICK_THRESHOLD ? "periodic" : "ok" };
+}
+/** Decodes a media file's audio through ffmpeg and measures it. Returns null when there is no audio to read. */
+function measureAudioTick(file, cwd) {
+    return new Promise((resolve, reject) => {
+        const args = [
+            "-nostdin", "-v", "error", "-i", file, "-vn", "-ac", "1", "-ar", String(ANALYSIS_RATE),
+            "-af", "highpass=f=5000:poles=2,highpass=f=5000:poles=2",
+            "-f", "f32le", "-",
+        ];
+        const child = (0, node_child_process_1.spawn)("ffmpeg", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const chunks = [];
+        let stderr = "";
+        child.stdout.on("data", (c) => chunks.push(c));
+        child.stderr.on("data", (c) => {
+            stderr += c.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            // A file with no audio stream makes ffmpeg exit non-zero with "does not contain any stream".
+            if (code !== 0 && /does not contain any stream|matches no streams/i.test(stderr))
+                return resolve(null);
+            if (code !== 0)
+                return reject(new Error(`ffmpeg could not decode the audio for the tick check:\n${stderr.slice(-600)}`));
+            const buf = Buffer.concat(chunks);
+            if (buf.length < 4)
+                return resolve(null);
+            // slice() copies into a fresh, 4-byte aligned ArrayBuffer; a pooled Buffer may not be aligned.
+            const aligned = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.length - (buf.length % 4));
+            resolve(analyzeTickEnvelope(new Float32Array(aligned), ANALYSIS_RATE));
+        });
+    });
+}
+/** One plain sentence for a finalize_video note, or null when nothing was found. */
+function describeTick(r) {
+    if (!r || r.verdict !== "periodic")
+        return null;
+    return (`Warning (audio-tick): short high-frequency hits repeat about every ${r.lagMs} ms ` +
+        `(autocorrelation ${r.peak}, threshold ${r.thresholdPeak}). It will sound like a ticking clock under the voiceover. ` +
+        `Use a bed without hats or ticks (compose_score defaults to none), or give the pattern rests.`);
+}

package/dist/beats.d.ts

@@ -6,8 +6,18 @@
  * the whole point of validation is to not assume this shape holds yet.
  */
 import type { z } from "zod";
-import type { interactionSchema } from "./capture";
-export type CaptureMethod = "screenshot" | "recording" | "dom-demo" | "higgsfield";
+import type { interactionSchema } from "@openvidstudio/capture";
+export type CaptureMethod = "screenshot" | "recording" | "dom-demo" | "higgsfield" | "existing-asset";
+/**
+ * Where a captured beat's footage comes from.
+ *
+ * `browser` is the original and remains the default when the field is absent, so every
+ * beats.json written before this existed stays valid and unchanged. The other three
+ * exist because Playwright can only drive a web page: a desktop application, a phone,
+ * and a terminal each have real, filmable software behind them and no URL, which is why
+ * beats about them used to collapse into hand-drawn `dom-demo` panels.
+ */
+export type CaptureSource = "browser" | "desktop" | "mobile" | "terminal";
 /**
  * Derived from capture.ts's `interactionSchema` (the zod discriminated union
  * capture_screenshot/capture_screen_recording actually enforce at replay time), via
@@ -19,10 +29,78 @@ export type CaptureMethod = "screenshot" | "recording" | "dom-demo" | "higgsfiel
  * capture.ts (or its playwright import) is introduced by this type alias.
  */
 export type Interaction = z.infer<typeof interactionSchema>;
+/** A browser capture. `source` may be omitted entirely, since "browser" is the default. */
 export interface CaptureVisual {
     captureMethod: "screenshot" | "recording";
+    source?: "browser";
     url: string;
     interactions: Interaction[];
+    /**
+     * Settle before capturing (fonts/images/finite-animations). Default true, matching
+     * capture_screenshot/capture_screen_recording's own default. A beat with a deliberately
+     * long entrance can carry its own budget here instead of it only living in the tool call
+     * that captures it, where nobody reading beats.json would see it.
+     */
+    settle?: boolean;
+    /** Budget for the settle wait above, in ms. Default 5000 (capture package's DEFAULT_SETTLE_TIMEOUT_MS). */
+    settleTimeoutMs?: number;
+    /**
+     * Navigation wait condition. Default "load", matching capture_screenshot/
+     * capture_screen_recording's own default (a dev server's open websocket never reaches
+     * "networkidle"). Set "networkidle" on a beat whose real content arrives from a delayed
+     * fetch after "load" already fired.
+     */
+    waitUntil?: "load" | "networkidle";
+    /**
+     * Emulate a color scheme. Omit for the page's own default. Matches
+     * capture_screenshot/capture_screen_recording's own colorScheme, set at context creation.
+     */
+    colorScheme?: "light" | "dark";
+    /** Emulate prefers-reduced-motion: reduce. Off by default. */
+    reducedMotion?: boolean;
+    /**
+     * Freeze Date.now()/new Date() and seed Math.random() for this capture. Default false.
+     * Matches capture_screenshot/capture_screen_recording's own deterministic flag -- does not
+     * fix animation-phase nondeterminism, only clock/RNG-derived content.
+     */
+    deterministic?: boolean;
+}
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A desktop app, a single window, or a whole display. Recorded by capture_desktop. */
+export interface DesktopVisual {
+    captureMethod: "recording";
+    source: "desktop";
+    /** Window title. Omit to record the whole display. */
+    window?: string;
+    region?: Region;
+    display?: number;
+    durationSeconds: number;
+}
+/** A real phone or simulator. Recorded by capture_mobile. */
+export interface MobileVisual {
+    captureMethod: "recording";
+    source: "mobile";
+    device: "android" | "ios-simulator";
+    deviceId?: string;
+    durationSeconds: number;
+}
+/** A real command run, recorded as timed text rather than pixels. See capture_terminal. */
+export interface TerminalVisual {
+    captureMethod: "recording";
+    source: "terminal";
+    command: string;
+    args?: string[];
+    cwd?: string;
+    script?: {
+        type: "type" | "wait";
+        text?: string;
+        ms?: number;
+    }[];
 }
 export interface DomDemoVisual {
     captureMethod: "dom-demo";
@@ -31,17 +109,62 @@ export interface HiggsfieldVisual {
     captureMethod: "higgsfield";
     higgsfieldPrompt: string;
 }
-export type Visual = CaptureVisual | DomDemoVisual | HiggsfieldVisual;
+/**
+ * A real asset the project already published, that this pipeline did not capture.
+ *
+ * Plenty of projects ship genuine screenshots of themselves (a docs site's images, a
+ * manual's figures). Before this existed there was no way to put one on screen: the
+ * capture methods all mean "film it now", so a real, existing image had to masquerade
+ * as a hand-drawn `dom-demo`. `attribution` is required because the honesty rules only
+ * hold if the video can say where a frame came from.
+ */
+export interface ExistingAssetVisual {
+    captureMethod: "existing-asset";
+    assetPath: string;
+    attribution: string;
+}
+export type Visual = CaptureVisual | DesktopVisual | MobileVisual | TerminalVisual | DomDemoVisual | HiggsfieldVisual | ExistingAssetVisual;
+/**
+ * The way into a beat. Everything but "cut" is drawn by core's TransitionOverlay on top of
+ * the hard cut, so no beat boundary moves (PLANNING.md §4.5).
+ */
+export type Transition = "cut" | "whip" | "fade" | "push" | "wipe" | "light-leak";
+/**
+ * Explicit named references to this beat's on-disk outputs. Every tool already agrees on
+ * the convention path (PIPELINE.md's Asset conventions table: public/images/<id>.png,
+ * public/video/<id>.mp4, public/audio/vo/<id>.mp3), and capture_screenshot /
+ * capture_screen_recording already accept an outPath override and report it back -- this
+ * field is what makes that override, and the resulting path, visible on the manifest
+ * itself instead of only in a tool call's return value. All optional: omit a key and the
+ * convention path is assumed.
+ */
+export interface Artifacts {
+    screenshotPath?: string;
+    recordingPath?: string;
+    voPath?: string;
+    /** capture_terminal's JSON cast, default public/terminal/<beatId>.json. */
+    terminalPath?: string;
+}
 export interface Beat {
     id: string;
     start: number;
     duration: number;
     vo: string;
     visual: Visual;
+    /** Cut if omitted, matching current SFX defaults (PIPELINE.md §2). */
+    transition?: Transition;
+    artifacts?: Artifacts;
 }
 export interface BeatsFile {
     /** 30fps assumed if omitted, per PLANNING.md / PIPELINE.md. */
     fps?: number;
     title: string;
+    /**
+     * "default" assumed if omitted. One of SCRIPT.md's Tone section presets (default,
+     * release, walkthrough, quiet) or a project-specific label; not enforced by any tool,
+     * it exists so every beat's VO gets written in the same register instead of drifting
+     * line to line across a multi-session video. See PLANNING.md §7.
+     */
+    tone?: string;
     beats: Beat[];
 }