@viralspin/mcp 0.4.0 → 0.5.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ViralSpin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ViralSpin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,79 @@
-# ViralSpin MCP — the video editor your AI agent operates
-
-[![MCP Registry](https://img.shields.io/badge/MCP-registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=viralspin)
-[![npm](https://img.shields.io/badge/npm-%40viralspin%2Fmcp-red)](https://www.npmjs.com/package/@viralspin/mcp)
-[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-
-Turn a talking-head clip + a folder of B-roll into a polished vertical short — and **let Claude do the edit**. Point it at your footage in plain English; it transcribes, picks B-roll cutaways matched to what's said, adds captions + a hook, and renders a 9:16 short. Then publishes to TikTok, Instagram, or YouTube. No timeline-wrangling required.
-
-> **The agent operates a real timeline.** Swap a clip, trim it, reorder scenes, cut a span — all by asking. Edits are instant; you render once when the cut is right.
-
-![demo](docs/demo.gif) <!-- TODO: the split-screen "Claude edits, clips stream onto the timeline" clip -->
-
-## Quick start
-
-```bash
-# Claude Code
-claude mcp add viralspin -- npx -y @viralspin/mcp
-
-# or Claude Desktop — add to claude_desktop_config.json:
-{
-  "mcpServers": {
-    "viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }
-  }
-}
-```
-
-Then just ask:
-
-```
-Turn my A-roll at C:/clips/talk.mp4 into a 9:16 short, using B-roll
-from C:/my-broll and my Google Photos.
-
-Publish that to TikTok and Instagram with the caption: posting through the chaos.
-```
-
-## Render a reel on your own computer (`render_locally`)
-
-ViralSpin plans the reel and hands over the media; **your Mac or PC does the draw**, nothing is published, 0 credits.
-
-1. Install Node 20+ (macOS: `brew install node` - Windows: `winget install OpenJS.NodeJS.LTS`) and keep 8 GB of disk free.
-2. Add the server to Claude Desktop (`claude_desktop_config.json`; on Windows use `"command": "npx.cmd"` if `npx` is not found):
-   `"viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }` - no tokens to paste.
-3. Connect once: in a terminal run `npx -y @viralspin/mcp login` (your browser opens, you click **Authorize**). Skipping this is fine too: the first time you ask Claude to render, the browser opens by itself. Credentials live in `~/.viralspin/oauth.json` (Windows: `%USERPROFILE%\.viralspin`), readable only by you, and renew themselves silently for about 30 days of use. `npx -y @viralspin/mcp whoami` / `logout` show / remove them; nothing ever prints a token.
-4. In the ViralSpin app: open a reel's **style picker**, choose **On my computer**, tap **Send to my computer**.
-5. In Claude Desktop say: *"Render my ViralSpin reel"* - with no arguments it picks your newest waiting reel and says which. The first run downloads a ~0.5 GB kit into `~/.viralspin/kit` and Chrome Headless Shell once. The finished reel is uploaded back and shows up in the app; a copy stays in `~/.viralspin/jobs/<id>/`.
-
-Tools: `render_locally` (no arguments, or `job_id`, `render_id`, `request`, `concurrency`, `dry_run`, `complete`, `upload`, `background`) and `render_locally_status` (no arguments lists your waiting / rendering reels).
-If the Chrome download is blocked by antivirus or a proxy the error says so and names the manual step.
-
-## What the agent can do
-
-| Tool | What it does |
-|---|---|
-| `create_video_assembly` | A-roll + B-roll (local files, a folder, URLs, or Google Photos) → a rendered vertical short. Local or hosted. |
-| `suggest_clips` / `swap_clip` | See the cutaways; swap one for better-fitting B-roll (with a `reason`). |
-| `trim_clip` / `remove_span` / `reorder_scenes` | Granular timeline edits — instant, no re-render. |
-| `render_project` | Bake captions/overlays into the final MP4 (the one render). |
-| `publish_now` / `schedule_post` / `send_to_drafts` | Post to TikTok / Instagram / YouTube. |
-| `generate_caption`, `create_kinetic_text`, carousels, image ads | The rest of the content pipeline. |
-
-Edits are **instant and free** (they patch the timeline); `render_project` is the single cloud render. Iterate the cut as much as you like, then finalize once.
-
-## Open source
-
-The MCP server, the editor, and the agent verbs are **MIT** — use them free. Cloud generation (AI B-roll, rendering, publishing) runs on ViralSpin's infrastructure and is metered as credits; sign in at [viralspin.ai](https://www.viralspin.ai). You never paste an API key for the AI — the heavy lifting is server-side.
-
-- Listed in the official **MCP registry**: `ai.viralspin/viralspin`
-- Hosted connector (no install, for URL / Google Photos workflows): `https://mcp.viralspin.ai/mcp`
-
-## Local vs hosted
-
-- **Hosted (the default):** the cloud pipeline does the heavy lifting — assembly, AI B-roll, rendering — and every edit opens in the web Swap & Refine editor. B-roll from Google Photos / URLs / your synced library. Needs a [viralspin.ai](https://www.viralspin.ai) account (generation is metered as credits); no API keys to paste. The `mcp.viralspin.ai/mcp` hosted connector is the same, zero-install.
-- **Local (advanced):** point `VIRALSPIN_ASSEMBLY_DIR` at a local engine checkout to read your disk — index a folder of clips, select B-roll contextually, and render locally. The npm package ships without the engine, so the local-render tools route you to the hosted path until that env var is set.
-
-Either way, the agent reads local files *to upload them* (A-roll, a B-roll folder); only on-disk rendering needs the local engine.
-
-## License
-
-MIT — see [LICENSE](./LICENSE).
+# ViralSpin MCP — the video editor your AI agent operates
+
+[![MCP Registry](https://img.shields.io/badge/MCP-registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=viralspin)
+[![npm](https://img.shields.io/badge/npm-%40viralspin%2Fmcp-red)](https://www.npmjs.com/package/@viralspin/mcp)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+Turn a talking-head clip + a folder of B-roll into a polished vertical short — and **let Claude do the edit**. Point it at your footage in plain English; it transcribes, picks B-roll cutaways matched to what's said, adds captions + a hook, and renders a 9:16 short. Then publishes to TikTok, Instagram, or YouTube. No timeline-wrangling required.
+
+> **The agent operates a real timeline.** Swap a clip, trim it, reorder scenes, cut a span — all by asking. Edits are instant; you render once when the cut is right.
+
+![demo](docs/demo.gif) <!-- TODO: the split-screen "Claude edits, clips stream onto the timeline" clip -->
+
+## Quick start
+
+```bash
+# Claude Code
+claude mcp add viralspin -- npx -y @viralspin/mcp
+
+# or Claude Desktop — add to claude_desktop_config.json:
+{
+  "mcpServers": {
+    "viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }
+  }
+}
+```
+
+Then just ask:
+
+```
+Turn my A-roll at C:/clips/talk.mp4 into a 9:16 short, using B-roll
+from C:/my-broll and my Google Photos.
+
+Publish that to TikTok and Instagram with the caption: posting through the chaos.
+```
+
+## Render a reel on your own computer (`render_locally`)
+
+ViralSpin plans the reel and hands over the media; **your Mac or PC does the draw**, nothing is published, 0 credits.
+
+1. Install Node 20+ (macOS: `brew install node` - Windows: `winget install OpenJS.NodeJS.LTS`) and keep 8 GB of disk free.
+2. Add the server to Claude Desktop (`claude_desktop_config.json`; on Windows use `"command": "npx.cmd"` if `npx` is not found):
+   `"viralspin": { "command": "npx", "args": ["-y", "@viralspin/mcp"] }` - no tokens to paste.
+3. Connect once: in a terminal run `npx -y @viralspin/mcp login` (your browser opens, you click **Authorize**). Skipping this is fine too: the first time you ask Claude to render, the browser opens by itself. Credentials live in `~/.viralspin/oauth.json` (Windows: `%USERPROFILE%\.viralspin`), readable only by you, and renew themselves silently for about 30 days of use. `npx -y @viralspin/mcp whoami` / `logout` show / remove them; nothing ever prints a token.
+4. In the ViralSpin app: open a reel's **style picker**, choose **On my computer**, tap **Send to my computer**.
+5. In Claude Desktop say: *"Render my ViralSpin reel"* - with no arguments it picks your newest waiting reel and says which. The first run downloads a ~0.5 GB kit into `~/.viralspin/kit` and Chrome Headless Shell once. The finished reel is uploaded back and shows up in the app; a copy stays in `~/.viralspin/jobs/<id>/`.
+
+Tools: `render_locally` (no arguments, or `job_id`, `render_id`, `request`, `concurrency`, `dry_run`, `complete`, `upload`, `background`) and `render_locally_status` (no arguments lists your waiting / rendering reels).
+If the Chrome download is blocked by antivirus or a proxy the error says so and names the manual step.
+
+## What the agent can do
+
+| Tool | What it does |
+|---|---|
+| `create_video_assembly` | A-roll + B-roll (local files, a folder, URLs, or Google Photos) → a rendered vertical short. Local or hosted. |
+| `suggest_clips` / `swap_clip` | See the cutaways; swap one for better-fitting B-roll (with a `reason`). |
+| `trim_clip` / `remove_span` / `reorder_scenes` | Granular timeline edits — instant, no re-render. |
+| `render_project` | Bake captions/overlays into the final MP4 (the one render). |
+| `publish_now` / `schedule_post` / `send_to_drafts` | Post to TikTok / Instagram / YouTube. |
+| `generate_caption`, `create_kinetic_text`, carousels, image ads | The rest of the content pipeline. |
+
+Edits are **instant and free** (they patch the timeline); `render_project` is the single cloud render. Iterate the cut as much as you like, then finalize once.
+
+## Open source
+
+The MCP server, the editor, and the agent verbs are **MIT** — use them free. Cloud generation (AI B-roll, rendering, publishing) runs on ViralSpin's infrastructure and is metered as credits; sign in at [viralspin.ai](https://www.viralspin.ai). You never paste an API key for the AI — the heavy lifting is server-side.
+
+- Listed in the official **MCP registry**: `ai.viralspin/viralspin`
+- Hosted connector (no install, for URL / Google Photos workflows): `https://mcp.viralspin.ai/mcp`
+
+## Local vs hosted
+
+- **Hosted (the default):** the cloud pipeline does the heavy lifting — assembly, AI B-roll, rendering — and every edit opens in the web Swap & Refine editor. B-roll from Google Photos / URLs / your synced library. Needs a [viralspin.ai](https://www.viralspin.ai) account (generation is metered as credits); no API keys to paste. The `mcp.viralspin.ai/mcp` hosted connector is the same, zero-install.
+- **Local (advanced):** point `VIRALSPIN_ASSEMBLY_DIR` at a local engine checkout to read your disk — index a folder of clips, select B-roll contextually, and render locally. The npm package ships without the engine, so the local-render tools route you to the hosted path until that env var is set.
+
+Either way, the agent reads local files *to upload them* (A-roll, a B-roll folder); only on-disk rendering needs the local engine.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
 const os_1 = __importDefault(require("os"));
 const client_js_1 = require("./client.js");
+const organize_watch_js_1 = require("./organize-watch.js");
 const tokens_js_1 = require("./local-render/tokens.js");
 const login_js_1 = require("./local-render/login.js");
 const render_js_1 = require("./local-render/render.js");
@@ -45,6 +46,11 @@ async function runCli(argv, out = (s) => process.stdout.write(s + "\n")) {
             await tokens.getAccessToken(); // signs in (opens the browser once) when this computer is not connected yet
             const ac = new AbortController();
             process.once("SIGINT", () => { out("Stopping."); ac.abort(); });
+            // "this computer is here" on its own clock: a render can hold the watch loop for many minutes, and the app read that silence as "Not connected"
+            const ping = () => tokens.request("POST", `${client_js_1.PY_API_URL}/v1/reel/local-agent/ping`, { version: WATCH_VERSION, host: os_1.default.hostname(), platform: process.platform }).catch(() => { });
+            const beat = setInterval(() => void ping(), 30000);
+            ac.signal.addEventListener("abort", () => clearInterval(beat));
+            void (0, organize_watch_js_1.organizeLoop)({ req: (m, u, b) => tokens.request(m, u, b), log: out }, client_js_1.API_URL, ac.signal);
             await (0, watch_js_1.watchLoop)({
                 list: () => (0, render_js_1.listPendingJobs)({ apiBase: client_js_1.PY_API_URL, tokens }),
                 render: async (jobId) => { await (0, render_js_1.renderLocally)({ apiBase: client_js_1.PY_API_URL, tokens, job_id: jobId, complete: true, upload: true, log: out }); },
@@ -53,6 +59,9 @@ async function runCli(argv, out = (s) => process.stdout.write(s + "\n")) {
                 sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
                 now: () => Date.now(),
             }, { signal: ac.signal });
+            // the thumbnail server, the folder picker and the heartbeat would keep the process alive after Ctrl+C ("Stopping." and then still running,
+            // still holding port 47831 with old code), so leave for real
+            process.exit(0);
         }
         catch (e) {
             out(`The connector stopped: ${e.message}`);
@@ -71,7 +80,8 @@ async function runCli(argv, out = (s) => process.stdout.write(s + "\n")) {
         out("viralspin-mcp            run as an MCP server (Claude Desktop / Claude Code start this)\n" +
             "viralspin-mcp login      connect this computer to your ViralSpin account (opens your browser once)\n" +
             "viralspin-mcp whoami     show whether this computer is connected (never prints a token)\n" +
-            "viralspin-mcp logout     disconnect this computer");
+            "viralspin-mcp logout     disconnect this computer\n" +
+            "viralspin-mcp watch      keep this computer ready to render reels from the web (--install starts it at sign-in, --uninstall removes that)");
     }
     return true;
 }

package/dist/client.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PY_API_URL = void 0;
+exports.PY_API_URL = exports.API_URL = void 0;
 exports.get = get;
 exports.post = post;
 exports.patch = patch;
@@ -14,7 +14,7 @@ exports.uploadFiles = uploadFiles;
 exports.deleteFiles = deleteFiles;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const API_URL = (process.env.VIRALSPIN_API_URL || "https://viralspinbackend.onrender.com").replace(/\/$/, "");
+exports.API_URL = (process.env.VIRALSPIN_API_URL || "https://viralspinbackend.onrender.com").replace(/\/$/, "");
 // Python backend — Higgsfield, review-sessions, OAuth, narrative-render
 exports.PY_API_URL = (process.env.VIRALSPIN_PY_API_URL || "https://viralspin-api.onrender.com").replace(/\/$/, "");
 const API_KEY = process.env.VIRALSPIN_API_KEY || "";
@@ -31,7 +31,7 @@ function headers(extra = {}) {
     // Legacy API key — retained for backward compatibility with personal installs
     return { "X-API-Key": API_KEY, ...extra };
 }
-async function apiFetch(endpoint, init = {}, base = API_URL) {
+async function apiFetch(endpoint, init = {}, base = exports.API_URL) {
     const url = `${base}${endpoint}`;
     const resp = await fetch(url, {
         ...init,
@@ -107,7 +107,7 @@ async function uploadFiles(filePaths) {
     const authHeader = OAUTH_TOKEN
         ? { "Authorization": `Bearer ${OAUTH_TOKEN}` }
         : { "X-API-Key": API_KEY };
-    const resp = await fetch(`${API_URL}/v1/media/upload`, {
+    const resp = await fetch(`${exports.API_URL}/v1/media/upload`, {
         method: "POST",
         // Don't set Content-Type manually — fetch will set it with the correct multipart boundary.
         headers: authHeader,

package/dist/index.js

@@ -19,6 +19,7 @@ const edit_clip_js_1 = require("./tools/edit-clip.js");
 const relight_clip_js_1 = require("./tools/relight-clip.js");
 const ideas_js_1 = require("./tools/ideas.js");
 const local_index_js_1 = require("./tools/local-index.js");
+const organize_js_1 = require("./tools/organize.js");
 const profile_js_1 = require("./tools/profile.js");
 const posts_js_1 = require("./tools/posts.js");
 const captions_js_1 = require("./tools/captions.js");
@@ -27,6 +28,7 @@ const explainer_index_js_1 = require("./tools/explainer-index.js");
 const kinetic_text_js_1 = require("./tools/kinetic-text.js");
 const review_js_1 = require("./tools/review.js");
 const cli_js_1 = require("./cli.js");
+const cwd_js_1 = require("./local-render/cwd.js");
 const render_locally_js_1 = require("./tools/render-locally.js");
 const image_ads_js_1 = require("./tools/image-ads.js");
 const tools = [
@@ -59,6 +61,10 @@ const tools = [
     profile_js_1.setCreatorProfileTool,
     profile_js_1.getCreatorProfileTool,
     local_index_js_1.syncLocalIndexTool,
+    organize_js_1.organizeScanTool,
+    organize_js_1.organizeApplyTool,
+    organize_js_1.organizeUndoTool,
+    organize_js_1.organizeAddToStoryTool,
     local_index_js_1.searchLocalIndexTool,
     posts_js_1.listPostsTool,
     posts_js_1.cancelPostTool,
@@ -179,6 +185,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
     }
 });
 async function main() {
+    (0, cwd_js_1.leaveUnwritableCwd)();
     if (await (0, cli_js_1.runCli)(process.argv.slice(2)))
         return;
     const transport = new stdio_js_1.StdioServerTransport();

package/dist/local-render/cwd.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.leaveUnwritableCwd = leaveUnwritableCwd;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Started elevated / as a service / from Task Scheduler on Windows the cwd is C:\WINDOWS\system32. Remotion (and
+ * anything else that writes "./x") then dies with `EPERM: mkdir '...\system32\.remotion'`. If the cwd is not writable,
+ * move to ~/.viralspin; a writable cwd (a normal terminal) is left alone so relative CLI arguments keep working.
+ * Returns the cwd afterwards.
+ */
+function leaveUnwritableCwd(home = os_1.default.homedir()) {
+    try {
+        fs_1.default.accessSync(process.cwd(), fs_1.default.constants.W_OK);
+        return process.cwd();
+    }
+    catch { /* unwritable, or already deleted */ }
+    try {
+        const dir = path_1.default.join(home, ".viralspin");
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        process.chdir(dir);
+    }
+    catch { /* keep what we have */ }
+    return process.cwd();
+}

package/dist/local-render/media-fix.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findKitTool = findKitTool;
+exports.firstVideoPts = firstVideoPts;
+exports.fixLeadingNegativePts = fixLeadingNegativePts;
+/**
+ * Phone clips that start BEFORE their own zero.
+ *
+ * An MP4 trimmed with an edit list keeps its pre-roll frames at negative timestamps (the first video packet at -0.88 s, say). Remotion's
+ * compositor then reports "No frame found at position 0" the moment the draw reaches that clip, and the whole local render dies at
+ * that second. ffmpeg honours the edit list, so ONE re-encode of that clip (usually a few seconds long) starts it at 0 where the
+ * creator meant it to. Only clips that need it are touched; the original file's checksum is kept in a `<name>.fixed` marker so the
+ * media cache still counts the clip as downloaded.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const VIDEO = /\.(mp4|mov|m4v)$/i;
+/** ffmpeg / ffprobe from the installed kit's compositor package, else from PATH. */
+function findKitTool(kitDir, name) {
+    const exe = process.platform === "win32" ? `${name}.exe` : name;
+    try {
+        const base = node_path_1.default.join(kitDir, "node_modules", "@remotion");
+        for (const d of node_fs_1.default.readdirSync(base)) {
+            if (!d.startsWith("compositor-"))
+                continue;
+            const p = node_path_1.default.join(base, d, exe);
+            if (node_fs_1.default.existsSync(p))
+                return p;
+        }
+    }
+    catch { /* no kit yet: fall back to PATH */ }
+    return exe;
+}
+/** The first video packet's timestamp in seconds, or null when it cannot be read. */
+function firstVideoPts(file, ffprobe) {
+    const r = (0, node_child_process_1.spawnSync)(ffprobe, ["-v", "error", "-select_streams", "v:0", "-show_entries", "packet=pts_time", "-read_intervals", "%+#3", "-of", "csv=p=0", file], { encoding: "utf8", timeout: 30000 });
+    if (r.status !== 0)
+        return null;
+    const vals = r.stdout.split(/\r?\n/).map((s) => Number(s.trim())).filter((n) => Number.isFinite(n));
+    return vals.length ? Math.min(...vals) : null;
+}
+/** Re-encode `file` in place when its first frame sits before zero. Returns true when it was rewritten. */
+function fixLeadingNegativePts(file, kitDir, log, origSha) {
+    if (!VIDEO.test(file))
+        return false;
+    const marker = `${file}.fixed`;
+    if (node_fs_1.default.existsSync(marker))
+        return false;
+    const ffprobe = findKitTool(kitDir, "ffprobe");
+    const first = firstVideoPts(file, ffprobe);
+    if (first === null || first >= -0.001)
+        return false;
+    const tmp = `${file}.fixing.mp4`;
+    const r = (0, node_child_process_1.spawnSync)(findKitTool(kitDir, "ffmpeg"), ["-v", "error", "-y", "-i", file, "-c:v", "libx264", "-crf", "15", "-preset", "fast", "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "160k", "-movflags", "+faststart", tmp], { encoding: "utf8", timeout: 10 * 60000 });
+    if (r.status !== 0 || !node_fs_1.default.existsSync(tmp)) {
+        try {
+            node_fs_1.default.rmSync(tmp, { force: true });
+        }
+        catch { /* ignore */ }
+        log(`[media] could not straighten ${node_path_1.default.basename(file)} (first frame at ${first.toFixed(2)} s); drawing it as it is`);
+        return false;
+    }
+    node_fs_1.default.renameSync(tmp, file);
+    node_fs_1.default.writeFileSync(marker, origSha ?? "fixed");
+    log(`[media] straightened ${node_path_1.default.basename(file)} (its first frame was at ${first.toFixed(2)} s)`);
+    return true;
+}

package/dist/local-render/render.js

@@ -14,6 +14,7 @@ exports.planJob = planJob;
 exports.downloadMedia = downloadMedia;
 exports.uploadOutput = uploadOutput;
 exports.renderLocally = renderLocally;
+const media_fix_js_1 = require("./media-fix.js");
 const fs_1 = __importDefault(require("fs"));
 const net_1 = __importDefault(require("net"));
 const os_1 = __importDefault(require("os"));
@@ -105,7 +106,7 @@ async function planJob(o, log) {
         throw new Error("The server said the job is ready but sent no manifest.");
     return view.manifest;
 }
-async function downloadMedia(media, dir, fetchImpl, log) {
+async function downloadMedia(media, dir, fetchImpl, log, kitDir) {
     await fs_1.default.promises.mkdir(dir, { recursive: true });
     let downloaded = 0, cached = 0;
     let i = 0;
@@ -115,7 +116,15 @@ async function downloadMedia(media, dir, fetchImpl, log) {
             if (!m)
                 return;
             const dest = path_1.default.join(dir, m.name);
+            // a clip straightened earlier (media-fix) no longer has the server's checksum: its marker holds the original one
+            const fixedMark = `${dest}.fixed`;
+            if (fs_1.default.existsSync(dest) && fs_1.default.existsSync(fixedMark) && (!m.sha256 || fs_1.default.readFileSync(fixedMark, "utf8").trim() === m.sha256)) {
+                cached++;
+                continue;
+            }
             if (fs_1.default.existsSync(dest) && m.sha256 && (await (0, kit_js_1.sha256File)(dest)) === m.sha256) {
+                if (kitDir)
+                    (0, media_fix_js_1.fixLeadingNegativePts)(dest, kitDir, log, m.sha256 ?? undefined);
                 cached++;
                 continue;
             }
@@ -129,6 +138,8 @@ async function downloadMedia(media, dir, fetchImpl, log) {
             catch {
                 await (0, kit_js_1.downloadVerified)(m.url, dest, m.sha256, fetchImpl); // one more try: a dropped connection is the usual cause
             }
+            if (kitDir)
+                (0, media_fix_js_1.fixLeadingNegativePts)(dest, kitDir, log, m.sha256 ?? undefined);
             downloaded++;
             if (downloaded % 10 === 0)
                 log(`[media] ${downloaded + cached}/${media.length}`);
@@ -170,6 +181,7 @@ async function renderLocally(o) {
     const secs = (a) => Math.round((Date.now() - a) / 100) / 10;
     const kitDir = (0, kit_js_1.assertSafeKitDir)(o.kitDir ?? path_1.default.join(home, ".viralspin", "kit"), home);
     const workRoot = path_1.default.resolve(o.workDir ?? path_1.default.join(home, ".viralspin"));
+    log(`[connector] cwd ${process.cwd()} | work ${workRoot} | kit ${kitDir}`);
     (0, kit_js_1.checkNode)(20);
     const envGb = Number(process.env.VIRALSPIN_MIN_FREE_GB);
     await (0, kit_js_1.checkDisk)(workRoot, o.minFreeBytes ?? (envGb > 0 ? envGb * 2 ** 30 : undefined));
@@ -193,12 +205,22 @@ async function renderLocally(o) {
     // 3 - the media, content-addressed so a second render of the same take downloads nothing
     const td = Date.now();
     const mediaDir = path_1.default.join(workRoot, "cache", "media");
-    const dl = await downloadMedia(job.media, mediaDir, fetchImpl, log);
+    const dl = await downloadMedia(job.media, mediaDir, fetchImpl, log, kitDir);
     const dlSecs = secs(td);
     log(`[media] ${job.media.length} file(s): ${dl.downloaded} downloaded, ${dl.cached} already cached`);
     // the app shows "rendering on your computer" from here (best effort: a failed stamp never stops the draw)
     if (!o.dryRun)
         await o.tokens.request("POST", `${o.apiBase}/v1/reel/local-jobs/${encodeURIComponent(job.job_id)}/started`, {}).catch(() => undefined);
+    // HOW FAR THE DRAW IS, told to ViralSpin as it goes (the kit prints "progress N/M frames"): the app shows the %, the time it has run and what is left
+    let lastSent = 0;
+    const drawLog = (line) => {
+        log(line);
+        const m = /progress (\d+)\/(\d+) frames/.exec(line);
+        if (!m || o.dryRun || Date.now() - lastSent < 15000)
+            return;
+        lastSent = Date.now();
+        void o.tokens.request("POST", `${o.apiBase}/v1/reel/local-jobs/${encodeURIComponent(job.job_id)}/progress`, { frames: Number(m[1]), total: Number(m[2]) }).catch(() => undefined);
+    };
     // 4 - the draw, by the installed kit's own run.mjs
     const outDir = path_1.default.join(workRoot, "jobs", job.job_id);
     await fs_1.default.promises.mkdir(outDir, { recursive: true });
@@ -215,7 +237,7 @@ async function renderLocally(o) {
     try {
         const r = await runKit({
             kitDir, propsPath, mediaDir, audioPath: path_1.default.join(mediaDir, takeName), outPath, port, concurrency,
-            dryRun: Boolean(o.dryRun), log, signal: o.signal,
+            dryRun: Boolean(o.dryRun), log: drawLog, signal: o.signal,
         });
         const result = {
             job_id: job.job_id, dry_run: Boolean(o.dryRun),

package/dist/local-render/tokens.js

@@ -42,6 +42,7 @@ function defaultTokenFile() {
     return path_1.default.join(os_1.default.homedir(), ".viralspin", "oauth.json");
 }
 /** The server said the refresh token is no good (expired, revoked): a new sign-in is the only way forward. */
+const REQUEST_TIMEOUT_MS = 60000;
 class RefreshRefused extends Error {
 }
 exports.RefreshRefused = RefreshRefused;
@@ -169,6 +170,9 @@ class TokenManager {
             method,
             headers: { Authorization: `Bearer ${token}`, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
             body: body !== undefined ? JSON.stringify(body) : undefined,
+            // a request that never answers must not stall the watch loop for good: the connector's "I am online" check-ins ran in that loop, and one
+            // hung call (2026-10-30) left it silent, so the app read "Not connected" while the render was still running on this computer
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
         let resp = await go(await this.getAccessToken());
         if (resp.status === 401 && (this.refreshToken() || this.opts.signIn)) {

package/dist/local-render/watch.js

@@ -1,15 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.newWatchState = exports.POLL_MS = exports.PING_EVERY_MS = void 0;
+exports.jittered = exports.newWatchState = exports.MAX_TRIES = exports.RETRY_AFTER_MS = exports.IDLE_MAX_MS = exports.POLL_MS = exports.PING_EVERY_MS = void 0;
+exports.mayTry = mayTry;
 exports.watchTick = watchTick;
 exports.nextDelay = nextDelay;
 exports.watchLoop = watchLoop;
 const render_js_1 = require("./render.js");
-exports.PING_EVERY_MS = 15000;
-exports.POLL_MS = 4000;
+/** How often this computer tells ViralSpin it is online. 30 s (was 15 s): each one is a database write, all day; the server allows 90 s. */
+exports.PING_EVERY_MS = 30000;
+exports.POLL_MS = 10000;
+/** While nothing is waiting the connector asks less often (10 s, 15 s, then every 20 s); a job found, or an app that sends one, is noticed within one of these. */
+exports.IDLE_MAX_MS = 20000;
 const MAX_BACKOFF_MS = 60000;
-const newWatchState = () => ({ lastPing: 0, failed: new Set(), errors: 0, pingWarned: false });
+/** A job that failed here is tried again after this long, up to MAX_TRIES in all. It used to be dropped for the life of the process: a job that
+ *  was picked up while ViralSpin was still preparing it (queued behind a cloud draw for over 20 minutes, 2026-10-30) timed out once and was never
+ *  drawn, though the app went on showing it as waiting for this computer. */
+exports.RETRY_AFTER_MS = 5 * 60000;
+exports.MAX_TRIES = 3;
+const newWatchState = () => ({ lastPing: 0, failed: new Map(), errors: 0, pingWarned: false, idle: 0 });
 exports.newWatchState = newWatchState;
+/** May this job be tried now? Never failed here, or failed long enough ago and not too often. */
+function mayTry(st, jobId, now) {
+    const f = st.failed.get(jobId);
+    return !f || (f.tries < exports.MAX_TRIES && now - f.at >= exports.RETRY_AFTER_MS);
+}
 async function watchTick(d, st) {
     if (d.now() - st.lastPing >= exports.PING_EVERY_MS) {
         st.lastPing = d.now();
@@ -34,10 +48,14 @@ async function watchTick(d, st) {
         d.log(`[watch] could not ask ViralSpin for jobs (${e.message})`);
         return { did: "error" };
     }
-    const { job } = (0, render_js_1.pickJob)(jobs.filter((j) => !st.failed.has(j.job_id)));
-    // a job ViralSpin is still preparing is waited for by the render itself (it polls); starting it now only means this computer holds it from here
-    if (!job)
+    // ONLY A JOB THAT IS READY. One ViralSpin is still preparing is left until it is: taking it early held it in this computer's 20-minute plan wait,
+    // and a plan queued longer than that failed here and was never drawn.
+    const { job } = (0, render_js_1.pickJob)(jobs.filter((j) => j.phase === "waiting" && mayTry(st, j.job_id, d.now())));
+    if (!job) {
+        st.idle++;
         return { did: "idle" };
+    }
+    st.idle = 0;
     const name = job.title ? `"${job.title}"` : job.job_id.slice(0, 8);
     d.log(`[watch] drawing ${name}${job.duration_sec ? ` (${Math.round(Number(job.duration_sec))} s)` : ""}`);
     try {
@@ -46,8 +64,9 @@ async function watchTick(d, st) {
         return { did: "rendered", jobId: job.job_id };
     }
     catch (e) {
-        st.failed.add(job.job_id);
-        d.log(`[watch] ${name} failed on this computer: ${e.message}`);
+        const tries = (st.failed.get(job.job_id)?.tries ?? 0) + 1;
+        st.failed.set(job.job_id, { at: d.now(), tries });
+        d.log(`[watch] ${name} failed on this computer: ${e.message}${tries < exports.MAX_TRIES ? ` (trying again in ${Math.round(exports.RETRY_AFTER_MS / 60000)} min)` : " (not trying again: send it again from the app)"}`);
         return { did: "failed", jobId: job.job_id };
     }
 }
@@ -57,13 +76,30 @@ function nextDelay(r, st) {
         return 500;
     if (r.did === "error")
         return Math.min(MAX_BACKOFF_MS, exports.POLL_MS * 2 ** Math.min(st.errors, 4));
-    return exports.POLL_MS;
+    return Math.min(exports.IDLE_MAX_MS, exports.POLL_MS + Math.max(0, st.idle - 1) * 5000);
 }
+/** A little spread (+-15%) so connectors started together do not all ask at the same second. */
+const jittered = (ms, rand = Math.random) => Math.round(ms * (0.85 + 0.3 * rand()));
+exports.jittered = jittered;
 async function watchLoop(d, o = {}) {
     const st = (0, exports.newWatchState)();
     d.log("[watch] ViralSpin connector is running. Send a reel to your computer from the app and it draws here. Ctrl+C to stop.");
-    while (!o.signal?.aborted) {
-        const r = await watchTick(d, st);
-        await d.sleep(nextDelay(r, st));
+    // CHECK IN WHILE DRAWING TOO. The tick's ping waits for the tick, and a tick that draws takes the whole render (25 min for a 3-minute album):
+    // the server read this computer as gone after 45 s (90 s now) and the app said "Not connected" under "Drawing on your computer" (2026-10-31).
+    // This timer keeps the check-ins going whatever the loop is doing; the tick's own ping still runs when it is idle.
+    const beat = setInterval(() => {
+        if (d.now() - st.lastPing < exports.PING_EVERY_MS)
+            return;
+        st.lastPing = d.now();
+        d.ping().then(() => { st.pingWarned = false; }, () => undefined);
+    }, exports.PING_EVERY_MS);
+    try {
+        while (!o.signal?.aborted) {
+            const r = await watchTick(d, st);
+            await d.sleep((0, exports.jittered)(nextDelay(r, st)));
+        }
+    }
+    finally {
+        clearInterval(beat);
     }
 }