@lalalic/markcut 2.2.7 → 2.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "2.2.7",
+  "version": "2.2.9",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -31,6 +31,7 @@
     "test:watch": "vitest --config tests/vitest.config.ts",
     "build": "scripts/build-pipeline.sh && scripts/build-player.sh",
     "vision": "node src/render/cli.mjs vision",
+    "markcut": "bin/markcut",
     "push": "GIT_SSH_COMMAND=\"ssh -i ~/.ssh/id_ed25519_1 -o IdentitiesOnly=yes\" git push"
   },
   "dependencies": {

package/skills/markcut/SKILL.md

@@ -62,8 +62,6 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Markdown descriptive format (primary authoring format) | [docs/markdown-descriptive.md](docs/markdown-descriptive.md) |
 | Label system (browse, label, export labels.json) | [docs/label-mode.md](docs/label-mode.md) |
 | Player servers (label + edit mode) | [docs/edit-mode.md](docs/edit-mode.md) |
-| How to make video template | [docs/template.md](docs/template.md) |
-| Templates | [docs/templates/](docs/templates/) |
 
 
 ## common used components

package/skills/markcut/docs/markdown-descriptive.md

@@ -529,7 +529,7 @@ layout:series width:1920 height:1080 fps:30
 tts:"edge-tts --voice 'en-US-GuyNeural' --text '{input}' --write-media '{output}'"
 
 ## Hook
-- image duration:3 prompt:"..."
+- image prompt:"..."
 
 ## Title
 - script "Welcome to the course"

package/src/config.mjs

@@ -8,6 +8,48 @@
  * @module
  */
 
+
+export const args=(function parseArgs(argv) {
+  const CLI_OVERRIDE_FLAGS = {
+    "--itt": "itt",
+    "--vtt": "vtt",
+    "--stt": "stt",
+    "--tts": "tts",
+    "--agent": "agent",
+    "--edit-cli": "editCli",
+    "--tti": "tti",
+    "--ttv": "ttv"
+  };
+  const args = { command: "", file: "", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, showClis: false, scriptOutputDir: "", mediaOutputDir: "", variant: [], cliOverrides: {} };
+  let i = 2;
+  if (argv[i]) args.command = argv[i++];
+  if (argv[i] && !argv[i].startsWith("--")) args.file = argv[i++];
+  while (i < argv.length) {
+    const flag = argv[i++];
+    if (flag === "--output" && argv[i]) args.output = argv[i++];
+    else if (flag === "--script-output-dir" && argv[i]) args.scriptOutputDir = argv[i++];
+    else if (flag === "--media-output-dir" && argv[i]) args.mediaOutputDir = argv[i++];
+    else if (flag === "--cli") args.cli = true;
+    else if (flag === "--show-clis") args.showClis = true;
+    else if (flag === "--compile") args.compile = true;
+    else if (flag === "--force-new") args.forceNew = true;
+    else if (flag === "--verbose") args.verbose = true;
+    else if (flag === "--label") args.label = true;
+    else if (flag === "--edit") args.edit = true;
+    else if (flag === "--no-browser") args.noBrowser = true;
+    else if (flag === "--port" && argv[i]) args.port = parseInt(argv[i], 10);
+    else if (flag.startsWith("--port=")) args.port = parseInt(flag.split("=")[1], 10);
+    else if (flag === "--variant" && argv[i]) args.variant.push(argv[i++]);
+    else if (flag.startsWith("--variant=")) args.variant.push(flag.split("=")[1]);
+    else if (CLI_OVERRIDE_FLAGS[flag] && argv[i]) {
+      const key = CLI_OVERRIDE_FLAGS[flag];
+      args.cliOverrides[key] = argv[i++];
+    }
+  }
+  return args;
+})(process.argv);
+
+
 // ── Media type sets ───────────────────────────────────────────────────────
 
 export const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tiff", ".heic", ".avif"]);
@@ -25,14 +67,8 @@ export const MAX_VIDEO_DIMENSION = Number(process.env.MARKCUT_MAX_VIDEO_DIMENSIO
 // ── Vision pipeline CLI templates ─────────────────────────────────────────
 
 /**
- * Image-to-text (ITT) CLI.
- * Reads an image file and returns a text description.
- * Placeholders: {input}=image path(s), {prompt}=description prompt.
- * Override with MARKCUT_ITT_CLI env var.
+ * Image-to-text (ITT) CLI placeholder (now defined below via export let).
  */
-export const DEFAULT_ITT_CLI =
-  process.env.MARKCUT_ITT_CLI ||
-  'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';
 
 /**
  * Seconds between sampled video frames when using the default ITT-based VTT.
@@ -42,62 +78,23 @@ export const GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY || "";
 export const DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE_INTERVAL) || 5;
 
 /**
- * Video-to-text (VTT) CLI — direct video model.
- * When set to null/empty, falls back to ITT via frame extraction.
- * Placeholders: {input}=video path, {prompt}=description prompt.
- * Override with MARKCUT_VTT_CLI env var.
- */
-export const DEFAULT_VTT_CLI =
-  process.env.MARKCUT_VTT_CLI ||
-  'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs \'{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}\'';
-
-/**
- * Speech-to-text (STT) CLI.
- * Extracts audio and generates VTT subtitles.
- * Placeholders: {input}=audio path, {output}=output directory.
- * Override with MARKCUT_STT_CLI env var.
- * Used by both vision and render pipelines.
- */
-export const DEFAULT_STT_CLI =
-  process.env.MARKCUT_STT_CLI ||
-  'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
-
-/**
- * Text-to-speech (TTS) CLI.
- * Generates audio from text.
- * Placeholders: {input}=text, {output}=audio file path.
- * Override with MARKCUT_TTS_CLI env var.
- * Used by both vision and render pipelines.
- */
-export const DEFAULT_TTS_CLI =
-  process.env.MARKCUT_TTS_CLI ||
-  'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
-
-/**
- * Default agent CLI — general-purpose text LLM.
- * Used for text-only tasks like detect-scenes.
- * Placeholder:
- *   {prompt} = user prompt (current context + edit request)
- * Override with MARKCUT_AGENT_CLI env var.
- */
-export const DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
-
-/**
- * Default edit agent CLI — used by the edit-mode persistent rpc session.
- * Placeholders:
- *   {systemprompt} = system prompt (role, instructions, knowledge)
- *   {prompt}       = user prompt (current context + edit request)
- *   {sessionid}    = unique session ID for conversation continuity
- * Override with MARKCUT_EDIT_CLI env var.
+ * Video-to-text (VTT) CLI placeholder (now defined below via export let).
  */
-export const DEFAULT_EDIT_CLI = process.env.MARKCUT_EDIT_CLI || 'npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}';
 
-// ── Render-only pipeline CLI templates ─────────────────────────────────────
-// These are specific to the render pipeline (no vision pipeline equivalent).
-// All templates support {input}, {output}, and {seed} placeholders.
-// {seed} is substituted with root.seed (or empty string if not set).
 
-export const DEFAULT_TTI_CLI =
-  process.env.MARKCUT_TTI_CLI ||
-  'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
-export const DEFAULT_TTV_CLI = process.env.MARKCUT_TTV_CLI || '';
+/** Speech-to-text CLI. Override via --stt flag or MARKCUT_STT_CLI env var. */
+export const DEFAULT_STT_CLI = args.cliOverrides.stt || process.env.MARKCUT_STT_CLI || 'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
+/** Text-to-speech CLI. Override via --tts flag or MARKCUT_TTS_CLI env var. */
+export const DEFAULT_TTS_CLI = args.cliOverrides.tts || process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
+/** Default agent CLI. Override via --agent flag or MARKCUT_AGENT_CLI env var. */
+export const DEFAULT_AGENT_CLI = args.cliOverrides.agent || process.env.MARKCUT_AGENT_CLI || 'npx pi -p {prompt}';
+/** Default edit agent CLI. Override via --edit-cli flag or MARKCUT_EDIT_CLI env var. */
+export const DEFAULT_EDIT_CLI = args.cliOverrides.editCli || process.env.MARKCUT_EDIT_CLI || 'npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}';
+/** Text-to-image CLI. Override via --tti flag or MARKCUT_TTI_CLI env var. */
+export const DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
+/** Text-to-video CLI. Override via --ttv flag or MARKCUT_TTV_CLI env var. */
+export const DEFAULT_TTV_CLI = args.cliOverrides.ttv || process.env.MARKCUT_TTV_CLI || '';
+/** Image-to-text CLI. Override via --itt flag or MARKCUT_ITT_CLI env var. */
+export const DEFAULT_ITT_CLI = args.cliOverrides.itt || process.env.MARKCUT_ITT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';;
+/** Video-to-text CLI. Override via --vtt flag or MARKCUT_VTT_CLI env var. */
+export const DEFAULT_VTT_CLI = args.cliOverrides.vtt || process.env.MARKCUT_VTT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs \'{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}\'';

package/src/descriptive/resolve.ts

@@ -713,8 +713,9 @@ export async function resolveGeneratedMedia(
   walkDown(clone as any, (node) => {
     if ((node.type !== "image" && node.type !== "video")) return;
     if (!node.prompt || typeof node.prompt !== "string") return;
-    // Skip if src is already set (prompt is just metadata)
-    if (node.src) return;
+    // Skip if src is already set to a real path (prompt is just metadata).
+    // "auto" is a placeholder meaning "auto-generate via TTI/TTV".
+    if (node.src && node.src !== "auto") return;
     const id = node.id ?? `${node.type}-${genNodes.length}`;
     genNodes.push({ node, id, type: node.type as "image" | "video", prompt: node.prompt });
   });

package/src/player/browser.tsx

@@ -123,7 +123,9 @@ function PlayerApp() {
 
   // Fetch scenes for active scene tracking
   React.useEffect(() => {
-    fetch("/api/video-info")
+    const variant = (window as any).VARIANT || "default";
+    const url = variant !== "default" ? `/api/video-info?variant=${variant}` : "/api/video-info";
+    fetch(url)
       .then((r) => r.json())
       .then((info) => {
         if (info.scenes) {

package/src/player/bundle/player.js

@@ -59780,6 +59780,7 @@ var root = folder.extend({
   fps: external_exports.number().int().positive().default(30),
   instruction: external_exports.string().optional(),
   metadata: external_exports.string().optional(),
+  seed: external_exports.number().optional().describe("global seed for TTI/TTV generation; substituted into CLI {seed} placeholder"),
   stylesheet: external_exports.string().optional().describe("global css; selectors use .type and .name"),
   subtitle: subtitleOverlay.optional().describe("global subtitle overlay; src is a VTT file with absolute timestamps"),
   /**
@@ -60351,7 +60352,9 @@ var import_jsx_runtime93 = __toESM(require_jsx_runtime(), 1);
 function SceneThumbnails({ currentTime, onSeek }) {
   const [scenes, setScenes] = React51.useState([]);
   React51.useEffect(() => {
-    fetch("/api/video-info").then((r) => r.json()).then((info2) => {
+    const variant = window.VARIANT || "default";
+    const url2 = variant !== "default" ? `/api/video-info?variant=${variant}` : "/api/video-info";
+    fetch(url2).then((r) => r.json()).then((info2) => {
       if (info2.scenes) setScenes(info2.scenes);
     }).catch(() => {
     });
@@ -60482,7 +60485,9 @@ function PlayerApp() {
   const [currentTime, setCurrentTime] = React55.useState(0);
   const [activeScene, setActiveScene] = React55.useState("");
   React55.useEffect(() => {
-    fetch("/api/video-info").then((r) => r.json()).then((info2) => {
+    const variant = window.VARIANT || "default";
+    const url2 = variant !== "default" ? `/api/video-info?variant=${variant}` : "/api/video-info";
+    fetch(url2).then((r) => r.json()).then((info2) => {
       if (info2.scenes) {
         window.__scenes = info2.scenes;
       }

package/src/player/components/SceneThumbnails.tsx

@@ -23,7 +23,9 @@ export function SceneThumbnails({ currentTime, onSeek }: SceneThumbnailsProps) {
   const [scenes, setScenes] = React.useState<Scene[]>([]);
 
   React.useEffect(() => {
-    fetch("/api/video-info")
+    const variant = (window as any).VARIANT || "default";
+    const url = variant !== "default" ? `/api/video-info?variant=${variant}` : "/api/video-info";
+    fetch(url)
       .then((r) => r.json())
       .then((info) => {
         if (info.scenes) setScenes(info.scenes);

package/src/player/pipeline.mjs

@@ -883,8 +883,8 @@ var require_format = __commonJS({
         return format.apply(null, [fmt].concat(replacements));
       }
       function format(fmt) {
-        var argIndex = 1, args = [].slice.call(arguments), i = 0, n = fmt.length, result = "", c, escaped = false, arg, tmp, leadingZero = false, precision, nextArg = function() {
-          return args[argIndex++];
+        var argIndex = 1, args2 = [].slice.call(arguments), i = 0, n = fmt.length, result = "", c, escaped = false, arg, tmp, leadingZero = false, precision, nextArg = function() {
+          return args2[argIndex++];
         }, slurpNumber = function() {
           var digits = "";
           while (/\d/.test(fmt[i])) {
@@ -972,22 +972,61 @@ import { existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 // src/config.mjs
+var args = (function parseArgs(argv) {
+  const CLI_OVERRIDE_FLAGS = {
+    "--itt": "itt",
+    "--vtt": "vtt",
+    "--stt": "stt",
+    "--tts": "tts",
+    "--agent": "agent",
+    "--edit-cli": "editCli",
+    "--tti": "tti",
+    "--ttv": "ttv"
+  };
+  const args2 = { command: "", file: "", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, showClis: false, scriptOutputDir: "", mediaOutputDir: "", variant: [], cliOverrides: {} };
+  let i = 2;
+  if (argv[i]) args2.command = argv[i++];
+  if (argv[i] && !argv[i].startsWith("--")) args2.file = argv[i++];
+  while (i < argv.length) {
+    const flag = argv[i++];
+    if (flag === "--output" && argv[i]) args2.output = argv[i++];
+    else if (flag === "--script-output-dir" && argv[i]) args2.scriptOutputDir = argv[i++];
+    else if (flag === "--media-output-dir" && argv[i]) args2.mediaOutputDir = argv[i++];
+    else if (flag === "--cli") args2.cli = true;
+    else if (flag === "--show-clis") args2.showClis = true;
+    else if (flag === "--compile") args2.compile = true;
+    else if (flag === "--force-new") args2.forceNew = true;
+    else if (flag === "--verbose") args2.verbose = true;
+    else if (flag === "--label") args2.label = true;
+    else if (flag === "--edit") args2.edit = true;
+    else if (flag === "--no-browser") args2.noBrowser = true;
+    else if (flag === "--port" && argv[i]) args2.port = parseInt(argv[i], 10);
+    else if (flag.startsWith("--port=")) args2.port = parseInt(flag.split("=")[1], 10);
+    else if (flag === "--variant" && argv[i]) args2.variant.push(argv[i++]);
+    else if (flag.startsWith("--variant=")) args2.variant.push(flag.split("=")[1]);
+    else if (CLI_OVERRIDE_FLAGS[flag] && argv[i]) {
+      const key = CLI_OVERRIDE_FLAGS[flag];
+      args2.cliOverrides[key] = argv[i++];
+    }
+  }
+  return args2;
+})(process.argv);
 var MAX_IMAGE_DIMENSION = Number(process.env.MARKCUT_MAX_IMAGE_DIMENSION) || 384;
 var MAX_VIDEO_DURATION = Number(process.env.MARKCUT_MAX_VIDEO_DURATION) || 60;
 var MAX_VIDEO_DIMENSION = Number(process.env.MARKCUT_MAX_VIDEO_DIMENSION) || 360;
-var DEFAULT_ITT_CLI = process.env.MARKCUT_ITT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';
 var GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY || "";
 var DEFAULT_VTT_SAMPLE_INTERVAL = Number(process.env.MARKCUT_VTT_SAMPLE_INTERVAL) || 5;
-var DEFAULT_VTT_CLI = process.env.MARKCUT_VTT_CLI || `uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs '{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}'`;
-var DEFAULT_STT_CLI = process.env.MARKCUT_STT_CLI || 'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
-var DEFAULT_TTS_CLI = process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
-var DEFAULT_AGENT_CLI = process.env.MARKCUT_AGENT_CLI || "npx pi -p {prompt}";
-var DEFAULT_EDIT_CLI = process.env.MARKCUT_EDIT_CLI || "npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}";
-var DEFAULT_TTI_CLI = process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}"';
-var DEFAULT_TTV_CLI = process.env.MARKCUT_TTV_CLI || "";
+var DEFAULT_STT_CLI = args.cliOverrides.stt || process.env.MARKCUT_STT_CLI || 'uvx --from openai-whisper whisper "{input}" --output_format vtt --output_dir "{output}"';
+var DEFAULT_TTS_CLI = args.cliOverrides.tts || process.env.MARKCUT_TTS_CLI || 'uvx edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"';
+var DEFAULT_AGENT_CLI = args.cliOverrides.agent || process.env.MARKCUT_AGENT_CLI || "npx pi -p {prompt}";
+var DEFAULT_EDIT_CLI = args.cliOverrides.editCli || process.env.MARKCUT_EDIT_CLI || "npx pi --session-id {sessionid} --system-prompt {systemprompt} -p {prompt}";
+var DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
+var DEFAULT_TTV_CLI = args.cliOverrides.ttv || process.env.MARKCUT_TTV_CLI || "";
+var DEFAULT_ITT_CLI = args.cliOverrides.itt || process.env.MARKCUT_ITT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';
+var DEFAULT_VTT_CLI = args.cliOverrides.vtt || process.env.MARKCUT_VTT_CLI || `uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs '{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}'`;
 
 // src/render/cli-tools.ts
-function substituteCli(template, input, output) {
+function substituteCli(template, input, output, seed) {
   const safeOutput = output;
   let safeInput;
   const inputMatch = template.match(/(['"])\{input\}/);
@@ -1001,7 +1040,8 @@ function substituteCli(template, input, output) {
   } else {
     safeInput = input.replace(/"/g, '\\"').replace(/'/g, "'\\''");
   }
-  return template.replace(/\{input\}/g, safeInput).replace(/\{output\}/g, safeOutput);
+  const safeSeed = seed !== void 0 ? String(seed) : "";
+  return template.replace(/\{input\}/g, safeInput).replace(/\{output\}/g, safeOutput).replace(/\{seed\}/g, safeSeed);
 }
 function generateTTS(text3, outputPath, cli) {
   mkdirSync(dirname(outputPath), { recursive: true });
@@ -1022,9 +1062,9 @@ async function generateSTT(audioPath, outputDir, cli) {
     console.warn(`  \u26A0 STT failed: ${e.message}`);
   }
 }
-function generateTTI(prompt, outputPath, cli) {
+function generateTTI(prompt, outputPath, cli, seed) {
   mkdirSync(dirname(outputPath), { recursive: true });
-  const cmd = substituteCli(cli ?? DEFAULT_TTI_CLI, prompt, outputPath);
+  const cmd = substituteCli(cli ?? DEFAULT_TTI_CLI, prompt, outputPath, seed);
   try {
     execSync(cmd, {
       encoding: "utf-8",
@@ -1038,11 +1078,11 @@ function generateTTI(prompt, outputPath, cli) {
   }
   return existsSync(outputPath) ? outputPath : "";
 }
-function generateTTV(prompt, outputPath, cli, ttiCmd) {
+function generateTTV(prompt, outputPath, cli, ttiCmd, seed) {
   mkdirSync(dirname(outputPath), { recursive: true });
   if (!cli) {
     const pngPath = outputPath.replace(/\.mp4$/, ".png");
-    const imageResult = generateTTI(prompt, pngPath, ttiCmd);
+    const imageResult = generateTTI(prompt, pngPath, ttiCmd, seed);
     if (!imageResult || !existsSync(imageResult)) {
       console.error(`  \u2717 TTV: TTI step produced no image for "${prompt.slice(0, 50)}..."`);
       return "";
@@ -1062,7 +1102,7 @@ function generateTTV(prompt, outputPath, cli, ttiCmd) {
     }
     return existsSync(outputPath) ? outputPath : "";
   }
-  const cmd = substituteCli(cli, prompt, outputPath);
+  const cmd = substituteCli(cli, prompt, outputPath, seed);
   try {
     execSync(cmd, {
       encoding: "utf-8",
@@ -10977,14 +11017,15 @@ async function resolveGeneratedMedia(root, options) {
   walkDown(clone, (node2) => {
     if (node2.type !== "image" && node2.type !== "video") return;
     if (!node2.prompt || typeof node2.prompt !== "string") return;
-    if (node2.src) return;
+    if (node2.src && node2.src !== "auto") return;
     const id = node2.id ?? `${node2.type}-${genNodes.length}`;
     genNodes.push({ node: node2, id, type: node2.type, prompt: node2.prompt });
   });
   for (const { node: node2, id, type, prompt } of genNodes) {
     const ext = type === "image" ? "png" : "mp4";
     const cli = type === "image" ? clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI : clone.ttv ?? options.ttvCli ?? DEFAULT_TTV_CLI;
-    const cacheKey = computeCacheKey({ prompt, cli, type });
+    const seed = options.seed;
+    const cacheKey = computeCacheKey({ prompt, cli, type, seed });
     const outputPath = join(options.outputDir, `${cacheKey}.${ext}`);
     const cached = checkCache(cache, `gen:${cacheKey}`, cacheKey);
     const label = type === "image" ? "TTI" : "TTV";
@@ -10997,7 +11038,7 @@ async function resolveGeneratedMedia(root, options) {
     try {
       console.log(`  \u{1F50A} ${label}: ${labelText}...`);
       const ttiCmd = clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI;
-      const result = type === "image" ? generateTTI(prompt, outputPath, cli) : generateTTV(prompt, outputPath, cli, ttiCmd);
+      const result = type === "image" ? generateTTI(prompt, outputPath, cli, seed) : generateTTV(prompt, outputPath, cli, ttiCmd, seed);
       if (result) {
         node2.src = outputPath;
         updateCache(cache, `gen:${cacheKey}`, cacheKey, outputPath);
@@ -11107,11 +11148,13 @@ async function resolveAll2(root, options = {}) {
     variant: options.variants?.[0] ?? "video"
   });
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
+  const generationSeed = result.seed ?? options.seed;
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,
       ttiCli: options.ttiCli,
-      ttvCli: options.ttvCli
+      ttvCli: options.ttvCli,
+      seed: generationSeed
     });
   }
   result = await resolveMediaDurations(result, {

package/src/player/server.mjs

@@ -181,7 +181,7 @@ function startAgentProcess() {
   const cmd = resolvedParts[0];
   const cmdArgs = resolvedParts.slice(1);
 
-  console.log(`  🎬 starting persistent agent (rpc): ${cmd} ${cmdArgs.slice(0, -1).join(" ")} --system-prompt <${systemPrompt.length} chars>`);
+  console.log(`  🎬 starting edit agent`);
 
   const child = spawn(cmd, cmdArgs, { cwd: ROOT, stdio: ["pipe", "pipe", "pipe"] });
   agentProcess = child;
@@ -1055,8 +1055,17 @@ Edit request: ${text}`;
 
     // Serve the main HTML page (variant-aware)
     if (path === "/" || path === "/index.html") {
+      // If the resolved variant isn't compiled, fall back to the first
+      // available variant. This handles the common case where the user
+      // passes only --variant zh (no "default" variant exists) and opens
+      // the root URL — the player will fetch the zh variant data instead
+      // of failing on a non-existent "default" variant.
+      let htmlVariant = variantLabel;
+      if (!compiledRootCache.has(variantLabel) && VARIANT_CONFIGS.length > 0) {
+        htmlVariant = VARIANT_CONFIGS[0].label;
+      }
       res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-      res.end(getHtml(variantLabel));
+      res.end(getHtml(htmlVariant));
       return;
     }
 

package/src/render/cli.mjs

@@ -11,6 +11,11 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from
 import { createHash } from "node:crypto";
 import { resolve, dirname, join, extname } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_TTS_CLI, DEFAULT_STT_CLI, DEFAULT_TTI_CLI, DEFAULT_TTV_CLI,
+  DEFAULT_ITT_CLI, DEFAULT_VTT_CLI, DEFAULT_AGENT_CLI, DEFAULT_EDIT_CLI,
+  args,
+} from "../config.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -44,13 +49,27 @@ function usage() {
   console.log(`
 markcut CLI — Markdown/JSON → video pipeline
 
+npx @lalalic/markcut <command> [options]
+
+global options:
+  --show-clis                          Print all default CLI templates and exit
+
+  --tti <template>                     Override default TTI CLI template
+  --tts <template>                     Override default TTS CLI template
+  --stt <template>                     Override default STT CLI template
+  --ttv <template>                     Override default TTV CLI template
+  --itt <template>                     Override default ITT CLI template
+  --vtt <template>                     Override default VTT CLI template
+  --agent <template>                   Override default agent CLI template
+  --edit-cli <template>                Override default edit agent CLI template
+
+  --help                               Show this help
+
 Commands:
 
   verify <file>                         Parse + validate descriptive file
-    --cli                             Check required CLI tools are installed
 
   preview <file.json|.md>               Open player with live preview
-    --edit                             Auto-reload on file change
     --label                           Open label input overlay
     --no-browser                      Skip opening browser automatically
     --port <num>                        Port for the player server (default: 3001)
@@ -61,47 +80,16 @@ Commands:
 
   vision <folder>                      Extract metadata into metadata.json
     --label                            Full pipeline: preview → label → normalize → percept → segments
-    --agent <template>                 Custom text LLM CLI for detect-scenes ({prompt})
-    --itt <template>                   Custom ITT CLI template with {input}, {prompt}
-    --vtt <template>                   Custom VTT CLI template with {input}, {prompt}
-    --stt <template>                   Custom STT CLI template with {input}, {output}
     --prompts-file <path>              Path to prompts markdown file (default: vision_prompts.md)
     --vtt-sample-interval <n>          Sample one video frame every N seconds (default: 5)
     --context "text"                   Background context about people/places (injected into prompts)
-    --pick <files>                     Comma-separated filenames to process
     --skip-stt                         Skip speech-to-text for videos
     --dry-run                          Show what would be processed without running AI
     --show-prompts                     Print the prompts file and exit
-    --show-clis                        Print the default ITT/VTT/STT CLI templates
-    --help                             Show this help
     --<prompt-name> "text"             Override any prompt template from vision_prompts.md
 `);
 }
 
-export function parseArgs(argv) {
-  const args = { command: "", file: "", output: "", forceNew: false, verbose: false, label: false, edit: false, noBrowser: false, chat: false, port: 3001, compile: false, cli: false, scriptOutputDir: "", mediaOutputDir: "", variant: [] };
-  let i = 2;
-  if (argv[i]) args.command = argv[i++];
-  if (argv[i] && !argv[i].startsWith("--")) args.file = argv[i++];
-  while (i < argv.length) {
-    const flag = argv[i++];
-    if (flag === "--output" && argv[i]) args.output = argv[i++];
-    else if (flag === "--script-output-dir" && argv[i]) args.scriptOutputDir = argv[i++];
-    else if (flag === "--media-output-dir" && argv[i]) args.mediaOutputDir = argv[i++];
-    else if (flag === "--cli") args.cli = true;
-    else if (flag === "--compile") args.compile = true;
-    else if (flag === "--force-new") args.forceNew = true;
-    else if (flag === "--verbose") args.verbose = true;
-    else if (flag === "--label") args.label = true;
-    else if (flag === "--edit") args.edit = true;
-    else if (flag === "--no-browser") args.noBrowser = true;
-    else if (flag === "--port" && argv[i]) args.port = parseInt(argv[i], 10);
-    else if (flag.startsWith("--port=")) args.port = parseInt(flag.split("=")[1], 10);
-    else if (flag === "--variant" && argv[i]) args.variant.push(argv[i++]);
-    else if (flag.startsWith("--variant=")) args.variant.push(flag.split("=")[1]);
-  }
-  return args;
-}
 
 /**
  * Render one aspect ratio with compact progress output.
@@ -222,13 +210,32 @@ function renderOne(streamTree, aspect, outputPath, verbose) {
 }
 
 async function main() {
-  const args = parseArgs(process.argv);
-
   if (!args.command || args.command === "help" || args.command === "--help") {
     usage();
     process.exit(0);
   }
 
+  // --show-clis works as a command or a flag
+  if (args.showClis || args.command === "--show-clis") {
+    console.log(`Default CLI 
+tti=${DEFAULT_TTI_CLI}
+
+ttv=${DEFAULT_TTV_CLI || "(empty — falls back to TTI + ffmpeg to produce a 3s MP4)"}
+
+tts=${DEFAULT_TTS_CLI}
+
+stt=${DEFAULT_STT_CLI}
+
+itt=${DEFAULT_ITT_CLI}
+
+vtt=${DEFAULT_VTT_CLI || "(empty — uses ITT via frame extraction)"}
+
+agent=${DEFAULT_AGENT_CLI}
+
+edit=${DEFAULT_EDIT_CLI}`);
+    process.exit(0);
+  }
+
   if (args.command === "vision") {
     const { main: visionMain } = await import("../vision/cli.mjs");
     await visionMain(process.argv);
@@ -487,40 +494,6 @@ function hasScript(root) {
       }
       walkMedia(descriptive.children);
 
-      // ── Check 2: CLI tool availability (--cli flag) ────────────────────
-      if (args.cli) {
-        function extractCmd(configStr) {
-          if (!configStr) return null;
-          return configStr.trim().split(/\s+/)[0] || null;
-        }
-
-        const pipelineConfigs = [
-          { type: "TTS", config: descriptive.tts, defaultCmd: "edge-tts", needsCheck: hasScript(descriptive) },
-          { type: "STT", config: descriptive.stt, defaultCmd: "whisper", needsCheck: hasScript(descriptive) },
-          { type: "TTI", config: descriptive.tti, defaultCmd: "pi", needsCheck: needsTti },
-          { type: "TTV", config: descriptive.ttv, defaultCmd: "pi", needsCheck: needsTtv },
-        ];
-
-        const checked = new Set();
-        for (const p of pipelineConfigs) {
-          if (!p.needsCheck) continue;
-          const cmd = extractCmd(p.config) || p.defaultCmd;
-          if (checked.has(cmd)) continue;
-          checked.add(cmd);
-          const { execSync } = await import("node:child_process");
-          try {
-            execSync(`which ${cmd}`, { stdio: "ignore" });
-          } catch {
-            const hints = {
-              "pi": " (pip install pi-sdk)",
-              "edge-tts": " (pip install edge-tts)",
-              "whisper": " (pip install openai-whisper)",
-            };
-            errors.push(`CLI tool "${cmd}" not found${hints[cmd] || ""}. Required by ${p.type}`);
-          }
-        }
-      }
-
       // ── Results ─────────────────────────────────────────────────────────
       for (const w of warnings) emitWarn(w);
       if (errors.length > 0) {