dictawhisper 0.0.13 → 0.0.14

package/src/cli.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { spawn, type ChildProcess } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const exampleConfig = path.join(packageRoot, 'config.example.json');
+const serverPath = path.join(packageRoot, 'src', 'server.ts');
+const doctorPath = path.join(packageRoot, 'src', 'doctor.ts');
+const uiDir = path.join(packageRoot, 'dist', 'ui');
+
+function usage(): string {
+  return `dictawhisper — local voice journal
+
+Usage:
+  dictawhisper init [--home]     write config.example.json
+  dictawhisper doctor            check python / CUDA / ffmpeg / ollanet
+  dictawhisper start             API + inbox (default)
+  dictawhisper serve             same as start
+
+A global install serves the packaged inbox. Checkout still uses pnpm dev.
+
+Config (first hit wins):
+  $DICTA_CONFIG
+  ./config.json
+  ~/.dictawhisper/config.json
+
+Requires Node 20+ and a Python with faster-whisper. See dictawhisper.com
+`;
+}
+
+function fail(message: string, code = 1): never {
+  console.error(message);
+  process.exit(code);
+}
+
+function resolveExistingConfig(): string | null {
+  const fromEnv = process.env.DICTA_CONFIG?.trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  const inCwd = path.resolve(process.cwd(), 'config.json');
+  if (existsSync(inCwd)) return inCwd;
+  const inHome = path.join(os.homedir(), '.dictawhisper', 'config.json');
+  if (existsSync(inHome)) return inHome;
+  return null;
+}
+
+function init(home: boolean): void {
+  const dest = home
+    ? path.join(os.homedir(), '.dictawhisper', 'config.json')
+    : path.resolve(process.cwd(), 'config.json');
+  if (existsSync(dest)) {
+    fail(`Already exists: ${dest}`);
+  }
+  if (!existsSync(exampleConfig)) {
+    fail(`Missing ${exampleConfig}`);
+  }
+  mkdirSync(path.dirname(dest), { recursive: true });
+  copyFileSync(exampleConfig, dest);
+  console.log(`Wrote ${dest}`);
+  console.log('Edit whisper.python, then: dictawhisper doctor');
+}
+
+function runNode(script: string, extraEnv: NodeJS.ProcessEnv): ChildProcess {
+  return spawn(process.execPath, ['--experimental-strip-types', script], {
+    stdio: 'inherit',
+    env: { ...process.env, ...extraEnv },
+    windowsHide: false,
+  });
+}
+
+function start(): void {
+  const configFile = resolveExistingConfig();
+  if (!configFile) {
+    fail('No config.json. Run: dictawhisper init\nThen edit whisper.python and run: dictawhisper doctor');
+  }
+  if (!existsSync(uiDir)) {
+    console.warn(`[ui] no packaged inbox at ${uiDir} — API only. In a checkout: pnpm --dir client build`);
+  }
+  const child = runNode(serverPath, {
+    DICTA_CONFIG: configFile,
+    DICTA_SERVE_UI: existsSync(uiDir) ? '1' : '',
+    DICTA_UI_DIR: uiDir,
+  });
+  const shutdown = () => {
+    if (child.pid) child.kill();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  child.on('exit', (code) => process.exit(code ?? 1));
+}
+
+function doctor(): void {
+  const configFile = resolveExistingConfig();
+  if (!configFile) {
+    fail('No config.json. Run: dictawhisper init');
+  }
+  const child = runNode(doctorPath, { DICTA_CONFIG: configFile });
+  child.on('exit', (code) => process.exit(code ?? 1));
+}
+
+function main(argv: string[]): number {
+  const args = argv.slice(2);
+  if (args.includes('-h') || args.includes('--help') || args[0] === 'help') {
+    console.log(usage());
+    return 0;
+  }
+  const command = args[0] && !args[0].startsWith('-') ? args[0] : 'start';
+  if (command === 'init') {
+    init(args.includes('--home'));
+    return 0;
+  }
+  if (command === 'doctor') {
+    doctor();
+    return 0;
+  }
+  if (command === 'start' || command === 'serve') {
+    start();
+    return 0;
+  }
+  console.error(`Unknown command: ${command}\n`);
+  console.log(usage());
+  return 1;
+}
+
+const entry = process.argv[1]?.replaceAll('\\', '/');
+if (entry && (entry.endsWith('/cli.ts') || entry.endsWith('/cli.js'))) {
+  process.exitCode = main(process.argv);
+}
+
+export { main, resolveExistingConfig };

package/src/config.ts

@@ -0,0 +1,238 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { z } from 'zod';
+import { localberthGet } from './lib/localberthGet.ts';
+
+export function resolveConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd = process.cwd(),
+  home = os.homedir()
+): string {
+  const fromEnv = env.DICTA_CONFIG?.trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  const inCwd = path.resolve(cwd, 'config.json');
+  if (fs.existsSync(inCwd)) return inCwd;
+  const inHome = path.join(home, '.dictawhisper', 'config.json');
+  if (fs.existsSync(inHome)) return inHome;
+  return inCwd;
+}
+
+export const defaultConfigPath = resolveConfigPath();
+
+function resolveAgainst(configDir: string, filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(configDir, filePath);
+}
+
+function servePackagedUi(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.DICTA_SERVE_UI === '1' || env.DICTA_SERVE_UI === 'true';
+}
+
+const httpSchema = z
+  .object({
+    host: z.string().min(1).default('127.0.0.1'),
+    port: z.number().int().positive().default(8008),
+    corsOrigins: z.array(z.string()).default(['http://localhost:7777', 'http://127.0.0.1:7777']),
+    tailscale: z.boolean().default(false),
+  })
+  .default({});
+
+const watchSchema = z
+  .object({
+    roots: z.array(z.string()).default([]),
+    browserDropFolder: z.string().default('./data/audio-files'),
+    settleMinutes: z.number().nonnegative().default(30),
+    browserSettleMs: z.number().nonnegative().default(0),
+    recursiveYears: z.boolean().default(true),
+    createMissingRoots: z.boolean().default(false),
+  })
+  .default({});
+
+const whisperSchema = z
+  .object({
+    python: z.string().min(1).default('python'),
+    model: z.string().min(1).default('large-v3'),
+    device: z.string().min(1).default('cuda'),
+    computeType: z.string().min(1).default('float16'),
+    promptTerms: z.array(z.string()).default([]),
+  })
+  .default({});
+
+const queuesSchema = z
+  .object({
+    transcription: z.object({ active: z.boolean().default(true), concurrency: z.number().int().positive().default(1) }).default({}),
+    processing: z.object({ active: z.boolean().default(true), concurrency: z.number().int().positive().default(1) }).default({}),
+  })
+  .default({});
+
+const ollanetSchema = z
+  .object({
+    machine: z.string().default(''),
+    cleanModel: z.string().default(''),
+    saveChats: z.boolean().default(false),
+    required: z.boolean().default(false),
+  })
+  .default({});
+
+const journalSchema = z
+  .object({
+    index: z.string().default('./data/journal.sqlite'),
+    search: z.enum(['lex', 'semantic', 'hybrid']).default('hybrid'),
+    embedModel: z.string().default(''),
+  })
+  .default({});
+
+export const dictaConfigFileSchema = z
+  .object({
+    http: httpSchema,
+    watch: watchSchema,
+    whisper: whisperSchema,
+    audio: z.object({ preprocess: z.boolean().default(true) }).default({}),
+    queues: queuesSchema,
+    ollanet: ollanetSchema,
+    journal: journalSchema,
+  })
+  .strip();
+
+export type DictaConfig = {
+  http: {
+    host: string;
+    port: number;
+    corsOrigins: string[];
+    tailscale: boolean;
+  };
+  watch: {
+    roots: string[];
+    browserDropFolder: string;
+    settleMinutes: number;
+    browserSettleMs: number;
+    recursiveYears: boolean;
+    createMissingRoots: boolean;
+  };
+  whisper: {
+    python: string;
+    model: string;
+    device: string;
+    computeType: string;
+    promptTerms: string[];
+  };
+  audio: { preprocess: boolean };
+  queues: {
+    transcription: { active: boolean; concurrency: number };
+    processing: { active: boolean; concurrency: number };
+  };
+  ollanet: {
+    machine: string;
+    cleanModel: string;
+    saveChats: boolean;
+    required: boolean;
+  };
+  journal: {
+    index: string;
+    search: 'lex' | 'semantic' | 'hybrid';
+    embedModel: string;
+  };
+};
+
+function readJson(filePath: string): unknown {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`config is not valid JSON (${filePath}): ${detail}`);
+  }
+}
+
+export function applyConfigToEnv(config: DictaConfig): void {
+  process.env.WHISPER_MODEL = config.whisper.model;
+  process.env.WHISPER_PYTHON = config.whisper.python;
+  process.env.WHISPER_DEVICE = config.whisper.device;
+  process.env.WHISPER_COMPUTE_TYPE = config.whisper.computeType;
+}
+
+/** LocalBerth start on the UI lease sets PORT=7777. That must not become the API. */
+export function resolveApiListenPort(
+  envPort: string | undefined,
+  uiPort: number | undefined,
+  apiLeasePort: number | undefined,
+  configPort: number
+): number {
+  const n = Number(envPort);
+  if (Number.isInteger(n) && n > 0 && n !== uiPort) return n;
+  return apiLeasePort || configPort;
+}
+
+/** Combined inbox+API (npm CLI) binds the UI port so the page and /note share origin. */
+export function resolveListenPort(
+  envPort: string | undefined,
+  uiPort: number | undefined,
+  apiLeasePort: number | undefined,
+  configPort: number,
+  serveUi = false
+): number {
+  if (serveUi) return uiPort || 7777;
+  return resolveApiListenPort(envPort, uiPort, apiLeasePort, configPort);
+}
+
+export function loadConfig(configPath: string = resolveConfigPath()): DictaConfig {
+  const parsed = dictaConfigFileSchema.parse(readJson(configPath));
+  const configDir = path.dirname(path.resolve(configPath));
+  const config: DictaConfig = {
+    http: {
+      host: process.env.HOST?.trim() || parsed.http.host,
+      port: resolveListenPort(
+        process.env.PORT,
+        localberthGet('dictawhisper'),
+        localberthGet('dictawhisper-api'),
+        parsed.http.port,
+        servePackagedUi()
+      ),
+      corsOrigins: parsed.http.corsOrigins,
+      tailscale:
+        process.env.DICTA_TAILSCALE === '1' ||
+        process.env.DICTA_TAILSCALE === 'true' ||
+        parsed.http.tailscale,
+    },
+    watch: {
+      roots: parsed.watch.roots.map((root) => resolveAgainst(configDir, root)),
+      browserDropFolder: resolveAgainst(configDir, parsed.watch.browserDropFolder),
+      settleMinutes: Number(process.env.VOICE_SETTLE_MINUTES) || parsed.watch.settleMinutes,
+      browserSettleMs:
+        process.env.VOICE_BROWSER_SETTLE_MS !== undefined
+          ? Number(process.env.VOICE_BROWSER_SETTLE_MS)
+          : parsed.watch.browserSettleMs,
+      recursiveYears: parsed.watch.recursiveYears,
+      createMissingRoots: parsed.watch.createMissingRoots,
+    },
+    whisper: {
+      python: process.env.WHISPER_PYTHON?.trim() || parsed.whisper.python,
+      model: process.env.WHISPER_MODEL?.trim() || parsed.whisper.model,
+      device: process.env.WHISPER_DEVICE?.trim() || parsed.whisper.device,
+      computeType: process.env.WHISPER_COMPUTE_TYPE?.trim() || parsed.whisper.computeType,
+      promptTerms: parsed.whisper.promptTerms.map((term) => String(term).trim()).filter(Boolean),
+    },
+    audio: {
+      preprocess: parsed.audio.preprocess,
+    },
+    queues: parsed.queues,
+    ollanet: {
+      machine: process.env.OLLANET_MACHINE?.trim() || parsed.ollanet.machine,
+      cleanModel: process.env.OLLANET_CLEAN_MODEL?.trim() || parsed.ollanet.cleanModel,
+      saveChats: parsed.ollanet.saveChats,
+      required: parsed.ollanet.required,
+    },
+    journal: {
+      index: resolveAgainst(configDir, parsed.journal.index),
+      search: parsed.journal.search,
+      embedModel: process.env.DICTA_EMBED_MODEL?.trim() || parsed.journal.embedModel,
+    },
+  };
+
+  applyConfigToEnv(config);
+  return config;
+}
+
+export const configPath = resolveConfigPath();
+export const config = loadConfig(configPath);

package/src/dev.ts

@@ -0,0 +1,63 @@
+import { execSync, spawn, type ChildProcess } from 'child_process';
+import { localberthGet } from './lib/localberthGet.ts';
+
+const children: ChildProcess[] = [];
+
+function apiEnv(): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    PORT: String(localberthGet('dictawhisper-api') ?? 8008),
+  };
+}
+
+function run(command: string, args: string[], hide = true, env: NodeJS.ProcessEnv = process.env) {
+  const child = spawn(command, args, {
+    stdio: 'inherit',
+    env,
+    windowsHide: hide,
+  });
+  children.push(child);
+  child.on('error', (error) => {
+    console.error(`[dev] failed to start ${command}:`, error.message);
+    shutdown(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) return;
+    if (code && code !== 0) shutdown(code);
+  });
+}
+
+// windowsHide hides Node stdout in Git Bash; the API child must stay visible.
+// Do not inherit the UI lease PORT (7777) — the API is dictawhisper-api (8008).
+run(process.execPath, ['--experimental-strip-types', 'src/server.ts'], false, apiEnv());
+
+if (process.platform === 'win32') {
+  // pnpm is a .cmd on PATH; CreateProcess cannot run it without cmd.exe.
+  // Args are fixed literals — not user input.
+  run('cmd.exe', ['/d', '/s', '/c', 'pnpm --dir client dev']);
+} else {
+  run('pnpm', ['--dir', 'client', 'dev']);
+}
+
+function killTree(child: ChildProcess) {
+  if (!child.pid) return;
+  if (process.platform === 'win32') {
+    try {
+      execSync(`taskkill /pid ${child.pid} /T /F`, { stdio: 'ignore' });
+    } catch {
+      child.kill();
+    }
+    return;
+  }
+  child.kill();
+}
+
+function shutdown(code = 0) {
+  for (const child of children) {
+    killTree(child);
+  }
+  process.exit(code);
+}
+
+process.on('SIGINT', () => shutdown(0));
+process.on('SIGTERM', () => shutdown(0));

package/src/doctor.ts

@@ -0,0 +1,12 @@
+import fs from 'fs';
+import { config, configPath } from './config.ts';
+import { collectHealth, printHealthReport } from './lib/healthLib.ts';
+
+if (!fs.existsSync(configPath)) {
+  console.error(`[doctor] FAIL  config.json missing — copy config.example.json to ${configPath}`);
+  process.exit(1);
+}
+
+const report = await collectHealth(config, { mode: 'doctor' });
+printHealthReport(report, 'doctor');
+process.exit(report.ok ? 0 : 1);

package/src/lib/alignLib.ts

@@ -0,0 +1,154 @@
+export type WhisperWord = {
+  word: string;
+  start: number;
+  end: number;
+};
+
+export type WhisperSegment = {
+  start: number;
+  end: number;
+  text: string;
+  words?: WhisperWord[];
+};
+
+export type PlaybackCue = {
+  start: number | null;
+  end: number | null;
+  text: string;
+};
+
+const FILLERS = new Set(['uh', 'um', 'umm', 'hmm', 'yeah', 'like']);
+
+export function splitCleanedSections(cleaned: string): string[] {
+  const trimmed = String(cleaned || '').trim();
+  if (!trimmed) return [];
+  const paras = trimmed.split(/\n{2,}/).map((part) => part.trim()).filter(Boolean);
+  if (paras.length >= 2) return paras;
+  const sentences = trimmed.split(/(?<=[.!?])\s+/).map((part) => part.trim()).filter(Boolean);
+  if (sentences.length >= 2) return sentences;
+  return [trimmed];
+}
+
+function normWord(text: string): string {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .replace(/[^a-z0-9]/g, '');
+}
+
+function contentWords(text: string): string[] {
+  return String(text || '')
+    .split(/\s+/)
+    .map(normWord)
+    .filter((word) => word.length > 1 && !FILLERS.has(word));
+}
+
+export function flattenSegmentWords(segments: WhisperSegment[] | undefined): WhisperWord[] {
+  const out: WhisperWord[] = [];
+  for (const segment of segments || []) {
+    if (!Array.isArray(segment.words)) continue;
+    for (const word of segment.words) {
+      if (typeof word?.start !== 'number' || typeof word.end !== 'number') continue;
+      if (!String(word.word || '').trim()) continue;
+      out.push({ word: word.word, start: word.start, end: word.end });
+    }
+  }
+  return out;
+}
+
+type Token = WhisperWord & { key: string };
+
+function tokenizeWords(words: WhisperWord[]): Token[] {
+  return words
+    .map((word) => ({ ...word, key: normWord(word.word) }))
+    .filter((word) => word.key.length > 1 && !FILLERS.has(word.key));
+}
+
+/** Map cleaned sections onto Whisper word timestamps. Sequential; does not invent times. */
+export function alignCleanedToWords(cleaned: string, words: WhisperWord[]): PlaybackCue[] {
+  const sections = splitCleanedSections(cleaned);
+  const tokens = tokenizeWords(words);
+  if (!sections.length || !tokens.length) return [];
+
+  let cursor = 0;
+  const cues: PlaybackCue[] = [];
+
+  for (const text of sections) {
+    const needed = contentWords(text);
+    if (!needed.length) {
+      const at = tokens[Math.min(cursor, tokens.length - 1)];
+      cues.push({ start: at.start, end: at.end, text });
+      continue;
+    }
+
+    const searchEnd = Math.min(tokens.length, cursor + Math.max(30, needed.length * 4));
+    let startIdx = -1;
+    for (let i = cursor; i < searchEnd; i += 1) {
+      if (tokens[i].key === needed[0]) {
+        startIdx = i;
+        break;
+      }
+    }
+    if (startIdx < 0) {
+      cues.push({ start: null, end: null, text });
+      continue;
+    }
+
+    let wordIdx = startIdx;
+    let needIdx = 0;
+    let endIdx = startIdx;
+    while (wordIdx < tokens.length && needIdx < needed.length) {
+      if (tokens[wordIdx].key === needed[needIdx]) {
+        endIdx = wordIdx;
+        wordIdx += 1;
+        needIdx += 1;
+        continue;
+      }
+      const upcoming = tokens.slice(wordIdx + 1, wordIdx + 4).some((token) => token.key === needed[needIdx]);
+      if (upcoming) wordIdx += 1;
+      else needIdx += 1;
+    }
+
+    cues.push({
+      start: tokens[startIdx].start,
+      end: tokens[endIdx].end,
+      text,
+    });
+    cursor = endIdx + 1;
+  }
+
+  return cues;
+}
+
+export function ensurePlaybackCues(json: {
+  cleanedTranscription?: string;
+  segments?: WhisperSegment[];
+  playbackCues?: PlaybackCue[];
+  playbackCuesSource?: string;
+}): boolean {
+  const cleaned = json?.cleanedTranscription;
+  const words = flattenSegmentWords(json?.segments);
+  const sections = cleaned ? splitCleanedSections(cleaned) : [];
+
+  if (words.length && cleaned && sections.length) {
+    const existing = json.playbackCues;
+    if (
+      json.playbackCuesSource === 'words' &&
+      Array.isArray(existing) &&
+      existing.length === sections.length &&
+      existing.every((cue) => cue && typeof cue.text === 'string')
+    ) {
+      return false;
+    }
+    json.playbackCues = alignCleanedToWords(cleaned, words);
+    json.playbackCuesSource = 'words';
+    return true;
+  }
+
+  if (json.playbackCues || json.playbackCuesSource) {
+    delete json.playbackCues;
+    delete json.playbackCuesSource;
+    return true;
+  }
+  return false;
+}