whspr 1.0.1 → 1.0.3

package/README.md

@@ -1,30 +1,35 @@
 # whspr
 
+[![npm version](https://img.shields.io/npm/v/whspr.svg)](https://www.npmjs.com/package/whspr)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+
 A CLI tool that records audio from your microphone, transcribes it using Groq's Whisper API, and post-processes the transcription with AI to fix errors and apply custom vocabulary.
 
-## Features
+<p align="center">
+  <img src="./demo.gif" alt="whspr demo" width="600">
+</p>
 
-- Live audio waveform visualization in the terminal
-- 15-minute max recording time
-- Transcription via Groq Whisper API
-- AI-powered post-processing to fix transcription errors
-- Custom vocabulary support via `WHSPR.md`
-- Automatic clipboard copy
+## Installation
 
-## Requirements
+```bash
+npm install -g whspr
+```
 
-- Node.js 18+
-- FFmpeg (`brew install ffmpeg` on macOS)
-- Groq API key
+### Optional: Alias as `whisper`
 
-## Installation
+If you'd like to use `whisper` instead of `whspr`, add this to your shell config (`~/.zshrc` or `~/.bashrc`):
 
 ```bash
-npm install
-npm run build
-npm link
+alias whisper="whspr"
 ```
 
+## Requirements
+
+- Node.js 18+
+- FFmpeg (`brew install ffmpeg` on macOS)
+- Groq API key
+
 ## Usage
 
 ```bash
@@ -40,9 +45,18 @@ whspr --verbose
 
 Press **Enter** to stop recording.
 
+## Features
+
+- Live audio waveform visualization in the terminal
+- 15-minute max recording time
+- Transcription via Groq Whisper API
+- AI-powered post-processing to fix transcription errors
+- Custom vocabulary support via `WHSPR.md`
+- Automatic clipboard copy
+
 ## Custom Vocabulary
 
-Create a `WHSPR.md` file in your current directory to provide custom vocabulary, names, or instructions for the AI post-processor:
+Create a `WHSPR.md` (or `WHISPER.md`) file in your current directory to provide custom vocabulary, names, or instructions for the AI post-processor:
 
 ```markdown
 # Custom Vocabulary

package/dist/index.d.ts

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-export {};
+export declare const DEFAULTS: {
+    transcriptionModel: "whisper-large-v3-turbo";
+    language: string;
+    systemPrompt: string;
+    customPromptPrefix: string;
+    transcriptionPrefix: string;
+};
+export interface WhsprSettings {
+    verbose?: boolean;
+    suffix?: string;
+    transcriptionModel?: "whisper-large-v3" | "whisper-large-v3-turbo";
+    language?: string;
+    systemPrompt?: string;
+    customPromptPrefix?: string;
+    transcriptionPrefix?: string;
+}

package/dist/index.js

@@ -7,7 +7,69 @@ import chalk from "chalk";
 import fs from "fs";
 import path from "path";
 import os from "os";
-const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+// Default prompts (can be overridden in settings.json)
+export const DEFAULTS = {
+    transcriptionModel: "whisper-large-v3-turbo",
+    language: "en",
+    systemPrompt: 'Your task is to clean up/fix transcribed text generated from mic input by the user according to the user\'s own prompt, this prompt may contain custom vocabulary, instructions, etc. Please return the user\'s transcription with the fixes made (e.g. the AI might hear "PostgreSQL" as "post crest QL" you need to use your own reasoning to fix these mistakes in the transcription)',
+    customPromptPrefix: "Here's my custom user prompt:",
+    transcriptionPrefix: "Here's my raw transcription output that I need you to edit:",
+};
+const WHSPR_DIR = path.join(os.homedir(), ".whspr");
+const SETTINGS_PATH = path.join(WHSPR_DIR, "settings.json");
+function loadSettings() {
+    try {
+        if (fs.existsSync(SETTINGS_PATH)) {
+            const content = fs.readFileSync(SETTINGS_PATH, "utf-8");
+            return JSON.parse(content);
+        }
+    }
+    catch (error) {
+        // Silently ignore invalid settings file
+    }
+    return {};
+}
+function loadCustomPrompt(verbose) {
+    const sources = [];
+    let globalPrompt = null;
+    let localPrompt = null;
+    // Check for global WHSPR.md or WHISPER.md in ~/.whspr/
+    const globalWhsprPath = path.join(WHSPR_DIR, "WHSPR.md");
+    const globalWhisperPath = path.join(WHSPR_DIR, "WHISPER.md");
+    if (fs.existsSync(globalWhsprPath)) {
+        globalPrompt = fs.readFileSync(globalWhsprPath, "utf-8");
+        sources.push("~/.whspr/WHSPR.md");
+    }
+    else if (fs.existsSync(globalWhisperPath)) {
+        globalPrompt = fs.readFileSync(globalWhisperPath, "utf-8");
+        sources.push("~/.whspr/WHISPER.md");
+    }
+    // Check for local WHSPR.md or WHISPER.md in current directory
+    const localWhsprPath = path.join(process.cwd(), "WHSPR.md");
+    const localWhisperPath = path.join(process.cwd(), "WHISPER.md");
+    if (fs.existsSync(localWhsprPath)) {
+        localPrompt = fs.readFileSync(localWhsprPath, "utf-8");
+        sources.push("./WHSPR.md");
+    }
+    else if (fs.existsSync(localWhisperPath)) {
+        localPrompt = fs.readFileSync(localWhisperPath, "utf-8");
+        sources.push("./WHISPER.md");
+    }
+    // Combine prompts: global first, then local
+    let combinedPrompt = null;
+    if (globalPrompt && localPrompt) {
+        combinedPrompt = globalPrompt + "\n\n" + localPrompt;
+    }
+    else if (globalPrompt) {
+        combinedPrompt = globalPrompt;
+    }
+    else if (localPrompt) {
+        combinedPrompt = localPrompt;
+    }
+    return { prompt: combinedPrompt, sources };
+}
+const settings = loadSettings();
+const verbose = settings.verbose || process.argv.includes("--verbose") || process.argv.includes("-v");
 function status(message) {
     process.stdout.write(`\x1b[2K\r${chalk.blue(message)}`);
 }
@@ -23,6 +85,13 @@ function formatDuration(seconds) {
     return `${secs}s`;
 }
 async function main() {
+    // Check for API key before recording
+    if (!process.env.GROQ_API_KEY) {
+        console.error(chalk.red("Error: GROQ_API_KEY environment variable is not set"));
+        console.log(chalk.gray("Get your API key at https://console.groq.com/keys"));
+        console.log(chalk.gray("Then run: export GROQ_API_KEY=\"your-api-key\""));
+        process.exit(1);
+    }
     try {
         // 1. Record audio
         const recording = await record(verbose);
@@ -33,31 +102,28 @@ async function main() {
         try {
             // 3. Transcribe with Whisper
             status("Transcribing...");
-            const rawText = await transcribe(mp3Path);
+            const rawText = await transcribe(mp3Path, settings.transcriptionModel ?? DEFAULTS.transcriptionModel, settings.language ?? DEFAULTS.language);
             if (verbose) {
                 clearStatus();
                 console.log(chalk.gray(`Raw: ${rawText}`));
             }
-            // 4. Read WHSPR.md or WHISPER.md if exists
-            const whsprMdPath = path.join(process.cwd(), "WHSPR.md");
-            const whisperMdPath = path.join(process.cwd(), "WHISPER.md");
-            let customPrompt = null;
-            let vocabFile = null;
-            if (fs.existsSync(whsprMdPath)) {
-                customPrompt = fs.readFileSync(whsprMdPath, "utf-8");
-                vocabFile = "WHSPR.md";
-            }
-            else if (fs.existsSync(whisperMdPath)) {
-                customPrompt = fs.readFileSync(whisperMdPath, "utf-8");
-                vocabFile = "WHISPER.md";
-            }
+            // 4. Read WHSPR.md or WHISPER.md (global from ~/.whspr/ and/or local)
+            const { prompt: customPrompt, sources: vocabSources } = loadCustomPrompt(verbose);
             if (customPrompt && verbose) {
-                console.log(chalk.gray(`Using custom vocabulary from ${vocabFile}`));
+                console.log(chalk.gray(`Using custom vocabulary from: ${vocabSources.join(" + ")}`));
             }
             // 5. Post-process
             status("Post-processing...");
-            const fixedText = await postprocess(rawText, customPrompt);
-            // 6. Output and copy
+            let fixedText = await postprocess(rawText, customPrompt, {
+                systemPrompt: settings.systemPrompt ?? DEFAULTS.systemPrompt,
+                customPromptPrefix: settings.customPromptPrefix ?? DEFAULTS.customPromptPrefix,
+                transcriptionPrefix: settings.transcriptionPrefix ?? DEFAULTS.transcriptionPrefix,
+            });
+            // 6. Apply suffix if configured
+            if (settings.suffix) {
+                fixedText = fixedText + settings.suffix;
+            }
+            // 7. Output and copy
             clearStatus();
             const processTime = ((Date.now() - processStart) / 1000).toFixed(1);
             const wordCount = fixedText.trim().split(/\s+/).filter(w => w.length > 0).length;
@@ -88,7 +154,7 @@ async function main() {
             console.log(chalk.dim("└" + bottomLine) + chalk.dim(stats) + chalk.dim("┘"));
             await copyToClipboard(fixedText);
             console.log(chalk.green("✓") + chalk.gray(" Copied to clipboard"));
-            // 7. Clean up
+            // 8. Clean up
             fs.unlinkSync(mp3Path);
         }
         catch (error) {

package/dist/postprocess.d.ts

@@ -1 +1,6 @@
-export declare function postprocess(rawTranscription: string, customPrompt: string | null): Promise<string>;
+export interface PostprocessOptions {
+    systemPrompt: string;
+    customPromptPrefix: string;
+    transcriptionPrefix: string;
+}
+export declare function postprocess(rawTranscription: string, customPrompt: string | null, options: PostprocessOptions): Promise<string>;

package/dist/postprocess.js

@@ -6,7 +6,8 @@ const MODEL = "openai/gpt-oss-120b";
 const outputSchema = z.object({
     fixed_transcription: z.string(),
 });
-export async function postprocess(rawTranscription, customPrompt) {
+export async function postprocess(rawTranscription, customPrompt, options) {
+    const { systemPrompt, customPromptPrefix, transcriptionPrefix } = options;
     const result = await withRetry(async () => {
         const response = await generateObject({
             model: groq(MODEL),
@@ -14,14 +15,20 @@ export async function postprocess(rawTranscription, customPrompt) {
             messages: [
                 {
                     role: "system",
-                    content: "Your task is to clean up/fix transcribed text generated from mic input by the user according to the user's own prompt, this prompt may contain custom vocabulary, instructions, etc. Please return the user's transcription with the fixes made (e.g. the AI might hear \"PostgreSQL\" as \"post crest QL\" you need to use your own reasoning to fix these mistakes in the transcription)"
+                    content: systemPrompt,
                 },
                 {
                     role: "user",
-                    content: customPrompt
-                        ? `Here's my custom user prompt:\n\`\`\`\n${customPrompt}\n\`\`\`\n\nHere's my raw transcription output that I need you to edit:\n\`\`\`\n${rawTranscription}\n\`\`\``
-                        : `Here's my raw transcription output that I need you to edit:\n\`\`\`\n${rawTranscription}\n\`\`\``
-                }
+                    content: [
+                        customPrompt
+                            ? `${customPromptPrefix}\n\`\`\`\n${customPrompt}\n\`\`\`\n\n`
+                            : null,
+                        `${transcriptionPrefix}\n\`\`\`\n${rawTranscription}\n\`\`\``,
+                    ]
+                        .filter(Boolean)
+                        .join("")
+                        .trim(),
+                },
             ],
         });
         return response.object;

package/dist/transcribe.d.ts

@@ -1 +1,2 @@
-export declare function transcribe(audioPath: string): Promise<string>;
+export type TranscriptionModel = "whisper-large-v3" | "whisper-large-v3-turbo";
+export declare function transcribe(audioPath: string, model?: TranscriptionModel, language?: string): Promise<string>;

package/dist/transcribe.js

@@ -1,12 +1,12 @@
 import Groq from "groq-sdk";
 import fs from "fs";
 const groq = new Groq(); // Uses GROQ_API_KEY env var
-export async function transcribe(audioPath) {
+export async function transcribe(audioPath, model = "whisper-large-v3-turbo", language = "en") {
     const transcription = await groq.audio.transcriptions.create({
         file: fs.createReadStream(audioPath),
-        model: "whisper-large-v3-turbo",
+        model,
         temperature: 0,
-        language: "en",
+        language,
     });
     return transcription.text;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whspr",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "CLI tool for audio transcription with Groq Whisper API",
   "type": "module",
   "bin": {