@drakulavich/kesha-voice-kit 1.10.0 → 1.11.0

package/SKILL.md

@@ -45,11 +45,21 @@ kesha --json voice.ogg
 
 Use `lang` (or the more detailed `audioLanguage`/`textLanguage`) to decide how to respond.
 
+Need timestamped transcript segments for navigation, chapters, or downstream editing:
+
+```bash
+kesha --json --timestamps voice.ogg > voice.timestamps.json
+jq '.[0].segments' voice.timestamps.json
+```
+
+Each segment has `start`, `end`, and `text` fields. `--timestamps` is available for machine-readable output (`--json`, `--toon`, or `--format json`).
+
 **Formats:** .ogg, .opus, .mp3, .m4a, .wav, .flac, .webm — decoded via symphonia, no ffmpeg required.
 
 **Other output modes:**
 - `kesha audio.ogg` — plain transcript on stdout
 - `kesha --format transcript audio.ogg` — transcript + `[lang: ru, confidence: 0.99]` footer
+- `kesha --json --timestamps audio.ogg` — JSON with timestamped `segments`
 - `kesha --verbose audio.ogg` — human-readable with language info
 - `kesha --lang en audio.ogg` — warn if detected language differs (useful sanity check)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.10.0",
+  "version": "1.11.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.10.0"
+    "version": "1.11.0"
   },
   "scripts": {
     "test": "bun test",

package/src/engine.ts

@@ -1,8 +1,15 @@
 import { join } from "path";
 import { homedir } from "os";
-import { existsSync } from "fs";
+import { existsSync, statSync } from "fs";
 import { log } from "./log";
 
+/**
+ * Capability-flag string surfaced via `kesha-engine --capabilities-json`. Single
+ * source of truth so the engine, the TS CLI gate, and the integration tests
+ * can't drift. Mirrors `rust/src/transcribe.rs::TRANSCRIBE_SEGMENTS_FEATURE`.
+ */
+export const TRANSCRIBE_SEGMENTS_FEATURE = "transcribe.segments";
+
 export interface LangDetectResult {
   code: string;
   confidence: number;
@@ -108,7 +115,7 @@ export async function transcribeEngineWithSegments(
   opts: TranscribeEngineOptions = {},
 ): Promise<TranscriptionOutput> {
   const caps = await getEngineCapabilities();
-  if (!caps?.features.includes("transcribe.segments")) {
+  if (!caps?.features.includes(TRANSCRIBE_SEGMENTS_FEATURE)) {
     throw new Error(
       "Timestamped segments require a newer kesha-engine. Run `kesha install` after upgrading Kesha Voice Kit.",
     );
@@ -162,20 +169,33 @@ export interface EngineCapabilities {
 }
 
 let cachedEngineCapabilities:
-  | { binPath: string; capabilities: EngineCapabilities }
+  | { binPath: string; mtime: number; capabilities: EngineCapabilities }
   | null = null;
 
 export async function getEngineCapabilities(): Promise<EngineCapabilities | null> {
   const binPath = getEngineBinPath();
-  if (cachedEngineCapabilities?.binPath === binPath) {
+  // Cache key includes `mtimeMs` so the cache invalidates when `kesha
+  // install` overwrites the binary in-place within a single long-lived
+  // process (#248). `statSync` throws on missing-file; the catch returns
+  // `null` — same effect as the previous explicit `isEngineInstalled()`
+  // pre-flight, one fewer redundant fs call.
+  let mtime: number;
+  try {
+    mtime = statSync(binPath).mtimeMs;
+  } catch {
+    return null;
+  }
+  if (
+    cachedEngineCapabilities?.binPath === binPath &&
+    cachedEngineCapabilities.mtime === mtime
+  ) {
     return cachedEngineCapabilities.capabilities;
   }
-  if (!existsSync(binPath)) return null;
   const { stdout, exitCode } = await runEngine(["--capabilities-json"]);
   if (exitCode !== 0) return null;
   try {
     const capabilities = JSON.parse(stdout) as EngineCapabilities;
-    cachedEngineCapabilities = { binPath, capabilities };
+    cachedEngineCapabilities = { binPath, mtime, capabilities };
     return capabilities;
   } catch {
     return null;

package/src/lib.ts

@@ -44,7 +44,7 @@ export async function transcribe(
   return internalTranscribe(audioPath, { ...options, silent: true });
 }
 
-export async function transcribeWithSegments(
+export async function transcribeWithTimestamps(
   audioPath: string,
   options: TranscribeOptions = {},
 ) {
@@ -58,3 +58,10 @@ export async function transcribeWithSegments(
     silent: true,
   });
 }
+
+/**
+ * @deprecated Renamed to {@link transcribeWithTimestamps} (#248). The old
+ * name shipped briefly in v1.9.0; this alias keeps existing imports working
+ * for one minor-version cycle. Will be removed in v1.12.0.
+ */
+export const transcribeWithSegments = transcribeWithTimestamps;