whisper-windows-mcp 1.5.1 → 1.7.0

package/dist/index.js

@@ -7,8 +7,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { execFile } from "child_process";
-import { existsSync, unlinkSync, readdirSync, writeFileSync, readFileSync } from "fs";
+import { execFile, spawn } from "child_process";
+import { existsSync, unlinkSync, readdirSync, writeFileSync, readFileSync, mkdirSync, openSync, closeSync, statSync, } from "fs";
 import { cpus, tmpdir } from "os";
 import { join, extname, basename, dirname } from "path";
 import { promisify } from "util";
@@ -53,6 +53,139 @@ async function isWhisperRunning() {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Background job architecture (Priorities 4 + 5)
+// ---------------------------------------------------------------------------
+const JOBS_DIR = join(tmpdir(), "whisper-mcp-jobs");
+function ensureJobsDir() {
+    mkdirSync(JOBS_DIR, { recursive: true });
+}
+async function spawnDetached(filePath, model, language, threads) {
+    ensureJobsDir();
+    const jobId = `job_${Date.now()}`;
+    const logPath = join(JOBS_DIR, `${jobId}.log`);
+    const jobPath = join(JOBS_DIR, `${jobId}.json`);
+    // Convert to WAV first if needed (fast, blocking — keeps things simple)
+    let transcribeFrom = filePath;
+    let isTmp = false;
+    if (needsConversion(filePath)) {
+        transcribeFrom = await convertToWav(filePath);
+        isTmp = true;
+    }
+    // Build args — use -otxt so whisper writes outputfile.txt itself
+    const outputBase = filePath.replace(/\.[^.]+$/, "");
+    const outputPath = outputBase + ".txt";
+    const args = [
+        "-m", model,
+        "-f", transcribeFrom,
+        "-l", language,
+        "-t", String(threads),
+        "-otxt",
+        "-of", outputBase,
+    ];
+    // Spawn detached, redirect both stdout+stderr to log file
+    const logFd = openSync(logPath, "w");
+    const child = spawn(WHISPER_CLI_PATH, args, {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        windowsHide: true,
+    });
+    closeSync(logFd);
+    child.unref();
+    const pid = child.pid ?? 0;
+    const job = {
+        jobId,
+        pid,
+        sourceFile: filePath,
+        transcribeFrom,
+        isTmp,
+        outputPath,
+        logPath,
+        jobPath,
+        startTime: new Date().toISOString(),
+        model,
+        language,
+        threads,
+        durationSec: 0,
+        status: "running",
+    };
+    writeFileSync(jobPath, JSON.stringify(job, null, 2), "utf8");
+    return { jobId, pid };
+}
+async function isPidRunning(pid) {
+    try {
+        const { stdout } = await execFileAsync("tasklist", ["/FI", `PID eq ${pid}`, "/NH"], { windowsHide: true });
+        return stdout.toLowerCase().includes("whisper-cli.exe");
+    }
+    catch {
+        return false;
+    }
+}
+function parseLastTimestamp(logContent) {
+    // whisper outputs: [00:01:30.000 --> 00:01:35.000]  text
+    const re = /\[(\d{2}):(\d{2}):(\d{2})\.\d{3} -->/g;
+    let lastSec = 0;
+    let m;
+    while ((m = re.exec(logContent)) !== null) {
+        const sec = parseInt(m[1], 10) * 3600 + parseInt(m[2], 10) * 60 + parseInt(m[3], 10);
+        if (sec > lastSec)
+            lastSec = sec;
+    }
+    return lastSec;
+}
+async function readJobProgress(jobId) {
+    const jobPath = join(JOBS_DIR, `${jobId}.json`);
+    if (!existsSync(jobPath)) {
+        return `❌ Job not found: ${jobId}\n\nThe job file may have been deleted or the ID is incorrect.`;
+    }
+    const job = JSON.parse(readFileSync(jobPath, "utf8"));
+    // Read log
+    let logContent = "";
+    if (existsSync(job.logPath)) {
+        logContent = readFileSync(job.logPath, "utf8");
+    }
+    const lastSec = parseLastTimestamp(logContent);
+    const isRunning = await isPidRunning(job.pid);
+    const outputExists = existsSync(job.outputPath);
+    // Completed
+    if (!isRunning && outputExists) {
+        job.status = "complete";
+        writeFileSync(job.jobPath, JSON.stringify(job, null, 2), "utf8");
+        // Clean up tmp wav if present
+        if (job.isTmp && existsSync(job.transcribeFrom)) {
+            try {
+                unlinkSync(job.transcribeFrom);
+            }
+            catch { }
+        }
+        const transcript = readFileSync(job.outputPath, "utf8").trim();
+        return (`✅ Complete!\n\n` +
+            `Source: ${basename(job.sourceFile)}\n` +
+            `Output: ${job.outputPath}\n\n` +
+            `Preview:\n${transcript.slice(0, 600)}${transcript.length > 600 ? "..." : ""}`);
+    }
+    // Failed
+    if (!isRunning && !outputExists) {
+        job.status = "failed";
+        writeFileSync(job.jobPath, JSON.stringify(job, null, 2), "utf8");
+        const lastLines = logContent.split(/\r?\n/).filter(l => l.trim()).slice(-5).join("\n");
+        return (`❌ Failed or cancelled.\n\n` +
+            `Source: ${basename(job.sourceFile)}\n` +
+            `No output found at: ${job.outputPath}\n\n` +
+            `Last log output:\n${lastLines || "(empty)"}`);
+    }
+    // Still running
+    const elapsed = Math.round((Date.now() - new Date(job.startTime).getTime()) / 1000);
+    const progressLine = lastSec > 0
+        ? `Last segment: ${formatDuration(lastSec)}`
+        : "Starting up...";
+    return (`⏳ In progress...\n\n` +
+        `Source: ${basename(job.sourceFile)}\n` +
+        `Job ID: ${jobId}\n` +
+        `Elapsed: ${formatDuration(elapsed)}\n` +
+        `${progressLine}\n\n` +
+        `Call check_progress with this job ID to get an update.`);
+}
 async function detectGpus() {
     try {
         const { stdout } = await execFileAsync("wmic", ["path", "win32_VideoController", "get", "name,AdapterRAM", "/format:csv"], { windowsHide: true });
@@ -95,6 +228,60 @@ function hasVulkanDll() {
     const whisperDir = dirname(WHISPER_CLI_PATH);
     return existsSync(join(whisperDir, "ggml-vulkan.dll"));
 }
+async function probeFile(filePath) {
+    try {
+        const { stdout } = await execFileAsync(FFMPEG_PATH.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1").replace(/ffmpeg$/i, "ffprobe"), [
+            "-v", "quiet",
+            "-print_format", "json",
+            "-show_format",
+            "-show_streams",
+            filePath,
+        ], { windowsHide: true, maxBuffer: 10 * 1024 * 1024 });
+        const data = JSON.parse(stdout);
+        const fmt = data.format ?? {};
+        const streams = data.streams ?? [];
+        const audioStream = streams.find((s) => s.codec_type === "audio");
+        const durationSec = parseFloat(fmt.duration ?? "0") || 0;
+        const sizeMb = parseInt(fmt.size ?? "0", 10) / (1024 * 1024);
+        const bitrate = Math.round(parseInt(fmt.bit_rate ?? "0", 10) / 1000);
+        const codec = audioStream?.codec_name ?? fmt.format_name?.split(",")[0] ?? "unknown";
+        return {
+            filePath,
+            fileName: basename(filePath),
+            durationSec,
+            sizeMb,
+            codec,
+            bitrate,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function formatDuration(sec) {
+    if (!sec)
+        return "?:??";
+    const h = Math.floor(sec / 3600);
+    const m = Math.floor((sec % 3600) / 60);
+    const s = Math.floor(sec % 60);
+    if (h > 0)
+        return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+    return `${m}:${String(s).padStart(2, "0")}`;
+}
+function estimateTime(durationSec, gpu) {
+    if (!durationSec)
+        return "?";
+    // CPU: ~1.5x realtime on Ryzen 7 2700x with medium.en
+    // GPU: ~0.12x realtime on Vega 56 via Vulkan with medium.en (~8x faster than CPU)
+    const ratio = gpu ? 0.12 : 1.5;
+    const estSec = Math.round(durationSec * ratio);
+    if (estSec < 60)
+        return `~${estSec}s`;
+    return `~${Math.round(estSec / 60)}m`;
+}
+function padEnd(str, len) {
+    return str.length >= len ? str.slice(0, len) : str + " ".repeat(len - str.length);
+}
 function needsConversion(filePath) {
     return !NATIVE_EXTENSIONS.includes(extname(filePath).toLowerCase());
 }
@@ -186,7 +373,7 @@ function getFiles(dir, recursive) {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "whisper-windows-mcp", version: "1.5.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "whisper-windows-mcp", version: "1.7.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -195,8 +382,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "Natively supports mp3 and wav. Automatically converts mp4, mkv, avi, mov, " +
                 "webm, m4a, flac, ogg etc. via FFmpeg — no manual conversion needed. " +
                 "Can output plain text, timestamps, JSON, or SRT subtitle files. " +
-                "WARNING: files over 30 minutes cannot be cancelled cleanly from Claude — " +
-                "use Task Manager to kill the process if needed.",
+                "For files that may take more than 4 minutes, set background=true to run as a detached job " +
+                "and use check_progress to monitor it.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -210,10 +397,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     },
                     threads: { type: "number", description: `CPU threads. Defaults to ${WHISPER_THREADS} of ${SYSTEM_THREADS}.` },
                     save_to_file: { type: "boolean", description: "Save transcript as .txt next to the source file.", default: false },
+                    background: { type: "boolean", description: "Run as a detached background job. Returns a job ID immediately. Use check_progress to monitor. Recommended for files over 10 minutes.", default: false },
                 },
                 required: ["file_path"],
             },
         },
+        {
+            name: "check_progress",
+            description: "Check the status of a background transcription job started with transcribe_audio (background=true). " +
+                "Returns current progress, elapsed time, last processed timestamp, and the transcript when complete. " +
+                "Call this repeatedly until the job shows as complete or failed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    job_id: { type: "string", description: "Job ID returned by transcribe_audio when background=true." },
+                },
+                required: ["job_id"],
+            },
+        },
         {
             name: "transcribe_batch",
             description: "Transcribe multiple audio/video files in a folder interactively, one file at a time. " +
@@ -258,6 +459,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Verify whisper-cli.exe, model, and FFmpeg are all available. Run this first if anything fails.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: "analyze_media",
+            description: "Analyze one or more media files using FFprobe before transcribing. " +
+                "For a single file: returns duration, size, codec, and estimated transcription time on CPU and GPU. " +
+                "For a folder: scans all supported media files and returns a sorted table with the same info for each. " +
+                "Use this to plan batch work, estimate how long transcription will take, or check what's already been transcribed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Absolute Windows path to a single file or a folder.",
+                    },
+                    sort_by: {
+                        type: "string",
+                        enum: ["duration", "name", "size"],
+                        description: "For folder scans: sort order. Defaults to duration (shortest first).",
+                        default: "duration",
+                    },
+                },
+                required: ["path"],
+            },
+        },
         {
             name: "check_system",
             description: "Detect GPU hardware and verify Vulkan acceleration is available. " +
@@ -297,6 +521,97 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
     // -------------------------------------------------------------------------
+    // analyze_media
+    // -------------------------------------------------------------------------
+    if (name === "analyze_media") {
+        const targetPath = args?.path;
+        const sortBy = args?.sort_by || "duration";
+        if (!targetPath)
+            return { content: [{ type: "text", text: "path is required." }], isError: true };
+        if (!existsSync(targetPath))
+            return { content: [{ type: "text", text: `Path not found: ${targetPath}` }], isError: true };
+        // Check ffprobe is available
+        const ffprobePath = FFMPEG_PATH.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1").replace(/ffmpeg$/i, "ffprobe");
+        try {
+            await execFileAsync(ffprobePath, ["-version"], { windowsHide: true });
+        }
+        catch {
+            return {
+                content: [{ type: "text", text: "ffprobe not found. FFprobe is bundled with FFmpeg — make sure FFmpeg is installed and in your PATH." }],
+                isError: true,
+            };
+        }
+        const vulkan = hasVulkanDll();
+        // Single file
+        const stat = statSync(targetPath);
+        if (stat.isFile()) {
+            const info = await probeFile(targetPath);
+            if (!info) {
+                return { content: [{ type: "text", text: `Could not probe file: ${targetPath}\nMake sure it is a supported media file.` }], isError: true };
+            }
+            const txtPath = targetPath.replace(/\.[^.]+$/, ".txt");
+            const transcribed = existsSync(txtPath) ? "✅ already transcribed" : "⬜ not yet transcribed";
+            return {
+                content: [{
+                        type: "text",
+                        text: `📄 ${info.fileName}\n` +
+                            `${"─".repeat(40)}\n` +
+                            `Duration:   ${formatDuration(info.durationSec)}\n` +
+                            `Size:       ${info.sizeMb.toFixed(1)} MB\n` +
+                            `Codec:      ${info.codec}\n` +
+                            `Bitrate:    ${info.bitrate} kbps\n` +
+                            `Status:     ${transcribed}\n\n` +
+                            `Estimated transcription time:\n` +
+                            `  CPU:  ${estimateTime(info.durationSec, false)}\n` +
+                            `  GPU:  ${estimateTime(info.durationSec, true)}${vulkan ? "" : " (⚠️ Vulkan not detected — GPU estimate may not apply)"}`,
+                    }],
+            };
+        }
+        // Folder scan
+        const files = getFiles(targetPath, false);
+        if (files.length === 0) {
+            return { content: [{ type: "text", text: `No supported media files found in: ${targetPath}` }], isError: true };
+        }
+        const results = [];
+        for (const f of files) {
+            const info = await probeFile(f);
+            if (info)
+                results.push(info);
+        }
+        // Sort
+        if (sortBy === "name")
+            results.sort((a, b) => a.fileName.localeCompare(b.fileName));
+        else if (sortBy === "size")
+            results.sort((a, b) => a.sizeMb - b.sizeMb);
+        else
+            results.sort((a, b) => a.durationSec - b.durationSec); // duration default
+        const totalDuration = results.reduce((acc, r) => acc + r.durationSec, 0);
+        const totalSize = results.reduce((acc, r) => acc + r.sizeMb, 0);
+        const transcribedCount = results.filter(r => existsSync(r.filePath.replace(/\.[^.]+$/, ".txt"))).length;
+        const header = `${padEnd("File", 36)} ${padEnd("Duration", 8)} ${padEnd("Size", 8)} ${padEnd("CPU est", 8)} ${padEnd("GPU est", 8)} Status\n` +
+            `${"─".repeat(90)}\n`;
+        const rows = results.map(r => {
+            const done = existsSync(r.filePath.replace(/\.[^.]+$/, ".txt")) ? "✅" : "⬜";
+            return (`${padEnd(r.fileName, 36)} ` +
+                `${padEnd(formatDuration(r.durationSec), 8)} ` +
+                `${padEnd(r.sizeMb.toFixed(1) + " MB", 8)} ` +
+                `${padEnd(estimateTime(r.durationSec, false), 8)} ` +
+                `${padEnd(estimateTime(r.durationSec, true), 8)} ` +
+                done);
+        }).join("\n");
+        const summary = `\n${"─".repeat(90)}\n` +
+            `${results.length} files | Total duration: ${formatDuration(totalDuration)} | Total size: ${totalSize.toFixed(1)} MB\n` +
+            `Transcribed: ${transcribedCount}/${results.length}\n` +
+            `Total est. CPU time: ${estimateTime(totalDuration, false)} | Total est. GPU time: ${estimateTime(totalDuration, true)}` +
+            (vulkan ? "" : "\n⚠️  ggml-vulkan.dll not detected — GPU estimates may not apply");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Media analysis: ${targetPath}\n\n${header}${rows}${summary}`,
+                }],
+        };
+    }
+    // -------------------------------------------------------------------------
     // check_system
     // -------------------------------------------------------------------------
     if (name === "check_system") {
@@ -341,6 +656,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const outputFormat = (args?.output_format || "text");
         const threads = Math.min(SYSTEM_THREADS, Math.max(1, Math.round(args?.threads || WHISPER_THREADS)));
         const saveToFile = args?.save_to_file || false;
+        const background = args?.background || false;
         if (!filePath)
             return { content: [{ type: "text", text: "file_path is required." }], isError: true };
         if (!existsSync(filePath))
@@ -348,6 +664,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const configError = validatePaths();
         if (configError)
             return { content: [{ type: "text", text: configError }], isError: true };
+        // Background mode — detached process, returns immediately
+        if (background) {
+            if (await isWhisperRunning()) {
+                return {
+                    content: [{ type: "text", text: "Transcription already in progress. Wait for the current job to finish before starting another." }],
+                    isError: true,
+                };
+            }
+            try {
+                const { jobId, pid } = await spawnDetached(filePath, model, language, threads);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `⏳ Background transcription started.\n\n` +
+                                `Source: ${basename(filePath)}\n` +
+                                `Job ID: ${jobId}\n` +
+                                `PID: ${pid}\n\n` +
+                                `Call check_progress with job_id="${jobId}" to monitor progress.\n` +
+                                `Output will be saved to: ${filePath.replace(/\.[^.]+$/, ".txt")}`,
+                        }],
+                };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `Failed to start background job:\n\n${err?.message || String(err)}` }], isError: true };
+            }
+        }
+        // Blocking mode (default)
         try {
             const result = await transcribeSingle(filePath, model, language, outputFormat, threads, saveToFile);
             let response = result.text;
@@ -362,6 +705,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     // -------------------------------------------------------------------------
+    // check_progress
+    // -------------------------------------------------------------------------
+    if (name === "check_progress") {
+        const jobId = args?.job_id;
+        if (!jobId)
+            return { content: [{ type: "text", text: "job_id is required." }], isError: true };
+        try {
+            const result = await readJobProgress(jobId);
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Error reading job progress:\n\n${err?.message || String(err)}` }], isError: true };
+        }
+    }
+    // -------------------------------------------------------------------------
     // generate_subtitles
     // -------------------------------------------------------------------------
     if (name === "generate_subtitles") {
@@ -476,7 +834,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`whisper-windows-mcp v1.5.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
+    console.error(`whisper-windows-mcp v1.7.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
 }
 main().catch((err) => {
     console.error("Fatal error:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whisper-windows-mcp",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Windows-native MCP server for local audio transcription using whisper.cpp with Vulkan GPU acceleration",
   "main": "dist/index.js",
   "bin": {