@drakulavich/kesha-voice-kit 1.8.2 → 1.9.0

package/README.md

@@ -38,6 +38,7 @@ Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-m
 kesha audio.ogg                            # transcribe (plain text)
 kesha --format transcript audio.ogg        # text + language/confidence
 kesha --format json audio.ogg              # full JSON with lang fields
+kesha --json --timestamps audio.ogg        # JSON with timestamped segments
 kesha --toon audio.ogg                     # compact LLM-friendly TOON
 kesha --verbose audio.ogg                  # show language detection details
 kesha --lang en audio.ogg                  # warn if detected language differs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.8.2"
+    "version": "1.9.0"
   },
   "scripts": {
     "test": "bun test",

package/src/cli/main.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from "citty";
 import { detect } from "tinyld";
-import { transcribe } from "../lib";
+import { transcribeWithSegments } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
@@ -23,6 +23,7 @@ interface MainCommandArgs {
   debug: boolean;
   vad: boolean;
   "no-vad": boolean;
+  timestamps: boolean;
   format?: string;
   lang?: string;
 }
@@ -57,6 +58,11 @@ export const mainCommand = defineCommand({
       description: "Output results as TOON (compact, LLM-friendly encoding of the same data as --json)",
       default: false,
     },
+    timestamps: {
+      type: "boolean",
+      description: "Include timestamped transcript segments in JSON/TOON output",
+      default: false,
+    },
     verbose: {
       type: "boolean",
       description: "Show language detection details",
@@ -99,6 +105,10 @@ export const mainCommand = defineCommand({
       log.error("--vad and --no-vad are mutually exclusive.");
       process.exit(2);
     }
+    if (args.timestamps && !(args.json || args.toon || args.format === "json")) {
+      log.error("--timestamps requires --json, --toon, or --format json.");
+      process.exit(2);
+    }
     const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
 
     if (files.length === 0) {
@@ -114,11 +124,12 @@ export const mainCommand = defineCommand({
     for (const file of files) {
       const startedAt = performance.now();
       try {
-        // Run audio lang-id and transcription concurrently
-        const [audioResult, text] = await Promise.all([
+        // Run audio lang-id and transcription concurrently.
+        const [audioResult, transcript] = await Promise.all([
           wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
-          transcribe(file, { vad: vadMode }),
+          transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps }),
         ]);
+        const { text, segments } = transcript;
 
         let audioLanguage: LangDetectResult | undefined;
         if (audioResult && audioResult.code) {
@@ -145,14 +156,18 @@ export const mainCommand = defineCommand({
         const mismatchWarning = checkLanguageMismatch(args.lang, lang);
         if (mismatchWarning) log.warn(`${file}: ${mismatchWarning}`);
 
-        results.push({
+        const result: TranscribeResult = {
           file,
           text,
           lang,
           audioLanguage,
           textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
           sttTimeMs: Math.round(performance.now() - startedAt),
-        });
+        };
+        if (args.timestamps) {
+          result.segments = segments;
+        }
+        results.push(result);
       } catch (err: unknown) {
         hasError = true;
         const message = err instanceof Error ? err.message : String(err);

package/src/engine.ts

@@ -8,6 +8,17 @@ export interface LangDetectResult {
   confidence: number;
 }
 
+export interface TranscriptionSegment {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export interface TranscriptionOutput {
+  text: string;
+  segments: TranscriptionSegment[];
+}
+
 const DEFAULT_ENGINE_BIN_PATH = join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
 
 /**
@@ -67,6 +78,57 @@ export async function transcribeEngine(
   return stdout;
 }
 
+function parseTranscriptionOutput(stdout: string): TranscriptionOutput {
+  const parsed = JSON.parse(stdout);
+  if (typeof parsed?.text !== "string" || !Array.isArray(parsed?.segments)) {
+    throw new Error("Invalid transcription JSON returned by kesha-engine");
+  }
+
+  const segments = parsed.segments.map((segment: unknown) => {
+    const s = segment as Record<string, unknown>;
+    if (
+      typeof s.start !== "number" ||
+      typeof s.end !== "number" ||
+      typeof s.text !== "string"
+    ) {
+      throw new Error("Invalid transcription segment returned by kesha-engine");
+    }
+    return {
+      start: s.start,
+      end: s.end,
+      text: s.text,
+    };
+  });
+
+  return { text: parsed.text, segments };
+}
+
+export async function transcribeEngineWithSegments(
+  audioPath: string,
+  opts: TranscribeEngineOptions = {},
+): Promise<TranscriptionOutput> {
+  const caps = await getEngineCapabilities();
+  if (!caps?.features.includes("transcribe.segments")) {
+    throw new Error(
+      "Timestamped segments require a newer kesha-engine. Run `kesha install` after upgrading Kesha Voice Kit.",
+    );
+  }
+
+  const args = ["transcribe", audioPath, "--json"];
+  if (opts.vad === "on") args.push("--vad");
+  else if (opts.vad === "off") args.push("--no-vad");
+  const { stdout, stderr, exitCode } = await runEngine(args);
+  if (exitCode !== 0) {
+    throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
+  }
+  try {
+    return parseTranscriptionOutput(stdout);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${message}: ${stdout}`);
+  }
+}
+
 export function parseLangResult(stdout: string): LangDetectResult | null {
   try {
     const parsed = JSON.parse(stdout);
@@ -99,12 +161,22 @@ export interface EngineCapabilities {
   features: string[];
 }
 
+let cachedEngineCapabilities:
+  | { binPath: string; capabilities: EngineCapabilities }
+  | null = null;
+
 export async function getEngineCapabilities(): Promise<EngineCapabilities | null> {
-  if (!isEngineInstalled()) return null;
+  const binPath = getEngineBinPath();
+  if (cachedEngineCapabilities?.binPath === binPath) {
+    return cachedEngineCapabilities.capabilities;
+  }
+  if (!existsSync(binPath)) return null;
   const { stdout, exitCode } = await runEngine(["--capabilities-json"]);
   if (exitCode !== 0) return null;
   try {
-    return JSON.parse(stdout) as EngineCapabilities;
+    const capabilities = JSON.parse(stdout) as EngineCapabilities;
+    cachedEngineCapabilities = { binPath, capabilities };
+    return capabilities;
   } catch {
     return null;
   }

package/src/lib.ts

@@ -1,8 +1,13 @@
 import { existsSync } from "fs";
-import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
+import {
+  transcribe as internalTranscribe,
+  transcribeWithSegments as internalTranscribeWithSegments,
+  type TranscribeOptions,
+} from "./transcribe";
 import { downloadEngine } from "./engine-install";
 
 export type { TranscribeOptions };
+export type { TranscriptionOutput, TranscriptionSegment } from "./engine";
 export { downloadEngine as downloadModel };
 export { say, type SayOptions, SayError } from "./say";
 
@@ -38,3 +43,18 @@ export async function transcribe(
 
   return internalTranscribe(audioPath, { ...options, silent: true });
 }
+
+export async function transcribeWithSegments(
+  audioPath: string,
+  options: TranscribeOptions = {},
+) {
+  if (!existsSync(audioPath)) {
+    throw new Error(`File not found: ${audioPath}`);
+  }
+
+  return internalTranscribeWithSegments(audioPath, {
+    ...options,
+    timestamps: true,
+    silent: true,
+  });
+}

package/src/transcribe.ts

@@ -1,14 +1,30 @@
-import { isEngineInstalled, transcribeEngine, type VadMode } from "./engine";
+import {
+  isEngineInstalled,
+  transcribeEngine,
+  transcribeEngineWithSegments,
+  type TranscriptionOutput,
+  type VadMode,
+} from "./engine";
 
 export type { VadMode };
+export type { TranscriptionOutput };
 
 export interface TranscribeOptions {
   silent?: boolean;
   /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
   vad?: VadMode;
+  /** Request timestamped transcript segments from the engine. */
+  timestamps?: boolean;
 }
 
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
+  return (await transcribeWithSegments(audioPath, opts)).text;
+}
+
+export async function transcribeWithSegments(
+  audioPath: string,
+  opts: TranscribeOptions = {},
+): Promise<TranscriptionOutput> {
   if (!isEngineInstalled()) {
     throw new Error(
       "Error: No transcription backend is installed\n\n" +
@@ -20,5 +36,10 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
     );
   }
 
-  return transcribeEngine(audioPath, { vad: opts.vad });
+  if (opts.timestamps) {
+    return transcribeEngineWithSegments(audioPath, { vad: opts.vad });
+  }
+
+  const text = await transcribeEngine(audioPath, { vad: opts.vad });
+  return { text, segments: [] };
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { LangDetectResult } from "./engine";
+import type { LangDetectResult, TranscriptionSegment } from "./engine";
 
 /**
  * One row of `kesha --json` / `kesha --toon` output. Canonical output shape
@@ -11,8 +11,10 @@ export type TranscribeResult = {
   lang: string;
   audioLanguage?: LangDetectResult;
   textLanguage?: LangDetectResult;
+  /** Timestamped transcript segments when requested via `--timestamps`. */
+  segments?: TranscriptionSegment[];
   /** Wall-clock time around the engine subprocess calls for this file, ms. See #139. */
   sttTimeMs?: number;
 };
 
-export type { LangDetectResult };
+export type { LangDetectResult, TranscriptionSegment };