@hasna/recordings 0.0.3

package/src/lib/config.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { RecordingsConfig } from "../types/index.js";
+
+export const DEFAULT_CONFIG: RecordingsConfig = {
+  openai_api_key: "",
+  enhancement_api_key: "",
+  transcription_model: "gpt-4o-mini-transcribe",
+  enhancement_model: "gpt-4o",
+  language: "en",
+  audio_format: "wav",
+  sample_rate: 16000,
+  record_command: "sox",
+  hotkey: "space",
+  auto_enhance: true,
+  enhance_triggers: [
+    "say it better",
+    "rewrite this",
+    "make it sound",
+    "clean this up",
+    "fix this",
+    "rephrase",
+    "write it properly",
+    "make it professional",
+    "improve this",
+    "polish this",
+  ],
+  db_path: "",
+  audio_dir: "",
+  max_recording_seconds: 300,
+};
+
+export function loadConfig(configPath?: string): RecordingsConfig {
+  const config = { ...DEFAULT_CONFIG };
+
+  // 1. Load from config file
+  const filePath =
+    configPath || findConfigFile() || join(getDataDir(), "config.json");
+
+  if (existsSync(filePath)) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const fileConfig = JSON.parse(raw) as Partial<RecordingsConfig>;
+      Object.assign(config, fileConfig);
+    } catch {
+      // Ignore invalid config files
+    }
+  }
+
+  // 2. Override with env vars
+  if (process.env.OPENAI_API_KEY) {
+    config.openai_api_key = process.env.OPENAI_API_KEY;
+  }
+  if (process.env.RECORDINGS_API_KEY) {
+    config.openai_api_key = process.env.RECORDINGS_API_KEY;
+  }
+  if (process.env.RECORDINGS_ENHANCEMENT_KEY) {
+    config.enhancement_api_key = process.env.RECORDINGS_ENHANCEMENT_KEY;
+  }
+  if (process.env.RECORDINGS_MODEL) {
+    config.transcription_model = process.env.RECORDINGS_MODEL;
+  }
+  if (process.env.RECORDINGS_ENHANCEMENT_MODEL) {
+    config.enhancement_model = process.env.RECORDINGS_ENHANCEMENT_MODEL;
+  }
+  if (process.env.RECORDINGS_LANGUAGE) {
+    config.language = process.env.RECORDINGS_LANGUAGE;
+  }
+  if (process.env.RECORDINGS_DB_PATH) {
+    config.db_path = process.env.RECORDINGS_DB_PATH;
+  }
+  if (process.env.RECORDINGS_AUDIO_DIR) {
+    config.audio_dir = process.env.RECORDINGS_AUDIO_DIR;
+  }
+  if (process.env.RECORDINGS_MAX_SECONDS) {
+    config.max_recording_seconds = parseInt(
+      process.env.RECORDINGS_MAX_SECONDS,
+      10
+    );
+  }
+
+  // 3. Load API key from ~/.secrets if not set
+  if (!config.openai_api_key) {
+    config.openai_api_key = loadSecretKey("OPENAI_API_KEY");
+  }
+  if (!config.enhancement_api_key) {
+    config.enhancement_api_key =
+      config.openai_api_key || loadSecretKey("OPENAI_API_KEY");
+  }
+
+  // 4. Set defaults for paths
+  if (!config.db_path) {
+    config.db_path = join(getDataDir(), "recordings.db");
+  }
+  if (!config.audio_dir) {
+    config.audio_dir = join(getDataDir(), "audio");
+  }
+
+  return config;
+}
+
+function findConfigFile(): string | null {
+  // Walk up from cwd looking for .recordings/config.json
+  let dir = process.cwd();
+  const root = "/";
+  while (dir !== root) {
+    const candidate = join(dir, ".recordings", "config.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function getDataDir(): string {
+  // Check for .recordings in cwd hierarchy
+  let dir = process.cwd();
+  const root = "/";
+  while (dir !== root) {
+    const candidate = join(dir, ".recordings");
+    if (existsSync(candidate)) return candidate;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fall back to ~/.recordings
+  return join(homedir(), ".recordings");
+}
+
+function loadSecretKey(keyName: string): string {
+  const secretsPath = join(homedir(), ".secrets");
+  if (!existsSync(secretsPath)) return "";
+
+  try {
+    const content = readFileSync(secretsPath, "utf-8");
+    const match = content.match(
+      new RegExp(`export\\s+${keyName}\\s*=\\s*"([^"]+)"`)
+    );
+    if (match) return match[1]!;
+
+    const match2 = content.match(
+      new RegExp(`export\\s+${keyName}\\s*=\\s*'([^']+)'`)
+    );
+    if (match2) return match2[1]!;
+
+    const match3 = content.match(new RegExp(`${keyName}\\s*=\\s*(.+)`));
+    if (match3) return match3[1]!.trim().replace(/^["']|["']$/g, "");
+  } catch {
+    // Ignore
+  }
+  return "";
+}
+
+export function ensureDataDir(config: RecordingsConfig): void {
+  const { mkdirSync } = require("fs") as typeof import("fs");
+  mkdirSync(config.audio_dir, { recursive: true });
+
+  // Ensure db directory exists
+  const dbDir = config.db_path.substring(
+    0,
+    config.db_path.lastIndexOf("/")
+  );
+  if (dbDir) mkdirSync(dbDir, { recursive: true });
+}

package/src/lib/enhancer.ts

@@ -0,0 +1,167 @@
+import OpenAI from "openai";
+import type {
+  RecordingsConfig,
+  EnhancementResult,
+} from "../types/index.js";
+import { EnhancementError } from "../types/index.js";
+
+let _enhancementClient: OpenAI | null = null;
+
+function getEnhancementClient(config: RecordingsConfig): OpenAI {
+  if (_enhancementClient) return _enhancementClient;
+  const key = config.enhancement_api_key || config.openai_api_key;
+  if (!key) {
+    throw new EnhancementError(
+      "API key not configured for enhancement. Set OPENAI_API_KEY or RECORDINGS_ENHANCEMENT_KEY"
+    );
+  }
+  _enhancementClient = new OpenAI({ apiKey: key });
+  return _enhancementClient;
+}
+
+export function resetEnhancementClient(): void {
+  _enhancementClient = null;
+}
+
+/**
+ * Detect if the transcribed text needs AI enhancement.
+ *
+ * Detection logic:
+ * 1. Explicit triggers: "say it better", "rewrite this", etc.
+ * 2. Instruction patterns: "write an email saying...", "give instructions to..."
+ * 3. Meta-commentary: text that talks ABOUT what to say rather than being the content itself
+ */
+export function needsEnhancement(
+  text: string,
+  config: RecordingsConfig
+): { needs: boolean; reason: string; instruction: string } {
+  const lower = text.toLowerCase().trim();
+
+  // Check explicit triggers from config
+  for (const trigger of config.enhance_triggers) {
+    if (lower.includes(trigger.toLowerCase())) {
+      return {
+        needs: true,
+        reason: `Explicit trigger: "${trigger}"`,
+        instruction: extractInstruction(text, trigger),
+      };
+    }
+  }
+
+  // Check instruction patterns
+  const instructionPatterns = [
+    /(?:write|draft|compose|create)\s+(?:an?\s+)?(?:email|message|response|reply|letter|note|text|slack|dm)/i,
+    /(?:give|provide|send)\s+(?:them|him|her|it|the\s+agent|the\s+team)\s+(?:full\s+)?instructions/i,
+    /(?:tell|ask)\s+(?:them|him|her|it|the\s+agent)\s+(?:to|that)/i,
+    /(?:make\s+it|make\s+this)\s+(?:sound|look|read)\s+(?:more\s+)?(?:professional|formal|casual|friendly|better)/i,
+    /(?:ok\s+so|okay\s+so|alright\s+so)\s+(?:say|write|tell|put)/i,
+    /(?:i\s+need|i\s+want)\s+(?:the\s+agent|it|them|you)\s+to\s+(?:build|create|implement|design|make)/i,
+  ];
+
+  for (const pattern of instructionPatterns) {
+    if (pattern.test(text)) {
+      return {
+        needs: true,
+        reason: `Instruction pattern detected`,
+        instruction: text,
+      };
+    }
+  }
+
+  return { needs: false, reason: "Direct dictation", instruction: text };
+}
+
+function extractInstruction(text: string, trigger: string): string {
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(trigger.toLowerCase());
+  if (idx === -1) return text;
+
+  // Take everything after the trigger as the instruction context
+  const after = text.substring(idx + trigger.length).trim();
+  const before = text.substring(0, idx).trim();
+
+  // If there's content before the trigger, that's likely the raw text to enhance
+  if (before.length > after.length && before.length > 10) {
+    return before;
+  }
+
+  // Otherwise the whole text is the instruction
+  return text;
+}
+
+export async function enhanceText(
+  rawText: string,
+  instruction: string,
+  config: RecordingsConfig
+): Promise<EnhancementResult> {
+  const client = getEnhancementClient(config);
+
+  try {
+    const response = await client.chat.completions.create({
+      model: config.enhancement_model,
+      messages: [
+        {
+          role: "system",
+          content: `You are a writing assistant. The user has dictated speech that needs to be transformed into polished output.
+
+Rules:
+- Output ONLY the enhanced/rewritten text — no explanations, no preamble
+- Preserve the user's intent and meaning
+- Fix grammar, structure, and clarity
+- If the user is giving instructions (e.g., "write an email saying..."), produce the actual output (the email), not a description of it
+- If the user says "say it better" or similar, rewrite their preceding text to be clearer and more professional
+- Match the appropriate tone (formal for business, casual for personal)`,
+        },
+        {
+          role: "user",
+          content: instruction,
+        },
+      ],
+      temperature: 0.3,
+      max_tokens: 4096,
+    });
+
+    const enhanced =
+      response.choices[0]?.message?.content?.trim() || rawText;
+
+    return {
+      original: rawText,
+      enhanced,
+      model: config.enhancement_model,
+      reasoning: null,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new EnhancementError(`Enhancement failed: ${msg}`);
+  }
+}
+
+/**
+ * Full pipeline: detect if enhancement is needed, enhance if so.
+ */
+export async function processText(
+  rawText: string,
+  config: RecordingsConfig
+): Promise<{
+  text: string;
+  mode: "raw" | "enhanced";
+  enhancement_model: string | null;
+}> {
+  if (!config.auto_enhance) {
+    return { text: rawText, mode: "raw", enhancement_model: null };
+  }
+
+  const detection = needsEnhancement(rawText, config);
+
+  if (!detection.needs) {
+    return { text: rawText, mode: "raw", enhancement_model: null };
+  }
+
+  const result = await enhanceText(rawText, detection.instruction, config);
+
+  return {
+    text: result.enhanced,
+    mode: "enhanced",
+    enhancement_model: result.model,
+  };
+}

package/src/lib/recorder.ts

@@ -0,0 +1,198 @@
+import { spawn, type ChildProcess } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
+import type { RecordingsConfig } from "../types/index.js";
+import { RecordingError } from "../types/index.js";
+
+let _recordProcess: ChildProcess | null = null;
+let _currentFile: string | null = null;
+
+/**
+ * Check if sox/rec is available for recording
+ */
+export async function checkRecordingDeps(): Promise<{
+  available: boolean;
+  tool: string;
+  message: string;
+}> {
+  // Check for sox
+  try {
+    const proc = Bun.spawn(["which", "sox"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return { available: true, tool: "sox", message: "sox is available" };
+    }
+  } catch {
+    // Not available
+  }
+
+  // Check for rec (part of sox)
+  try {
+    const proc = Bun.spawn(["which", "rec"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return { available: true, tool: "rec", message: "rec is available" };
+    }
+  } catch {
+    // Not available
+  }
+
+  // Check for ffmpeg
+  try {
+    const proc = Bun.spawn(["which", "ffmpeg"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return {
+        available: true,
+        tool: "ffmpeg",
+        message: "ffmpeg is available",
+      };
+    }
+  } catch {
+    // Not available
+  }
+
+  return {
+    available: false,
+    tool: "none",
+    message:
+      "No recording tool found. Install sox: brew install sox (macOS) or apt install sox (Linux)",
+  };
+}
+
+/**
+ * Start recording audio from microphone
+ */
+export function startRecording(config: RecordingsConfig): string {
+  if (_recordProcess) {
+    throw new RecordingError("Already recording. Stop the current recording first.");
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `recording-${timestamp}.${config.audio_format}`;
+  const filepath = join(config.audio_dir, filename);
+
+  // Build sox/rec command based on config
+  const args = buildRecordArgs(filepath, config);
+
+  _recordProcess = spawn(args[0]!, args.slice(1), {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  _currentFile = filepath;
+
+  _recordProcess.on("error", (err) => {
+    _recordProcess = null;
+    _currentFile = null;
+    throw new RecordingError(`Recording process error: ${err.message}`);
+  });
+
+  _recordProcess.on("exit", () => {
+    _recordProcess = null;
+  });
+
+  return filepath;
+}
+
+/**
+ * Stop the current recording
+ */
+export function stopRecording(): string | null {
+  if (!_recordProcess) {
+    return null;
+  }
+
+  const filepath = _currentFile;
+
+  // Send SIGINT to gracefully stop sox/rec
+  _recordProcess.kill("SIGINT");
+  _recordProcess = null;
+  _currentFile = null;
+
+  return filepath;
+}
+
+/**
+ * Check if currently recording
+ */
+export function isRecording(): boolean {
+  return _recordProcess !== null;
+}
+
+/**
+ * Get current recording file path
+ */
+export function getCurrentFile(): string | null {
+  return _currentFile;
+}
+
+function buildRecordArgs(filepath: string, config: RecordingsConfig): string[] {
+  const format = config.audio_format;
+  const rate = config.sample_rate;
+  const maxSeconds = config.max_recording_seconds;
+
+  // Use rec (sox) for recording — most reliable cross-platform
+  // rec outputs to file, auto-detects input device
+  return [
+    "rec",
+    "-r",
+    rate.toString(),
+    "-c",
+    "1", // mono
+    "-b",
+    "16", // 16-bit
+    filepath,
+    "trim",
+    "0",
+    maxSeconds.toString(),
+  ];
+}
+
+/**
+ * Record for a specific duration (non-interactive)
+ */
+export async function recordDuration(
+  seconds: number,
+  config: RecordingsConfig
+): Promise<string> {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `recording-${timestamp}.${config.audio_format}`;
+  const filepath = join(config.audio_dir, filename);
+
+  const args = [
+    "rec",
+    "-r",
+    config.sample_rate.toString(),
+    "-c",
+    "1",
+    "-b",
+    "16",
+    filepath,
+    "trim",
+    "0",
+    seconds.toString(),
+  ];
+
+  const proc = Bun.spawn(args, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0 && !existsSync(filepath)) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new RecordingError(`Recording failed (exit ${exitCode}): ${stderr}`);
+  }
+
+  return filepath;
+}

package/src/lib/transcriber.ts

@@ -0,0 +1,105 @@
+import OpenAI from "openai";
+import { createReadStream } from "fs";
+import type { RecordingsConfig, TranscriptionResult } from "../types/index.js";
+import { TranscriptionError } from "../types/index.js";
+
+let _client: OpenAI | null = null;
+
+function getClient(config: RecordingsConfig): OpenAI {
+  if (_client) return _client;
+  if (!config.openai_api_key) {
+    throw new TranscriptionError(
+      "OpenAI API key not configured. Set OPENAI_API_KEY env var or add to ~/.secrets"
+    );
+  }
+  _client = new OpenAI({ apiKey: config.openai_api_key });
+  return _client;
+}
+
+export function resetClient(): void {
+  _client = null;
+}
+
+export async function transcribeAudio(
+  audioPath: string,
+  config: RecordingsConfig
+): Promise<TranscriptionResult> {
+  const client = getClient(config);
+  const startTime = Date.now();
+
+  try {
+    const transcription = await client.audio.transcriptions.create({
+      file: createReadStream(audioPath),
+      model: config.transcription_model,
+      language: config.language || undefined,
+      response_format: "json",
+    });
+
+    const durationMs = Date.now() - startTime;
+
+    return {
+      text: transcription.text,
+      duration_ms: durationMs,
+      model: config.transcription_model,
+      language: (transcription as unknown as Record<string, unknown>).language as string | null,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new TranscriptionError(`Transcription failed: ${msg}`);
+  }
+}
+
+export async function transcribeBuffer(
+  buffer: Buffer,
+  filename: string,
+  config: RecordingsConfig
+): Promise<TranscriptionResult> {
+  const client = getClient(config);
+  const startTime = Date.now();
+
+  try {
+    const file = new File([new Uint8Array(buffer)], filename, {
+      type: getMimeType(filename),
+    });
+
+    const transcription = await client.audio.transcriptions.create({
+      file,
+      model: config.transcription_model,
+      language: config.language || undefined,
+      response_format: "json",
+    });
+
+    const durationMs = Date.now() - startTime;
+
+    return {
+      text: transcription.text,
+      duration_ms: durationMs,
+      model: config.transcription_model,
+      language: (transcription as unknown as Record<string, unknown>).language as string | null,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new TranscriptionError(`Transcription failed: ${msg}`);
+  }
+}
+
+function getMimeType(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "wav":
+      return "audio/wav";
+    case "mp3":
+      return "audio/mpeg";
+    case "m4a":
+      return "audio/mp4";
+    case "webm":
+      return "audio/webm";
+    case "mp4":
+      return "audio/mp4";
+    case "mpeg":
+    case "mpga":
+      return "audio/mpeg";
+    default:
+      return "audio/wav";
+  }
+}