@effectnode/media 0.9.0 → 0.10.0

package/dist/backend/movie-backend/render-media.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync, readdirSync, statSync, unlinkSync, rmSync, copyFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { join, sep } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { spawn, whichSync, mimeType } from "./process.js";
 // Track the currently active spawn process so it can be cancelled
 let activeProc = null;
@@ -16,7 +16,6 @@ const APP_DATA_DIR = join(homedir(), "media-studio");
 const OUTPUT_DIR = join(APP_DATA_DIR, "output");
 const UPLOAD_DIR = join(APP_DATA_DIR, "upload");
 const AGENT_UPLOAD_DIR = join(APP_DATA_DIR, "agent-upload");
-const EXTRACTED_FRAMES_DIR = join(APP_DATA_DIR, "extracted-frames");
 const AGENTS_DIR = join(APP_DATA_DIR, "agents");
 const JSON_DIR = join(APP_DATA_DIR, "json");
 const PYTHON_DIR = join(APP_DATA_DIR, "python-src");
@@ -25,7 +24,10 @@ const PROJECTS_FILE = join(JSON_DIR, "projects.json");
 const CHARACTERS_FILE = join(JSON_DIR, "characters.json");
 const Z_IMAGE_MODEL = "AbstractFramework/z-image-turbo-8bit";
 const FLUX_KLEIN_MODEL = "AbstractFramework/flux.2-klein-4b-8bit";
+const SEEDVR2_MODEL = "AbstractFramework/seedvr2-7b-8bit";
 const MLX_VLM_MODEL = "mlx-community/gemma-4-e4b-it-8bit";
+const LTX_MODEL_HIGH_QUALITY = "dgrauet/ltx-2.3-mlx";
+const LTX_MODEL_STANDARD = "dgrauet/ltx-2.3-mlx-q8";
 const VIDEO_STAGE_FLAGS = {
     distilled: "--distilled",
     "one-stage": "--one-stage",
@@ -41,6 +43,12 @@ function stageFlagFor(mode) {
         ? (VIDEO_STAGE_FLAGS[mode] ?? "--distilled")
         : "--distilled";
 }
+/** Resolve a ltx-2-mlx model id, falling back to the q8 standard model. */
+function resolveLtxModel(model) {
+    return String(model) === LTX_MODEL_HIGH_QUALITY
+        ? LTX_MODEL_HIGH_QUALITY
+        : LTX_MODEL_STANDARD;
+}
 // ========== Project Helpers ==========
 function ensureDir(dir) {
     if (!existsSync(dir)) {
@@ -187,22 +195,6 @@ function resolveSafePath(candidate, projectId) {
     }
     return null;
 }
-/** Resolve and validate a user-supplied video filename. Only bare .mp4 names in the output dir. */
-function resolveSafeVideoPath(candidate, projectId) {
-    const base = candidate.split(/[/\\]/).pop() || candidate;
-    if (base !== candidate || base.includes("..") || base.startsWith(".")) {
-        return null;
-    }
-    if (!base.toLowerCase().endsWith(".mp4"))
-        return null;
-    const candidatePath = join(OUTPUT_DIR, projectId, base);
-    if (!existsSync(candidatePath))
-        return null;
-    const resolved = realpathSync(candidatePath);
-    if (isPathAllowed(resolved))
-        return resolved;
-    return null;
-}
 /**
  * Resolve the `mlxgen` executable installed via `uv tool install --upgrade mlx-gen`.
  * uv tool installs binaries into `~/.local/bin`; fall back to relying on PATH.
@@ -219,6 +211,63 @@ async function getMlxgenBin() {
     }
     return "mlxgen";
 }
+/** Resolve the `dots-tts` executable installed via `uv tool install dots-tts`. */
+async function getDotsTtsBin() {
+    const candidates = [
+        join(homedir(), ".local", "bin", "dots-tts"),
+        "/opt/homebrew/bin/dots-tts",
+        "/usr/local/bin/dots-tts",
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return "dots-tts";
+}
+/** Resolve the `mlx_whisper` executable installed via `uv tool install mlx-whisper`. */
+async function getMlxWhisperBin() {
+    const candidates = [
+        join(homedir(), ".local", "bin", "mlx_whisper"),
+        "/opt/homebrew/bin/mlx_whisper",
+        "/usr/local/bin/mlx_whisper",
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return "mlx_whisper";
+}
+/** The cloned dots-tts-mlx project directory. */
+const DOTS_TTS_FOLDER = join(APP_DATA_DIR, "python-src", "dots-tts-mlx");
+/** Base directory where dots-tts MLX weights live (inside the project folder). */
+const DOTS_TTS_WEIGHTS_DIR = join(DOTS_TTS_FOLDER, "dots-tts-mlx-weights");
+/**
+ * Resolve a dots-tts `--model` value. Accepts `./dots-tts-mlx-weights/mf-int4`
+ * (relative to the dots-tts-mlx folder), a bare variant (`mf-int4`), or an
+ * explicit path.
+ */
+function resolveDotsTtsModel(model) {
+    if (!model)
+        return join(DOTS_TTS_WEIGHTS_DIR, "mf-int4");
+    if (model.startsWith("./"))
+        return join(DOTS_TTS_FOLDER, model.slice(2));
+    if (model.includes("/"))
+        return model;
+    return join(DOTS_TTS_WEIGHTS_DIR, model);
+}
+/** True when the dots-tts `mf-int4` weights have been downloaded. */
+function isDotsTtsModelDownloaded() {
+    return existsSync(join(DOTS_TTS_WEIGHTS_DIR, "mf-int4"));
+}
+/** Resolve the ffmpeg binary installed via Homebrew (Apple Silicon then Intel). */
+async function getFfmpegBin() {
+    const candidates = ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return "ffmpeg";
+}
 /** True when the `mlxgen` executable is installed (known paths or PATH). */
 function isMlxgenInstalled() {
     const candidates = [
@@ -293,18 +342,6 @@ function isMlxVlmInstalled() {
         return false;
     }
 }
-/**
- * Resolve the ffmpeg binary installed via Homebrew (Apple Silicon then Intel).
- * Falls back to relying on PATH when neither known location exists.
- */
-async function getFfmpegBin() {
-    const candidates = ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"];
-    for (const p of candidates) {
-        if (existsSync(p))
-            return p;
-    }
-    return "ffmpeg";
-}
 /** Fixed filename mlx_audio.tts.generate writes its output clip as. */
 const TTS_OUTPUT_FILENAME = "audio_000.mp3";
 /**
@@ -574,6 +611,76 @@ export async function generateSceneVideo(uvPath, projectId, scene, characters, o
         url: `/api/files?path=${encodeURIComponent(videoPath)}`,
     };
 }
+/**
+ * Generate a video from a project image via LTX-2.3. `imagePath` must be a bare
+ * filename previously uploaded/generated for this project. Used by the queue
+ * worker for the "Scene Video Generation" tab.
+ */
+export async function generateImageToVideo(uvPath, projectId, params, onLog) {
+    const { prompt, imagePath, mode } = params;
+    if (!isValidProjectId(projectId))
+        return { error: "Invalid project ID" };
+    if (!prompt || !prompt.trim())
+        return { error: "Prompt is required" };
+    if (!imagePath)
+        return { error: "Image path is required" };
+    const resolvedImage = resolveSafePath(imagePath, projectId);
+    if (!resolvedImage) {
+        return {
+            error: "Invalid image path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    const ltxFolder = join(PYTHON_DIR, "ltx-2-mlx");
+    if (!existsSync(ltxFolder)) {
+        return { error: "ltx-2-mlx not found. Run setup first." };
+    }
+    const projectOutputDir = resolveOutputDir(undefined, projectId);
+    if (!projectOutputDir)
+        return { error: "Invalid output directory." };
+    const outputFile = `video-${Date.now()}.mp4`;
+    const outputPath = join(projectOutputDir, outputFile);
+    const videoWidth = Number(params.width) || 480;
+    const videoHeight = Number(params.height) || 480;
+    const videoFrames = Number(params.frames) || 121;
+    const videoFps = Number(params.frameRate) || 24;
+    const stage1Steps = Math.max(1, Math.round(Number(params.stage1Steps)) || 30);
+    const stage2Steps = Math.max(1, Math.round(Number(params.stage2Steps)) || 3);
+    const result = await runCommand([
+        uvPath,
+        "run",
+        "ltx-2-mlx",
+        "generate",
+        "--model",
+        resolveLtxModel(params.model),
+        "--prompt",
+        prompt.trim(),
+        stageFlagFor(mode),
+        "--stage1-steps",
+        String(stage1Steps),
+        "--stage2-steps",
+        String(stage2Steps),
+        "--frames",
+        String(videoFrames),
+        "--width",
+        String(videoWidth),
+        "--height",
+        String(videoHeight),
+        "--frame-rate",
+        String(videoFps),
+        "--image",
+        resolvedImage,
+        "--output",
+        outputPath,
+    ], { cwd: ltxFolder, onLog });
+    if (!result.success || !existsSync(outputPath)) {
+        return { error: result.output || "Video generation failed" };
+    }
+    backupFile(outputPath, projectId);
+    return {
+        filename: outputFile,
+        url: `/api/files?path=${encodeURIComponent(outputPath)}`,
+    };
+}
 /** Normalize a value into a safe filesystem slug. */
 function slugify(v) {
     return String(v || "")
@@ -584,10 +691,11 @@ function slugify(v) {
  * Generate a single scene image via fast-image-edit (FLUX.2 Klein), using the
  * already-generated character/place images referenced by the scene's slugs.
  */
-export async function generateSceneImage(projectId, scene, onLog) {
+export async function generateSceneImage(projectId, scene, steps, onLog) {
     const s = slugify(scene?.slug);
     if (!s)
         return { error: "Invalid scene slug" };
+    const stepCount = Math.max(1, Number(steps) || 6);
     const outputDir = join(OUTPUT_DIR, projectId);
     const mlxgen = await getMlxgenBin();
     const refImages = [];
@@ -611,7 +719,7 @@ export async function generateSceneImage(projectId, scene, onLog) {
     const fluxArgs = [mlxgen, "generate", "--model", FLUX_KLEIN_MODEL];
     for (const p of refImages)
         fluxArgs.push("--image", p);
-    fluxArgs.push("--prompt", String(scene?.imagePrompt || ""), "--output", sceneImagePath, "--mlx-cache-limit-gb", "20", "--steps", "5", "--seed", "42", "--width", "1024", "--height", "1024");
+    fluxArgs.push("--prompt", String(scene?.imagePrompt || ""), "--output", sceneImagePath, "--mlx-cache-limit-gb", "20", "--steps", String(stepCount), "--seed", "42", "--width", "1024", "--height", "1024");
     const result = await runCommand(fluxArgs, { onLog });
     if (!result.success || !existsSync(sceneImagePath)) {
         return { error: result.output || `Failed to generate scene image ${s}` };
@@ -622,12 +730,368 @@ export async function generateSceneImage(projectId, scene, onLog) {
         url: `/api/files?path=${encodeURIComponent(sceneImagePath)}`,
     };
 }
+/**
+ * Upscale/refine a project image via mlxgen (SeedVR2). `imagePath` must be a
+ * bare filename previously uploaded/generated for this project. `resolution` is
+ * either "1x" (refine at native resolution) or "2048" (upscale to 2048px).
+ */
+export async function generateUpscale(projectId, imagePath, resolution, onLog) {
+    if (!isValidProjectId(projectId))
+        return { error: "Invalid project ID" };
+    if (!imagePath)
+        return { error: "Image path is required" };
+    const resolvedImage = resolveSafePath(imagePath, projectId);
+    if (!resolvedImage) {
+        return {
+            error: "Invalid image path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    const target = /^(1x|\d+)$/.test(resolution) ? resolution : "1x";
+    const mlxgen = await getMlxgenBin();
+    const projectOutputDir = join(OUTPUT_DIR, projectId);
+    ensureDir(projectOutputDir);
+    const outputFile = `upscale-${target}-${Date.now()}.png`;
+    const outputPath = join(projectOutputDir, outputFile);
+    const result = await runCommand([
+        mlxgen,
+        "upscale",
+        "--model",
+        SEEDVR2_MODEL,
+        "--image-path",
+        resolvedImage,
+        "--resolution",
+        target,
+        "--seed",
+        "42",
+        "--mlx-cache-limit-gb",
+        "100",
+        "--output",
+        outputPath,
+    ], { onLog });
+    if (!result.success || !existsSync(outputPath)) {
+        return { error: result.output || "Upscale failed" };
+    }
+    backupFile(outputPath, projectId);
+    return {
+        filename: outputFile,
+        url: `/api/files?path=${encodeURIComponent(outputPath)}`,
+    };
+}
+/**
+ * Clone a reference voice and speak `text` via mlx_audio.tts.generate. `refAudioPath`
+ * must be a bare filename previously uploaded to this project. `quality` is "low"
+ * or "high" (maps to a TTS model). Output is saved under <output>/voices/.
+ */
+export async function generateVoiceClone(uvPath, projectId, text, refAudioPath, quality, onLog) {
+    if (!isValidProjectId(projectId))
+        return { error: "Invalid project ID" };
+    if (!refAudioPath)
+        return { error: "Reference audio is required" };
+    // Sanitize the transcript: strip control characters (incl. newlines) and
+    // collapse whitespace. spawn() runs with shell:false (array args), so shell
+    // metacharacters cannot execute, but this keeps `--text` a single well-formed
+    // argument and out of the terminal log.
+    const cleanText = text
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleanText)
+        return { error: "Text is required" };
+    const resolvedRef = resolveSafePath(refAudioPath, projectId);
+    if (!resolvedRef) {
+        return {
+            error: "Invalid reference audio path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    const model = quality === "low" ? TTS_MODELS.low : TTS_MODELS.high;
+    const projectOutputDir = resolveOutputDir(undefined, projectId);
+    if (!projectOutputDir)
+        return { error: "Invalid output directory." };
+    const voiceId = `voice-${Date.now()}`;
+    const voiceDir = join(projectOutputDir, "voices", voiceId);
+    ensureDir(voiceDir);
+    const result = await runCommand([
+        uvPath,
+        "run",
+        "mlx_audio.tts.generate",
+        "--model",
+        model,
+        "--text",
+        cleanText,
+        "--ref_audio",
+        resolvedRef,
+        "--output",
+        voiceDir,
+        "--audio_format",
+        "mp3",
+        "--play",
+        "--instruct",
+        "slow down speech",
+    ], { cwd: voiceDir, onLog });
+    if (!result.success) {
+        return { error: result.output || "Voice generation failed" };
+    }
+    const path = resolveAudioFile(voiceDir);
+    if (!path) {
+        return { error: "TTS completed but no audio file was produced" };
+    }
+    const filename = path.split(sep).pop() || TTS_OUTPUT_FILENAME;
+    // Persist a per-voice metadata file so the generated-voice list can be rebuilt
+    // from the folder structure (each voice in its own folder with meta.json), with
+    // no central JSON index.
+    const meta = {
+        id: voiceId,
+        transcript: cleanText,
+        quality,
+        refAudioFilename: refAudioPath,
+        filename,
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(join(voiceDir, "meta.json"), JSON.stringify(meta, null, 2), "utf-8");
+    return {
+        filename,
+        url: `/api/files?path=${encodeURIComponent(path)}`,
+    };
+}
+/** Find the newest video file (mp4/webm/mov) inside a directory. */
+function findNewestVideo(dir) {
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const name of entries) {
+        const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+        if (ext !== ".mp4" && ext !== ".webm" && ext !== ".mov")
+            continue;
+        const full = join(dir, name);
+        try {
+            const st = statSync(full);
+            if (!st.isFile())
+                continue;
+            if (!newest || st.mtimeMs > newest.mtime) {
+                newest = { path: full, mtime: st.mtimeMs };
+            }
+        }
+        catch {
+            // skip unreadable entries
+        }
+    }
+    return newest ? newest.path : null;
+}
+/**
+ * Generate a video from an image + audio via ltx-2-mlx `a2v` (audio-to-video).
+ * `imagePath` and `audioPath` must be bare filenames previously uploaded/generated
+ * for this project. `stage1Steps` maps to `--stage1-steps` (15 default, 30 HD).
+ */
+export async function generateAudioToVideo(uvPath, projectId, params, onLog) {
+    if (!isValidProjectId(projectId))
+        return { error: "Invalid project ID" };
+    if (!params.imagePath)
+        return { error: "Image path is required" };
+    if (!params.audioPath)
+        return { error: "Audio path is required" };
+    const resolvedImage = resolveSafePath(params.imagePath, projectId);
+    if (!resolvedImage) {
+        return {
+            error: "Invalid image path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    const resolvedAudio = resolveSafePath(params.audioPath, projectId);
+    if (!resolvedAudio) {
+        return {
+            error: "Invalid audio path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    // Collapse whitespace so the prompt stays a single well-formed CLI argument.
+    const cleanPrompt = String(params.prompt || "")
+        .replace(/\s+/g, " ")
+        .trim() || "scene";
+    const stage1Steps = Math.max(1, Math.round(Number(params.stage1Steps)) || 15);
+    // 1 second = 24 frames, plus a terminal frame (24n + 1).
+    const frames = Math.max(1, Math.round(Number(params.frames)) || 25);
+    const ltxFolder = join(PYTHON_DIR, "ltx-2-mlx");
+    if (!existsSync(ltxFolder)) {
+        return { error: "ltx-2-mlx not found. Run setup first." };
+    }
+    const outputDir = join(OUTPUT_DIR, projectId, `a2v-${Date.now()}`);
+    ensureDir(outputDir);
+    const result = await runCommand([
+        uvPath,
+        "run",
+        "ltx-2-mlx",
+        "a2v",
+        "--image",
+        resolvedImage,
+        "--audio",
+        resolvedAudio,
+        "--frame-rate",
+        "24",
+        "--frames",
+        String(frames),
+        "--output",
+        outputDir,
+        "--prompt",
+        cleanPrompt,
+        "--stage1-steps",
+        String(stage1Steps),
+        "--stage2-steps",
+        "3",
+    ], { cwd: ltxFolder, onLog });
+    if (!result.success) {
+        return { error: result.output || "Audio-to-video generation failed" };
+    }
+    const videoPath = findNewestVideo(outputDir);
+    if (!videoPath) {
+        return { error: "a2v completed but no video file was produced" };
+    }
+    backupFile(videoPath, projectId);
+    return {
+        filename: videoPath.split(sep).pop() || "a2v.mp4",
+        url: `/api/files?path=${encodeURIComponent(videoPath)}`,
+    };
+}
+/**
+ * Clone a reference voice via dots-tts. Output is written to
+ * <output>/<projectId>/dots-tts/ as `<prefix>_000.wav`.
+ */
+export async function generateAdvancedVoiceClone(projectId, params, onLog) {
+    if (!isValidProjectId(projectId))
+        return { error: "Invalid project ID" };
+    const cleanText = String(params.text || "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleanText)
+        return { error: "Text is required" };
+    if (!params.refAudioPath)
+        return { error: "Reference audio is required" };
+    const resolvedRef = resolveSafePath(params.refAudioPath, projectId);
+    if (!resolvedRef) {
+        return {
+            error: "Invalid reference audio path. Provide a filename previously uploaded to this project.",
+        };
+    }
+    const language = String(params.language || "YUE").trim() || "YUE";
+    const prefix = String(params.outPrefix || "voice")
+        .replace(/[^a-zA-Z0-9_-]/g, "_")
+        .slice(0, 64) || "voice";
+    const model = resolveDotsTtsModel(String(params.model || ""));
+    // dots-tts and mlx_whisper both expect a WAV reference — convert mp3/other
+    // formats to 16-bit PCM WAV first.
+    let refAudio = resolvedRef;
+    if (!resolvedRef.toLowerCase().endsWith(".wav")) {
+        const tempDir = join(TEMP_DIR, String(projectId));
+        ensureDir(tempDir);
+        const convertedRef = join(tempDir, `avc-ref-${Date.now()}.wav`);
+        const ffmpegBin = await getFfmpegBin();
+        const conv = await runCommand([
+            ffmpegBin,
+            "-y",
+            "-i",
+            resolvedRef,
+            "-c:a",
+            "pcm_s16le",
+            "-ar",
+            "44100",
+            "-ac",
+            "2",
+            convertedRef,
+        ], { onLog });
+        if (!conv.success || !existsSync(convertedRef)) {
+            return { error: "Failed to convert reference audio to WAV" };
+        }
+        refAudio = convertedRef;
+    }
+    // dots-tts requires `--ref-text` (the reference audio's transcript). Transcribe
+    // the WAV reference with mlx_whisper to supply it.
+    const whisperBin = await getMlxWhisperBin();
+    const transcribeDir = join(TEMP_DIR, String(projectId));
+    ensureDir(transcribeDir);
+    const whisperResult = await runCommand([whisperBin, refAudio, "--output-dir", transcribeDir], { onLog });
+    const refTxtPath = join(transcribeDir, (refAudio.split(sep).pop() || "ref").replace(/\.[^.]+$/, "") + ".txt");
+    const refText = whisperResult.success && existsSync(refTxtPath)
+        ? readFileSync(refTxtPath, "utf-8").replace(/\s+/g, " ").trim()
+        : "";
+    if (!refText) {
+        return { error: "Failed to transcribe reference audio (mlx_whisper)" };
+    }
+    const dotsTtsBin = await getDotsTtsBin();
+    // Mirror the voice-clone tab's timestamped-folder layout so outputs never
+    // overwrite each other.
+    const voiceId = `voice-${Date.now()}`;
+    const outDir = join(OUTPUT_DIR, projectId, "dots-tts", voiceId);
+    ensureDir(outDir);
+    console.log("debug-info:", [
+        dotsTtsBin,
+        "--model",
+        model,
+        "--text",
+        cleanText || "please provide text",
+        "--ref-audio",
+        refAudio,
+        "--ref-text",
+        refText,
+        "--language",
+        language,
+        "--out-path",
+        outDir,
+        "--out-prefix",
+        prefix,
+    ]);
+    const result = await runCommand([
+        dotsTtsBin,
+        "--model",
+        model,
+        "--text",
+        cleanText || "please provide text",
+        "--ref-audio",
+        refAudio,
+        "--ref-text",
+        refText,
+        "--language",
+        language,
+        "--out-path",
+        outDir,
+        "--out-prefix",
+        prefix,
+    ], { cwd: dirname(dotsTtsBin), onLog });
+    if (!result.success) {
+        return { error: result.output || "Advanced voice clone failed" };
+    }
+    const outputFile = `${prefix}_000.wav`;
+    const outputPath = join(outDir, outputFile);
+    if (!existsSync(outputPath)) {
+        return { error: `Expected output ${outputFile} was not produced` };
+    }
+    // Mirror the voice-clone tab's on-disk conventions: a timestamped backup copy
+    // plus a per-voice meta.json so the output can be listed without a central index.
+    backupFile(outputPath, projectId);
+    const meta = {
+        id: voiceId,
+        transcript: cleanText,
+        refText,
+        language,
+        model,
+        refAudioFilename: params.refAudioPath,
+        outPrefix: prefix,
+        filename: outputFile,
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(join(outDir, "meta.json"), JSON.stringify(meta, null, 2), "utf-8");
+    return {
+        filename: outputFile,
+        url: `/api/files?path=${encodeURIComponent(outputPath)}`,
+    };
+}
 /**
  * Generate a composite image via fast-image-edit (FLUX.2 Klein). `images` are
  * base64 data URLs that are decoded into temp files and passed to the model as
  * separate `--image` inputs. Used by the generation queue worker.
  */
-export async function generateFastImageEditImage(projectId, prompt, images, onLog) {
+export async function generateFastImageEditImage(projectId, prompt, images, steps, upscaleResolution, onLog) {
     if (!isValidProjectId(projectId))
         return { error: "Invalid project ID" };
     if (!prompt || !prompt.trim())
@@ -635,6 +1099,7 @@ export async function generateFastImageEditImage(projectId, prompt, images, onLo
     if (!Array.isArray(images) || images.length === 0) {
         return { error: "At least one reference image is required" };
     }
+    const stepCount = Math.max(1, Number(steps) || 4);
     // Decode each base64 reference image into a temp workspace file so the
     // FLUX model receives them as separate `--image` inputs.
     const tempDir = join(TEMP_DIR, String(projectId));
@@ -661,12 +1126,21 @@ export async function generateFastImageEditImage(projectId, prompt, images, onLo
         const args = [mlxgen, "generate", "--model", FLUX_KLEIN_MODEL];
         for (const path of tempImagePaths)
             args.push("--image", path);
-        args.push("--prompt", prompt.trim(), "--output", outputPath, "--mlx-cache-limit-gb", "20", "--steps", "5", "--seed", "42", "--width", "1024", "--height", "1024");
+        args.push("--prompt", prompt.trim(), "--output", outputPath, "--mlx-cache-limit-gb", "20", "--steps", String(stepCount), "--seed", "42", "--width", "1024", "--height", "1024");
         const result = await runCommand(args, { onLog });
         if (!result.success || !existsSync(outputPath)) {
             return { error: result.output || "Fast image edit failed" };
         }
         backupFile(outputPath, projectId);
+        // Optionally upscale the generated result (1x / 1500px / 2000px).
+        if (upscaleResolution && upscaleResolution !== "none") {
+            if (onLog)
+                onLog(`Upscaling result (${upscaleResolution})…\n`);
+            const upscaled = await generateUpscale(projectId, outputFile, upscaleResolution, onLog);
+            if ("error" in upscaled)
+                return { error: upscaled.error };
+            return upscaled;
+        }
         return {
             filename: outputFile,
             url: `/api/files?path=${encodeURIComponent(outputPath)}`,
@@ -973,6 +1447,60 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         raw.sort((a, b) => b.birthtime - a.birthtime);
         res.json(raw.map(({ filename, url }) => ({ filename, url })));
     });
+    // List previously generated voice clones by scanning the voices folder. Each
+    // voice lives in its own subfolder with a meta.json (no central JSON index).
+    app.get("/api/projects/:id/voices", (req, res) => {
+        const { id } = req.params;
+        if (!isValidProjectId(id)) {
+            res.status(400).json({ error: "Invalid project ID" });
+            return;
+        }
+        const voicesRoot = join(OUTPUT_DIR, id, "voices");
+        const results = [];
+        if (existsSync(voicesRoot)) {
+            let names = [];
+            try {
+                names = readdirSync(voicesRoot);
+            }
+            catch {
+                names = [];
+            }
+            for (const name of names) {
+                const voiceDir = join(voicesRoot, name);
+                let isDir = false;
+                try {
+                    isDir = statSync(voiceDir).isDirectory();
+                }
+                catch {
+                    isDir = false;
+                }
+                if (!isDir)
+                    continue;
+                let meta = null;
+                try {
+                    meta = JSON.parse(readFileSync(join(voiceDir, "meta.json"), "utf-8"));
+                }
+                catch {
+                    continue; // folder without a meta.json — skip
+                }
+                const filename = String(meta?.filename || TTS_OUTPUT_FILENAME);
+                const audioPath = join(voiceDir, filename);
+                if (!existsSync(audioPath))
+                    continue;
+                results.push({
+                    id: name,
+                    transcript: String(meta?.transcript ?? ""),
+                    quality: String(meta?.quality ?? "high"),
+                    refAudioFilename: meta?.refAudioFilename ?? null,
+                    filename,
+                    createdAt: meta?.createdAt ?? null,
+                    url: `/api/files?path=${encodeURIComponent(audioPath)}`,
+                });
+            }
+        }
+        results.sort((a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")));
+        res.json(results);
+    });
     // ========== Render: Text-to-Image ==========
     app.post("/api/render/text-to-image", async (req, res) => {
         const { prompt, projectId, width = 512, height = 512, device = "mps", } = req.body || {};
@@ -1066,7 +1594,7 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
     });
     // ========== Render: Image-to-Video ==========
     app.post("/api/render/image-to-video", async (req, res) => {
-        const { prompt, imagePath, projectId, outputDir, width = 480, height = 480, frames = 121, frameRate = 24, mode = "distilled", } = req.body || {};
+        const { prompt, imagePath, projectId, outputDir, width = 480, height = 480, frames = 121, frameRate = 24, mode = "distilled", stage1Steps, stage2Steps, model, } = req.body || {};
         if (!prompt) {
             res.status(400).json({ error: "Prompt is required" });
             return;
@@ -1122,6 +1650,8 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             const videoHeight = Number(height) || 480;
             const videoFrames = Number(frames) || 121;
             const videoFps = Number(frameRate) || 24;
+            const stage1 = Math.max(1, Math.round(Number(stage1Steps)) || 30);
+            const stage2 = Math.max(1, Math.round(Number(stage2Steps)) || 3);
             send("progress", {
                 status: "starting",
                 label: "Generating video...",
@@ -1139,10 +1669,14 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
                 "ltx-2-mlx",
                 "generate",
                 "--model",
-                "dgrauet/ltx-2.3-mlx-q8",
+                resolveLtxModel(model),
                 "--prompt",
                 prompt,
                 stageFlagFor(mode),
+                "--stage1-steps",
+                String(stage1),
+                "--stage2-steps",
+                String(stage2),
                 // "--low-ram",
                 "--frames",
                 String(videoFrames),
@@ -1738,26 +2272,39 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== Render: Extend-Video ==========
-    app.post("/api/render/extend-video", async (req, res) => {
-        const { prompt, videoPath, projectId, extendFrames = 2 } = req.body || {};
-        if (!prompt) {
-            res.status(400).json({ error: "Prompt is required" });
+    // ========== MLX-Audio: Status ==========
+    app.get("/api/mlxaudio/status", async (_req, res) => {
+        // Never throw on a missing uv — installation state is based on the folder.
+        try {
+            await getUvPath();
+        }
+        catch {
+            // uv not found; installed is still reported from the folder below.
+        }
+        res.json({
+            installed: existsSync(join(PYTHON_DIR, "mlx-audio")),
+        });
+    });
+    // ========== Render: Voice Chat (TTS with reference voice) ==========
+    app.post("/api/render/voice-chat", async (req, res) => {
+        const { text, refAudioPath, projectId } = req.body || {};
+        if (!text || typeof text !== "string" || !text.trim()) {
+            res.status(400).json({ error: "Text is required" });
             return;
         }
-        if (!videoPath) {
-            res.status(400).json({ error: "Video path is required" });
+        if (!refAudioPath) {
+            res.status(400).json({ error: "Reference audio is required" });
             return;
         }
-        if (!projectId) {
-            res.status(400).json({ error: "Project ID is required" });
+        if (!projectId || !isValidProjectId(String(projectId))) {
+            res.status(400).json({ error: "Invalid project ID" });
             return;
         }
-        // Resolve video path — only bare .mp4 filenames in this project's output dir
-        const resolvedVideo = resolveSafeVideoPath(videoPath, projectId);
-        if (!resolvedVideo) {
+        // Resolve reference audio — only bare filenames in this project's dirs.
+        const resolvedRef = resolveSafePath(refAudioPath, String(projectId));
+        if (!resolvedRef) {
             res.status(400).json({
-                error: "Invalid video path. Provide a filename previously generated in this project.",
+                error: "Invalid reference audio path. Provide a filename previously uploaded to this project.",
             });
             return;
         }
@@ -1772,59 +2319,65 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
         try {
-            const ltxFolder = join(PYTHON_DIR, "ltx-2-mlx");
-            if (!existsSync(ltxFolder)) {
-                send("error", { error: "ltx-2-mlx not found. Run setup first." });
+            const uvPath = await getUvPath();
+            const projectOutputDir = resolveOutputDir(null, String(projectId));
+            if (!projectOutputDir) {
+                send("error", { error: "Invalid output directory." });
                 res.end();
                 return;
             }
-            const uvPath = await getUvPath();
-            const projectOutputDir = join(OUTPUT_DIR, projectId);
-            ensureDir(projectOutputDir);
-            const outputFile = `extended-${Date.now()}.mp4`;
-            const outputPath = join(projectOutputDir, outputFile);
-            const framesToAdd = Number(extendFrames) || 2;
+            // Isolate each utterance so a new response never overwrites a previous
+            // one. mlx_audio writes the clip as <dir>/audio_000.mp3.
+            const voiceDir = join(projectOutputDir, "voice-chat", `chat-${Date.now()}`);
+            ensureDir(voiceDir);
             send("progress", {
                 status: "starting",
-                label: "Extending video...",
-                inputFile: resolvedVideo,
-                outputFile,
-                settings: { extendFrames: framesToAdd },
+                label: "Generating voice...",
             });
             const proc = spawn([
                 uvPath,
                 "run",
-                "ltx-2-mlx",
-                "extend",
+                "mlx_audio.tts.generate",
                 "--model",
-                "dgrauet/ltx-2.3-mlx-q8",
-                "--prompt",
-                prompt,
-                "--video",
-                resolvedVideo,
-                "--extend-frames",
-                String(framesToAdd),
+                TTS_MODELS.high,
+                "--text",
+                text.trim(),
+                "--ref_audio",
+                resolvedRef,
+                // "--play",
                 "--output",
-                outputPath,
+                voiceDir,
+                "--audio_format",
+                "mp3",
+                // "--stream",
+                // "--save",
+                "--instruct",
+                "slow down",
             ], {
                 env: process.env,
-                cwd: ltxFolder,
+                cwd: voiceDir,
                 stdout: "pipe",
                 stderr: "pipe",
             });
             activeProc = proc;
-            // Stream stdout/stderr concurrently
-            const stdoutPromise = streamToSSE(proc.stdout, "Extend", send);
-            const stderrText = await streamToSSE(proc.stderr, "Extend", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "VoiceChat", send);
+            const stderrText = await streamToSSE(proc.stderr, "VoiceChat", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
-            const success = exitCode === 0 && existsSync(outputPath);
-            if (success) {
-                send("complete", {
-                    success: true,
-                    path: outputPath,
-                    filename: outputFile,
-                });
+            if (exitCode === 0) {
+                const path = resolveAudioFile(voiceDir);
+                if (path) {
+                    send("complete", {
+                        success: true,
+                        path,
+                        filename: path.split(sep).pop(),
+                    });
+                }
+                else {
+                    send("error", {
+                        error: "TTS completed but no audio file was produced",
+                    });
+                }
             }
             else {
                 send("error", {
@@ -1841,47 +2394,17 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== MLX-Audio: Status ==========
-    app.get("/api/mlxaudio/status", async (_req, res) => {
-        // Never throw on a missing uv — installation state is based on the folder.
-        try {
-            await getUvPath();
-        }
-        catch {
-            // uv not found; installed is still reported from the folder below.
-        }
+    // ========== MLX-Gen: Status ==========
+    app.get("/api/mlxgen/status", (_req, res) => {
         res.json({
-            installed: existsSync(join(PYTHON_DIR, "mlx-audio")),
+            installed: isMlxgenInstalled(),
+            zModelDownloaded: isModelDownloaded(Z_IMAGE_MODEL),
+            fluxModelDownloaded: isModelDownloaded(FLUX_KLEIN_MODEL),
+            seedvr2Downloaded: isModelDownloaded(SEEDVR2_MODEL),
         });
     });
-    // ========== Render: Text-to-Speech (mlx-audio) ==========
-    app.post("/api/render/tts", async (req, res) => {
-        const { text, refAudioPath, projectId, outputDir, quality, voiceId } = req.body || {};
-        if (!text || typeof text !== "string" || !text.trim()) {
-            res.status(400).json({ error: "Text is required" });
-            return;
-        }
-        if (!refAudioPath) {
-            res.status(400).json({ error: "Reference audio is required" });
-            return;
-        }
-        if (!projectId || !isValidProjectId(String(projectId))) {
-            res.status(400).json({ error: "Invalid project ID" });
-            return;
-        }
-        if (quality !== "low" && quality !== "high") {
-            res.status(400).json({ error: "Quality must be 'low' or 'high'" });
-            return;
-        }
-        // Resolve reference audio — only bare filenames in this project's dirs
-        const resolvedRef = resolveSafePath(refAudioPath, projectId);
-        if (!resolvedRef) {
-            res.status(400).json({
-                error: "Invalid reference audio path. Provide a filename previously uploaded to this project.",
-            });
-            return;
-        }
-        // SSE headers
+    // ========== MLX-Gen: Install ==========
+    app.post("/api/mlxgen/install", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -1893,81 +2416,21 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         };
         try {
             const uvPath = await getUvPath();
-            const projectOutputDir = resolveOutputDir(outputDir, projectId);
-            if (!projectOutputDir) {
-                send("error", { error: "Invalid output directory." });
-                res.end();
-                return;
-            }
-            // TTS audio is saved under <projectOutputDir>/voices/<voiceId>/ so each
-            // row's voiceover stays isolated in its own folder. Sanitize voiceId to
-            // alphanumerics/_/- so it can never escape the voices directory.
-            const safeVoiceId = String(voiceId ?? `voice-${Date.now()}`)
-                .replace(/[^a-zA-Z0-9_-]/g, "_")
-                .slice(0, 64);
-            const voiceDir = join(projectOutputDir, "voices", safeVoiceId);
-            ensureDir(voiceDir);
-            // Regenerating a row must overwrite the previous clip: delete any
-            // existing output so the generator writes a fresh audio_000.mp3.
-            const prevAudio = join(voiceDir, TTS_OUTPUT_FILENAME);
-            if (existsSync(prevAudio)) {
-                try {
-                    unlinkSync(prevAudio);
-                }
-                catch {
-                    // Ignore — the generator will overwrite the file regardless.
-                }
-            }
             send("progress", {
                 status: "starting",
-                label: "Generating speech...",
-                model: TTS_MODELS[quality],
+                label: "Installing mlx-gen...",
             });
-            // No --play flag: this is a silent server-side batch generation. The mp3
-            // lands in <projectOutputDir>/voices/<voiceId>/, which is servable via
-            // /api/files and resolvable via resolveSafePath for the mux step.
-            const proc = spawn([
-                uvPath,
-                "run",
-                "mlx_audio.tts.generate",
-                "--model",
-                TTS_MODELS[quality],
-                "--text",
-                text,
-                "--ref_audio",
-                resolvedRef,
-                "--output",
-                voiceDir,
-                "--audio_format",
-                "mp3",
-                "--play",
-                "--instruct",
-                "slow down speech",
-            ], {
-                env: process.env,
-                cwd: voiceDir,
+            const proc = spawn([uvPath, "tool", "install", "--upgrade", "mlx-gen"], {
                 stdout: "pipe",
                 stderr: "pipe",
             });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "TTS", send);
-            const stderrText = await streamToSSE(proc.stderr, "TTS", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "Install", send);
+            const stderrText = await streamToSSE(proc.stderr, "Install", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
-                const path = resolveAudioFile(voiceDir);
-                if (path) {
-                    send("complete", {
-                        success: true,
-                        path,
-                        filename: path.split(sep).pop(),
-                    });
-                }
-                else {
-                    send("error", {
-                        error: "TTS completed but no audio file was produced",
-                    });
-                }
+                send("complete", { success: true });
             }
             else {
                 send("error", {
@@ -1984,30 +2447,8 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== Render: Voice Chat (TTS with reference voice) ==========
-    app.post("/api/render/voice-chat", async (req, res) => {
-        const { text, refAudioPath, projectId } = req.body || {};
-        if (!text || typeof text !== "string" || !text.trim()) {
-            res.status(400).json({ error: "Text is required" });
-            return;
-        }
-        if (!refAudioPath) {
-            res.status(400).json({ error: "Reference audio is required" });
-            return;
-        }
-        if (!projectId || !isValidProjectId(String(projectId))) {
-            res.status(400).json({ error: "Invalid project ID" });
-            return;
-        }
-        // Resolve reference audio — only bare filenames in this project's dirs.
-        const resolvedRef = resolveSafePath(refAudioPath, String(projectId));
-        if (!resolvedRef) {
-            res.status(400).json({
-                error: "Invalid reference audio path. Provide a filename previously uploaded to this project.",
-            });
-            return;
-        }
-        // SSE headers
+    // ========== MLX-Gen: Download Z-Image Model ==========
+    app.post("/api/mlxgen/download-z-model", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2017,66 +2458,24 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         const send = (event, data) => {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
+        const model = Z_IMAGE_MODEL;
         try {
-            const uvPath = await getUvPath();
-            const projectOutputDir = resolveOutputDir(null, String(projectId));
-            if (!projectOutputDir) {
-                send("error", { error: "Invalid output directory." });
-                res.end();
-                return;
-            }
-            // Isolate each utterance so a new response never overwrites a previous
-            // one. mlx_audio writes the clip as <dir>/audio_000.mp3.
-            const voiceDir = join(projectOutputDir, "voice-chat", `chat-${Date.now()}`);
-            ensureDir(voiceDir);
+            const mlxgen = await getMlxgenBin();
             send("progress", {
                 status: "starting",
-                label: "Generating voice...",
+                label: `Downloading model ${model}...`,
             });
-            const proc = spawn([
-                uvPath,
-                "run",
-                "mlx_audio.tts.generate",
-                "--model",
-                TTS_MODELS.high,
-                "--text",
-                text.trim(),
-                "--ref_audio",
-                resolvedRef,
-                // "--play",
-                "--output",
-                voiceDir,
-                "--audio_format",
-                "mp3",
-                // "--stream",
-                // "--save",
-                "--instruct",
-                "slow down",
-            ], {
-                env: process.env,
-                cwd: voiceDir,
+            const proc = spawn([mlxgen, "download", "--model", model], {
                 stdout: "pipe",
                 stderr: "pipe",
             });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "VoiceChat", send);
-            const stderrText = await streamToSSE(proc.stderr, "VoiceChat", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "Download", send);
+            const stderrText = await streamToSSE(proc.stderr, "Download", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
-                const path = resolveAudioFile(voiceDir);
-                if (path) {
-                    send("complete", {
-                        success: true,
-                        path,
-                        filename: path.split(sep).pop(),
-                    });
-                }
-                else {
-                    send("error", {
-                        error: "TTS completed but no audio file was produced",
-                    });
-                }
+                send("complete", { success: true });
             }
             else {
                 send("error", {
@@ -2093,38 +2492,8 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== Render: Mux Video + Audio ==========
-    app.post("/api/render/mux-audio", async (req, res) => {
-        const { videoPath, audioPath, projectId, outputDir } = req.body || {};
-        if (!videoPath) {
-            res.status(400).json({ error: "Video path is required" });
-            return;
-        }
-        if (!audioPath) {
-            res.status(400).json({ error: "Audio path is required" });
-            return;
-        }
-        if (!projectId || !isValidProjectId(String(projectId))) {
-            res.status(400).json({ error: "Invalid project ID" });
-            return;
-        }
-        // Resolve video path — only bare .mp4 filenames in this project's output dir
-        const resolvedVideo = resolveSafeVideoPath(videoPath, projectId);
-        if (!resolvedVideo) {
-            res.status(400).json({
-                error: "Invalid video path. Provide a filename previously generated in this project.",
-            });
-            return;
-        }
-        // Resolve audio path — only bare filenames in this project's dirs
-        const resolvedAudio = resolveSafePath(audioPath, projectId);
-        if (!resolvedAudio) {
-            res.status(400).json({
-                error: "Invalid audio path. Provide a filename previously generated or uploaded to this project.",
-            });
-            return;
-        }
-        // SSE headers
+    // ========== MLX-Gen: Download FLUX.2 Klein Model ==========
+    app.post("/api/mlxgen/download-flux-model", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2135,54 +2504,22 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
         try {
-            const ffmpegBin = await getFfmpegBin();
-            const projectOutputDir = resolveOutputDir(outputDir, projectId);
-            if (!projectOutputDir) {
-                send("error", { error: "Invalid output directory." });
-                res.end();
-                return;
-            }
-            const finalFile = `voice-${Date.now()}.mp4`;
-            const finalPath = join(projectOutputDir, finalFile);
+            const mlxgen = await getMlxgenBin();
             send("progress", {
                 status: "starting",
-                label: "Muxing video and audio...",
-                outputFile: finalFile,
+                label: `Downloading model ${FLUX_KLEIN_MODEL}...`,
             });
-            const proc = spawn([
-                ffmpegBin,
-                "-y",
-                "-i",
-                resolvedVideo,
-                "-i",
-                resolvedAudio,
-                "-map",
-                "0:v",
-                "-map",
-                "1:a",
-                "-c:v",
-                "copy",
-                "-c:a",
-                "aac",
-                "-b:a",
-                "192k",
-                "-shortest",
-                finalPath,
-            ], {
+            const proc = spawn([mlxgen, "download", "--model", FLUX_KLEIN_MODEL], {
                 stdout: "pipe",
                 stderr: "pipe",
             });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "Mux", send);
-            const stderrText = await streamToSSE(proc.stderr, "Mux", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "Download", send);
+            const stderrText = await streamToSSE(proc.stderr, "Download", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
-            if (exitCode === 0 && existsSync(finalPath)) {
-                send("complete", {
-                    success: true,
-                    path: finalPath,
-                    filename: finalFile,
-                });
+            if (exitCode === 0) {
+                send("complete", { success: true });
             }
             else {
                 send("error", {
@@ -2199,16 +2536,8 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== MLX-Gen: Status ==========
-    app.get("/api/mlxgen/status", (_req, res) => {
-        res.json({
-            installed: isMlxgenInstalled(),
-            zModelDownloaded: isModelDownloaded(Z_IMAGE_MODEL),
-            fluxModelDownloaded: isModelDownloaded(FLUX_KLEIN_MODEL),
-        });
-    });
-    // ========== MLX-Gen: Install ==========
-    app.post("/api/mlxgen/install", async (_req, res) => {
+    // ========== MLX-Gen: Download SeedVR2 Model ==========
+    app.post("/api/mlxgen/download-seedvr2-model", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2219,18 +2548,18 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
         try {
-            const uvPath = await getUvPath();
+            const mlxgen = await getMlxgenBin();
             send("progress", {
                 status: "starting",
-                label: "Installing mlx-gen...",
+                label: `Downloading model ${SEEDVR2_MODEL}...`,
             });
-            const proc = spawn([uvPath, "tool", "install", "--upgrade", "mlx-gen"], {
+            const proc = spawn([mlxgen, "download", "--model", SEEDVR2_MODEL], {
                 stdout: "pipe",
                 stderr: "pipe",
             });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "Install", send);
-            const stderrText = await streamToSSE(proc.stderr, "Install", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "Download", send);
+            const stderrText = await streamToSSE(proc.stderr, "Download", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
@@ -2251,8 +2580,25 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== MLX-Gen: Download Z-Image Model ==========
-    app.post("/api/mlxgen/download-z-model", async (_req, res) => {
+    // ========== H3: Download Model ==========
+    app.get("/api/h3/status", (_req, res) => {
+        res.json({ downloaded: isH3ModelDownloaded() });
+    });
+    // ========== Hugging Face CLI + LTX Video Model ==========
+    app.get("/api/hf/status", (_req, res) => {
+        res.json({
+            installed: whichSync("hf") !== null,
+            ltxDownloaded: isModelDownloaded("dgrauet/ltx-2.3-mlx-q8"),
+            ltxBaseDownloaded: isModelDownloaded("dgrauet/ltx-2.3-mlx"),
+            ttsDownloaded: isModelDownloaded("Qwen/Qwen3-TTS-12Hz-1.7B-Base"),
+            mlxVlmDownloaded: isModelDownloaded(MLX_VLM_MODEL),
+        });
+    });
+    // ========== Dots-TTS: Status + Model Download ==========
+    app.get("/api/dots-tts/status", (_req, res) => {
+        res.json({ downloaded: isDotsTtsModelDownloaded() });
+    });
+    app.post("/api/dots-tts/download-model", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2262,20 +2608,24 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         const send = (event, data) => {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
-        const model = Z_IMAGE_MODEL;
         try {
-            const mlxgen = await getMlxgenBin();
+            ensureDir(DOTS_TTS_FOLDER);
             send("progress", {
                 status: "starting",
-                label: `Downloading model ${model}...`,
-            });
-            const proc = spawn([mlxgen, "download", "--model", model], {
-                stdout: "pipe",
-                stderr: "pipe",
+                label: "Downloading dots-tts model (mf-int4)...",
             });
+            const proc = spawn([
+                "hf",
+                "download",
+                "shraey/dots-tts-mlx",
+                "--include",
+                "mf-int4/*",
+                "--local-dir",
+                "./dots-tts-mlx-weights",
+            ], { cwd: DOTS_TTS_FOLDER, stdout: "pipe", stderr: "pipe" });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "Download", send);
-            const stderrText = await streamToSSE(proc.stderr, "Download", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "dots-tts", send);
+            const stderrText = await streamToSSE(proc.stderr, "dots-tts", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
@@ -2296,8 +2646,7 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== MLX-Gen: Download FLUX.2 Klein Model ==========
-    app.post("/api/mlxgen/download-flux-model", async (_req, res) => {
+    app.post("/api/hf/install", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2308,18 +2657,14 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
         };
         try {
-            const mlxgen = await getMlxgenBin();
             send("progress", {
                 status: "starting",
-                label: `Downloading model ${FLUX_KLEIN_MODEL}...`,
-            });
-            const proc = spawn([mlxgen, "download", "--model", FLUX_KLEIN_MODEL], {
-                stdout: "pipe",
-                stderr: "pipe",
+                label: "Installing huggingface-cli...",
             });
+            const proc = spawn(["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash"], { stdout: "pipe", stderr: "pipe" });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "Download", send);
-            const stderrText = await streamToSSE(proc.stderr, "Download", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "HF Install", send);
+            const stderrText = await streamToSSE(proc.stderr, "HF Install", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
@@ -2340,20 +2685,7 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    // ========== H3: Download Model ==========
-    app.get("/api/h3/status", (_req, res) => {
-        res.json({ downloaded: isH3ModelDownloaded() });
-    });
-    // ========== Hugging Face CLI + LTX Video Model ==========
-    app.get("/api/hf/status", (_req, res) => {
-        res.json({
-            installed: whichSync("hf") !== null,
-            ltxDownloaded: isModelDownloaded("dgrauet/ltx-2.3-mlx-q8"),
-            ttsDownloaded: isModelDownloaded("Qwen/Qwen3-TTS-12Hz-1.7B-Base"),
-            mlxVlmDownloaded: isModelDownloaded(MLX_VLM_MODEL),
-        });
-    });
-    app.post("/api/hf/install", async (_req, res) => {
+    app.post("/api/hf/download-ltx", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2366,12 +2698,15 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         try {
             send("progress", {
                 status: "starting",
-                label: "Installing huggingface-cli...",
+                label: "Downloading dgrauet/ltx-2.3-mlx-q8...",
+            });
+            const proc = spawn(["hf", "download", "dgrauet/ltx-2.3-mlx-q8"], {
+                stdout: "pipe",
+                stderr: "pipe",
             });
-            const proc = spawn(["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash"], { stdout: "pipe", stderr: "pipe" });
             activeProc = proc;
-            const stdoutPromise = streamToSSE(proc.stdout, "HF Install", send);
-            const stderrText = await streamToSSE(proc.stderr, "HF Install", send);
+            const stdoutPromise = streamToSSE(proc.stdout, "HF Download", send);
+            const stderrText = await streamToSSE(proc.stderr, "HF Download", send);
             await stdoutPromise;
             const exitCode = await proc.exited;
             if (exitCode === 0) {
@@ -2392,7 +2727,7 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
             res.end();
         }
     });
-    app.post("/api/hf/download-ltx", async (_req, res) => {
+    app.post("/api/hf/download-ltx-base", async (_req, res) => {
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -2405,9 +2740,9 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         try {
             send("progress", {
                 status: "starting",
-                label: "Downloading dgrauet/ltx-2.3-mlx-q8...",
+                label: "Downloading dgrauet/ltx-2.3-mlx...",
             });
-            const proc = spawn(["hf", "download", "dgrauet/ltx-2.3-mlx-q8"], {
+            const proc = spawn(["hf", "download", "dgrauet/ltx-2.3-mlx"], {
                 stdout: "pipe",
                 stderr: "pipe",
             });
@@ -3041,37 +3376,6 @@ export async function renderMediaRoutes({ app, getUvPath, }) {
         writeCharacters(characters);
         res.json(removed);
     });
-    // Save an extracted video frame into the project's extracted-frames folder.
-    app.post("/api/extracted-frames", (req, res) => {
-        const { image, filename, projectId } = req.body || {};
-        if (!image) {
-            res.status(400).json({ error: "Image data is required (base64)" });
-            return;
-        }
-        if (!projectId || !isValidProjectId(String(projectId))) {
-            res.status(400).json({ error: "Invalid project ID" });
-            return;
-        }
-        try {
-            const base64 = String(image).replace(/^data:[^;]+;base64,/, "");
-            const buffer = Buffer.from(base64, "base64");
-            const dir = join(EXTRACTED_FRAMES_DIR, String(projectId));
-            ensureDir(dir);
-            const safeName = (filename || `frame-${Date.now()}.png`).replace(/[^a-zA-Z0-9._-]/g, "_");
-            writeFileSync(join(dir, safeName), buffer);
-            res.json({
-                success: true,
-                path: join(dir, safeName),
-                filename: safeName,
-                size: buffer.length,
-            });
-        }
-        catch (e) {
-            res
-                .status(500)
-                .json({ error: "Failed to save frame", details: String(e) });
-        }
-    });
     // Open project folder in Finder
     app.post("/api/projects/:id/open-folder", (req, res) => {
         const { type } = req.body || {};