@mafdet/cli 1.4.18 → 1.4.29

package/dist/commands/transcribe.d.ts

@@ -0,0 +1,6 @@
+import { ExitCode } from "../output/exit-codes.js";
+import { type CommandIo } from "./runtime.js";
+export declare function transcribeCommand(argv: readonly string[], io: CommandIo): Promise<ExitCode>;
+/** Container magic numbers. Returns null for anything not recognised. */
+export declare function sniffFormat(buffer: Buffer): string | null;
+//# sourceMappingURL=transcribe.d.ts.map

package/dist/commands/transcribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../src/commands/transcribe.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAsBtB,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC,QAAQ,CAAC,CAoFnB;AAqED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczD"}

package/dist/commands/transcribe.js

@@ -0,0 +1,177 @@
+import { readFileSync, statSync } from "node:fs";
+import { z } from "zod";
+import { parseApiData } from "../api/validate.js";
+import { ApiError } from "../api/errors.js";
+import { assertSurface, fetchCatalog, SurfaceMismatchError, } from "../api/models.js";
+import { ExitCode } from "../output/exit-codes.js";
+import { buildRuntime, reportError, writeHumanError, requireApiKey, } from "./runtime.js";
+const USAGE = `Usage:
+  mafdet transcribe <file> [--model <id>] [--prompt <text>] [--json]
+
+Turns a recording into text. The audio is sent inline, so it must fit the
+gateway's 25 MB request limit — base64 inflates it by a third, which caps the
+file at about 18 MB (roughly 10 minutes of 16 kHz mono WAV). Longer recordings
+have to be split; the model's own 60-minute limit is not reachable this way.
+`;
+/** DEFAULT_MODEL is the file-transcription model, not the streaming one. */
+const DEFAULT_MODEL = "gemini-3.5-transcribe";
+/**
+ * 18 MiB. nginx allows 25 MB on `location /v1/` and base64 costs a third, so
+ * this is the largest raw file whose encoded body still fits, with room for the
+ * JSON envelope. Checked locally so a 40 MB file fails in a millisecond with a
+ * sentence, rather than after a long upload with a 413.
+ */
+const MAX_BYTES = 18 * 1024 * 1024;
+export async function transcribeCommand(argv, io) {
+    try {
+        const runtime = buildRuntime(io);
+        requireApiKey(runtime.config);
+        let model = DEFAULT_MODEL;
+        let prompt = "Transcribe this audio.";
+        let json = false;
+        const positional = [];
+        for (let i = 0; i < argv.length; i += 1) {
+            const arg = argv[i];
+            const next = () => argv[(i += 1)];
+            if (arg === "--model")
+                model = next() ?? "";
+            else if (arg === "--prompt")
+                prompt = next() ?? "";
+            else if (arg === "--json")
+                json = true;
+            else if (arg.startsWith("--")) {
+                io.stderr(`mafdet transcribe: unknown option '${arg}'\n${USAGE}`);
+                return ExitCode.Usage;
+            }
+            else
+                positional.push(arg);
+        }
+        if (positional.length !== 1) {
+            io.stderr(`mafdet transcribe: one audio file is required\n${USAGE}`);
+            return ExitCode.Usage;
+        }
+        if (!model) {
+            io.stderr("mafdet transcribe: --model needs a value\n");
+            return ExitCode.Usage;
+        }
+        const path = positional[0];
+        const audio = readAudio(path, io);
+        if (audio === null)
+            return ExitCode.Usage;
+        const catalog = await fetchCatalog(runtime.accountPlane).catch(() => []);
+        assertSurface(catalog, model, "CHAT_COMPLETIONS");
+        const body = {
+            model,
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        { type: "text", text: prompt },
+                        {
+                            type: "input_audio",
+                            input_audio: { data: audio.base64, format: audio.format },
+                        },
+                    ],
+                },
+            ],
+        };
+        const { data: raw } = await runtime.dataPlane.postJson("/chat/completions", body);
+        const data = parseApiData(responseSchema, raw, "transcribe API");
+        const text = data.choices[0]?.message.content;
+        if (typeof text !== "string" || text.length === 0) {
+            io.stderr("mafdet transcribe: the model returned no text. That usually means no speech was detected in the file.\n");
+            return ExitCode.Unavailable;
+        }
+        io.stdout(json ? `${JSON.stringify({ text }, null, 2)}\n` : `${text}\n`);
+        return ExitCode.Ok;
+    }
+    catch (error) {
+        if (error instanceof SurfaceMismatchError) {
+            writeHumanError(io, `mafdet transcribe: ${error.message}\n`);
+            return ExitCode.Usage;
+        }
+        if (error instanceof ApiError && error.status === 413) {
+            writeHumanError(io, "mafdet transcribe: the gateway rejected the upload as too large. Split the recording and transcribe each part.\n");
+            return ExitCode.Usage;
+        }
+        return reportError(error, io);
+    }
+}
+/**
+ * Deliberately NOT the shared chat schemas. Both of them insist on at least one
+ * choice, and this model legitimately returns `choices: []` when the recording
+ * holds no speech (verified against Vertex directly, 2026-08-29) — so reusing
+ * them turns an ordinary outcome into "returned an invalid response at choices",
+ * which is both wrong and unactionable.
+ */
+const responseSchema = z
+    .object({
+    choices: z.array(z
+        .object({
+        message: z
+            .object({ content: z.string().nullable().optional() })
+            .passthrough(),
+    })
+        .passthrough()),
+    usage: z.unknown().optional(),
+})
+    .passthrough();
+/**
+ * Reads the file and names its format from the bytes, never the extension — a
+ * `.wav` holding an MP3 is common and the extension would send the wrong label.
+ *
+ * The label barely matters in practice: the provider sniffs the content and
+ * ignores the declared type (measured 2026-09-03 — the same WAV bytes labelled
+ * wav, mp3 and flac all returned an identical 25 audio tokens). It is sent
+ * honestly anyway, and an unrecognised header is refused here so a text file
+ * cannot be uploaded and billed as audio.
+ */
+function readAudio(path, io) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        io.stderr(`mafdet transcribe: cannot read '${path}'\n`);
+        return null;
+    }
+    if (size === 0) {
+        io.stderr(`mafdet transcribe: '${path}' is empty\n`);
+        return null;
+    }
+    if (size > MAX_BYTES) {
+        io.stderr(`mafdet transcribe: '${path}' is ${mib(size)} MiB; the limit is ${mib(MAX_BYTES)} MiB. Split the recording and transcribe each part.\n`);
+        return null;
+    }
+    const buffer = readFileSync(path);
+    const format = sniffFormat(buffer);
+    if (format === null) {
+        io.stderr(`mafdet transcribe: '${path}' does not look like audio (unrecognised file header)\n`);
+        return null;
+    }
+    return { base64: buffer.toString("base64"), format };
+}
+/** Container magic numbers. Returns null for anything not recognised. */
+export function sniffFormat(buffer) {
+    const ascii = (start, end) => buffer.subarray(start, end).toString("latin1");
+    if (buffer.length < 12)
+        return null;
+    if (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WAVE")
+        return "wav";
+    if (ascii(0, 4) === "fLaC")
+        return "flac";
+    if (ascii(0, 4) === "OggS")
+        return "ogg";
+    if (ascii(4, 8) === "ftyp")
+        return "m4a";
+    if (ascii(0, 3) === "ID3")
+        return "mp3";
+    // MPEG audio frame sync: 11 set bits. 0xFFF1/0xFFF9 are ADTS AAC.
+    if (buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0) {
+        return (buffer[1] & 0x16) === 0x10 ? "aac" : "mp3";
+    }
+    return null;
+}
+function mib(bytes) {
+    return (bytes / (1024 * 1024)).toFixed(1);
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAmElD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyGpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAgBA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAoElD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4GpE"}

package/dist/index.js

@@ -9,6 +9,7 @@ import { configCommand } from "./commands/config.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { embedCommand } from "./commands/embed.js";
 import { speechCommand } from "./commands/speech.js";
+import { transcribeCommand } from "./commands/transcribe.js";
 import { modelsCommand } from "./commands/models.js";
 import { sessionsCommand } from "./commands/sessions.js";
 import { ExitCode } from "./output/exit-codes.js";
@@ -34,6 +35,7 @@ Commands:
   chat              Send a prompt to a model
   embed             Turn text into a vector
   speech            Turn text into an audio file
+  transcribe        Turn a recording into text
   models list       List the models this key can call
   models show       Describe one model
   account balance   Wallet balance and bonus
@@ -153,6 +155,9 @@ export async function run(argv) {
     if (command === "embed") {
         return embedCommand(argv.slice(1), { ...io, readStdin });
     }
+    if (command === "transcribe") {
+        return transcribeCommand(argv.slice(1), io);
+    }
     if (command === "speech") {
         return speechCommand(argv.slice(1), { ...io, readStdin });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mafdet/cli",
-  "version": "1.4.18",
+  "version": "1.4.29",
   "description": "Mafdet AI command line — model calls, account queries, and a permissioned local agent.",
   "type": "module",
   "license": "MIT",