recmp3-cli 1.0.0

package/LICENSE-COMMERCIAL.md

@@ -0,0 +1,25 @@
+# Commercial License
+
+`recmp3-cli` is dual-licensed:
+
+1. **Open Source (AGPL-3.0)** — Free for personal use, open source projects, and non-commercial use. See [LICENSE](LICENSE).
+
+2. **Commercial License** — Required if you:
+   - Integrate `recmp3-cli` into a proprietary product or service without open-sourcing your modifications
+   - Distribute it as part of a closed-source product
+   - Use it in a commercial SaaS, enterprise product, or internal tooling at a for-profit entity without complying with AGPL-3.0
+
+## How to obtain a commercial license
+
+Email: **eduardoa.borjas@gmail.com**
+
+Include:
+- Company name and size
+- Intended use case
+- Expected volume (users / deployments)
+
+Response within 48 business hours.
+
+---
+
+The AGPL-3.0 license means: if you run a modified version of this software as a service (SaaS), you must release your modifications under the same license. If that model doesn't work for your organization, a commercial license removes this requirement.

package/README.md

@@ -0,0 +1,255 @@
+# recmp3-cli
+
+[![CI](https://github.com/aedneth/recmp3-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aedneth/recmp3-cli/actions/workflows/ci.yml)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/aedneth/recmp3-cli/releases)
+
+Record audio from any terminal, transcribe with Groq Whisper, get developer-ready output.
+A first-class tool for **both humans and terminal AI agents** — every interactive flow has a
+fully non-interactive, JSON-emitting equivalent, plus a built-in MCP server.
+
+```
+recmp3 record --name "my standup"
+recmp3 prompt standup.wav --template claude-code | pbcopy
+```
+
+## What it does
+
+- **Records** audio with pause/resume using an Ink TUI (runs in your current terminal — no popup windows)
+- **Transcribes** via Groq `whisper-large-v3-turbo` (or OpenAI Whisper)
+- **Formats** output with 7 developer templates: `claude-code`, `prd`, `bug`, `meeting-notes`, `todo`, `commit-message`, `raw`
+- **Cross-platform:** Linux (PulseAudio/PipeWire), macOS (AVFoundation), Windows (DirectShow)
+- **Agent-native:** global `--json` envelopes, `--yes`, deterministic exit codes, stdin/stdout piping, a discoverable `manifest`, and an MCP server — see [Agent & scripting use](#agent--scripting-use)
+- **Local option:** `--provider local-whisper` transcribes on-device via whisper.cpp (no upload)
+
+## Requirements
+
+- Node.js ≥ 20
+- ffmpeg ≥ 4.4 (`sudo apt install ffmpeg` / `brew install ffmpeg`)
+- A Groq API key (free tier works) — get one at console.groq.com
+
+## Installation
+
+```bash
+npm install -g recmp3-cli
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/aedneth/recmp3-cli
+cd recmp3-cli
+npm install && npm run build && npm link
+```
+
+Then set your API key:
+
+```bash
+echo 'export GROQ_API_KEY=gsk_...' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Verify the install:
+
+```bash
+recmp3 doctor
+```
+
+## Commands
+
+### `recmp3 record`
+
+```
+recmp3 record [options]
+
+Options:
+  -n, --name <name>        Output filename stem (e.g. "my-idea")
+  -o, --out <dir>          Output directory
+  -t, --transcribe         Transcribe immediately after recording
+  --mp3                    Save as MP3 instead of WAV
+  --provider <name>        Override provider (groq, openai, local-whisper)
+  --lang <code>            Force language code (e.g. es, en)
+  --source <id>            Audio source id, or "auto" for the best physical mic
+  --duration <seconds>     Headless: record N seconds then stop (no TUI)
+  --no-tui                 Force headless capture (record until Ctrl+C)
+  --no-copy / --no-print   Don't copy / don't print the transcript
+  -y, --yes                Skip upload consent prompt
+```
+
+> **Tip:** `recmp3 record --source auto` selects your real microphone automatically,
+> skipping the generic `default` device and system-audio `.monitor` sources.
+> Run `recmp3 sources` to see every device and which one is `(recommended)`.
+
+Controls while recording:
+- `p` or Space — pause / resume
+- `s` or Enter — save and finish
+- `c` or Escape — cancel (discard recording)
+- Ctrl+C — cancel
+
+### `recmp3 transcribe <file>`
+
+Transcribe an existing audio file. Outputs transcript text to stdout (pipeable).
+
+```bash
+recmp3 transcribe meeting.wav --template prd > meeting-prd.md
+```
+
+### `recmp3 prompt <file>`
+
+Apply a developer template to a transcript or text file. No network call — purely deterministic formatting.
+
+```bash
+recmp3 prompt transcript.txt --template claude-code
+recmp3 prompt transcript.txt --list-templates
+```
+
+**Available templates:** `raw`, `claude-code`, `prd`, `bug`, `meeting-notes`, `todo`, `commit-message`
+
+### `recmp3 sources`
+
+List available audio input devices for the current platform.
+
+```bash
+recmp3 sources
+recmp3 sources --json
+```
+
+### `recmp3 doctor`
+
+Run 8 system checks: Node version, platform support, ffmpeg version, audio backend, config file, API key, provider connectivity, and recordings directory.
+
+### `recmp3 config`
+
+```bash
+recmp3 config init          # Setup (interactive, or flag-driven: --provider/--lang/--outdir/--key)
+recmp3 config show          # Display current config (API key redacted)
+recmp3 config path          # Print config file path
+recmp3 config set <k> <v>   # Set a config key
+recmp3 config set-key groq --key gsk_...   # Store an API key in the OS keychain
+```
+
+## Agent & scripting use
+
+Every command is usable by AI agents (Claude Code, Codex, Gemini CLI, …) and shell scripts
+with no TTY and no prompts. See [`docs/AGENTS.md`](docs/AGENTS.md) for the full reference.
+
+```bash
+# Stable JSON envelope on stdout; chatter on stderr
+recmp3 transcribe meeting.wav --json --yes | jq -r .data.text
+
+# Compose via pipes: transcribe → template
+recmp3 transcribe meeting.wav --json --yes | jq -r .data.text | recmp3 prompt - --template prd
+
+# Headless recording (no Ink TUI)
+recmp3 record --duration 5 --json --yes
+
+# Discover the command/tool surface
+recmp3 manifest --json
+```
+
+**Exit codes:** `0` success · `1` unknown · `2` config · `3` audio/ffmpeg · `4` transcription ·
+`5` network · `6` local-whisper · `7` input · `130` user abort.
+
+### MCP server
+
+`recmp3` ships a Model Context Protocol server over stdio. Register it with any MCP client:
+
+```jsonc
+{ "mcpServers": { "recmp3": { "command": "recmp3", "args": ["mcp"] } } }
+```
+
+Tools: `recmp3_transcribe`, `recmp3_prompt`, `recmp3_sources`, `recmp3_doctor`,
+`recmp3_config_show`, `recmp3_record`, `recmp3_manifest`.
+
+### Local, no-upload transcription
+
+```bash
+export RECMP3_WHISPER_BIN=/usr/local/bin/whisper-cli   # whisper.cpp binary
+export RECMP3_WHISPER_MODEL=/models/ggml-base.en.bin
+recmp3 transcribe clip.wav --provider local-whisper --json
+```
+
+## Use Cases
+
+### Transcribe Instagram reels, TikToks, or any system audio (`recwatch`)
+
+Capture the audio your speakers are playing — useful for transcribing reels, TikToks, YouTube clips, podcasts, or any video in your browser without re-recording with the mic. Linux + PulseAudio/PipeWire only; the source name below is the monitor of your default output sink (find yours via `recmp3 sources` or `pactl list short sources`).
+
+```bash
+alias recwatch='RECMP3_SOURCE="alsa_output.platform-avs_hdaudio.0.stereo-fallback.monitor" recmp3 record --transcribe -y'
+```
+
+1. Add the alias above to `~/.bashrc` and `source ~/.bashrc`.
+2. Open the Instagram reel / TikTok / video in your browser.
+3. Run `recwatch` — it starts recording your system audio output.
+4. Watch the video; the audio plays through your speakers and is captured.
+5. Press `s` to stop → auto-transcribes via Groq Whisper → transcript prints to terminal and is copied to your clipboard.
+
+## Configuration
+
+Config file location:
+- Linux: `~/.config/recmp3/config.json`
+- macOS: `~/Library/Preferences/recmp3/config.json`
+- Windows: `%APPDATA%\recmp3\config.json`
+
+Environment variables override config file values:
+
+| Variable | Effect |
+|---|---|
+| `GROQ_API_KEY` | Groq API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `RECMP3_PROVIDER` | `groq` or `openai` |
+| `RECMP3_MODEL` | Override transcription model |
+| `RECMP3_SOURCE` | Default audio source |
+| `RECMP3_FFMPEG_PATH` | Path to ffmpeg binary |
+| `RECMP3_OUTDIR` | Default recordings output directory |
+| `RECMP3_LANG` | Default language hint (e.g. `es`, `en`) |
+| `RECMP3_WHISPER_BIN` | Path to a whisper.cpp binary (for `local-whisper`) |
+| `RECMP3_WHISPER_MODEL` | Path to a GGML model file (for `local-whisper`) |
+| `RECMP3_JSON` | `1` to always emit JSON envelopes |
+| `RECMP3_YES` | `1` to skip all prompts |
+| `RECMP3_QUIET` | `1` to suppress stderr chatter |
+| `RECMP3_SKIP_CONSENT` | `1` to skip upload consent prompt |
+
+## Providers
+
+| Provider | Default model | Max file size | Upload |
+|---|---|---|---|
+| Groq | `whisper-large-v3-turbo` | 25 MB | yes |
+| OpenAI | `whisper-1` | 25 MB | yes |
+| local-whisper | whisper.cpp GGML model | unlimited | **no (on-device)** |
+
+Audio is captured as WAV 16kHz mono (~1 MB/min), so the 25 MB limit covers ~25 minutes per recording. Longer recordings are chunked automatically.
+
+## Roadmap
+
+| Version | Theme | Status |
+|---|---|---|
+| v0.1.0 | Core TUI recorder + Groq/OpenAI transcription | ✅ shipped |
+| v0.2.0 | Agent-native: `--json`, MCP server, local Whisper, keychain | ✅ shipped |
+| v1.0.0 | Source auto-detection, graceful MCP shutdown, stable CLI + exit-code contract | ✅ shipped |
+| v1.1.0 | Streaming transcription, real-time waveform display | planned |
+| v1.2.0 | Multi-segment smart chunking, speaker diarization | planned |
+| v2.0.0 | Plugin SDK for custom providers and templates | planned |
+
+## Development
+
+```bash
+npm run dev           # Run with tsx (no build step)
+npm run build         # Build to dist/
+npm run typecheck     # TypeScript check
+npm run lint          # Biome lint
+npm test              # Run test suite (vitest)
+npm run test:watch    # Watch mode
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.
+
+## License
+
+`recmp3-cli` is dual-licensed:
+
+- **[AGPL-3.0](LICENSE)** — free for personal use and open source projects
+- **[Commercial license](LICENSE-COMMERCIAL.md)** — required for proprietary/commercial use
+
+Contact **eduardoa.borjas@gmail.com** to purchase a commercial license.

package/dist/chunk-7NR5CU7W.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+var execFileAsync = promisify(execFile);
+var _ffmpegPath = null;
+async function findFfmpeg() {
+  if (_ffmpegPath) return _ffmpegPath;
+  if (process.env.RECMP3_FFMPEG_PATH) {
+    _ffmpegPath = process.env.RECMP3_FFMPEG_PATH;
+    return _ffmpegPath;
+  }
+  try {
+    const which = process.platform === "win32" ? "where" : "which";
+    const { stdout } = await execFileAsync(which, ["ffmpeg"]);
+    _ffmpegPath = stdout.trim().split("\n")[0];
+    return _ffmpegPath;
+  } catch {
+    throw new Error("ffmpeg not found. Install with: sudo apt install ffmpeg");
+  }
+}
+async function checkFfmpegVersion() {
+  try {
+    const ffmpeg = await findFfmpeg();
+    const { stdout, stderr } = await execFileAsync(ffmpeg, ["-version"]);
+    const output = stdout + stderr;
+    const match = output.match(/ffmpeg version (\S+)/);
+    const version = match?.[1] ?? "unknown";
+    const [major, minor] = version.split(".").map(Number);
+    const meets = major > 4 || major === 4 && minor >= 4;
+    return { version, meets };
+  } catch {
+    return { version: "not found", meets: false };
+  }
+}
+async function supportsInputFormat(format) {
+  try {
+    const ffmpeg = await findFfmpeg();
+    const { stdout } = await execFileAsync(ffmpeg, ["-formats"]);
+    return stdout.includes(format);
+  } catch {
+    return false;
+  }
+}
+
+export { checkFfmpegVersion, findFfmpeg, supportsInputFormat };

package/dist/chunk-DDXRBIWU.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// src/log.ts
+var debugEnabled = false;
+var verboseEnabled = false;
+function initLogger(opts) {
+  debugEnabled = opts.debug ?? process.env.RECMP3_DEBUG === "1";
+  verboseEnabled = opts.verbose ?? debugEnabled;
+}
+var log = {
+  debug(msg, ...args) {
+    if (debugEnabled) {
+      process.stderr.write(
+        `[debug] ${msg} ${args.length ? JSON.stringify(args) : ""}
+`
+      );
+    }
+  },
+  info(msg, ...args) {
+    if (verboseEnabled) {
+      process.stderr.write(
+        `[info]  ${msg} ${args.length ? JSON.stringify(args) : ""}
+`
+      );
+    }
+  },
+  warn(msg) {
+    process.stderr.write(`[warn]  ${msg}
+`);
+  },
+  error(msg) {
+    process.stderr.write(`[error] ${msg}
+`);
+  }
+};
+function redactKey(key) {
+  if (!key || key.length < 8) return "***";
+  return `${key.slice(0, 3)}***${key.slice(-4)}`;
+}
+
+export { initLogger, log, redactKey };

package/dist/chunk-FNZ6ZCOK.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { log } from './chunk-DDXRBIWU.js';
+
+// src/secrets/keychain.ts
+var SERVICE = "recmp3";
+var _keytar;
+var _warned = false;
+async function getKeytar() {
+  if (_keytar !== void 0) return _keytar;
+  try {
+    const mod = await import('keytar');
+    _keytar = mod.default ?? mod;
+  } catch {
+    _keytar = null;
+    if (!_warned) {
+      _warned = true;
+      log.info(
+        "OS keychain (keytar) unavailable \u2014 falling back to environment variables."
+      );
+    }
+  }
+  return _keytar;
+}
+async function keychainAvailable() {
+  return await getKeytar() !== null;
+}
+async function getSecret(account) {
+  const kt = await getKeytar();
+  if (!kt) return void 0;
+  try {
+    return await kt.getPassword(SERVICE, account) ?? void 0;
+  } catch (err) {
+    log.info(
+      `keychain read failed for ${account}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return void 0;
+  }
+}
+async function setSecret(account, value) {
+  const kt = await getKeytar();
+  if (!kt) return false;
+  await kt.setPassword(SERVICE, account, value);
+  return true;
+}
+async function deleteSecret(account) {
+  const kt = await getKeytar();
+  if (!kt) return false;
+  return kt.deletePassword(SERVICE, account);
+}
+
+export { deleteSecret, getSecret, keychainAvailable, setSecret };

package/dist/chunk-NUWDWBJQ.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// src/errors.ts
+var ExitCode = {
+  SUCCESS: 0,
+  UNKNOWN: 1,
+  CONFIG: 2,
+  AUDIO: 3,
+  TRANSCRIPTION: 4,
+  NETWORK: 5,
+  LOCAL_WHISPER: 6,
+  INPUT: 7,
+  USER_ABORT: 130
+};
+var RecmpError = class extends Error {
+  constructor(code, message, exitCode = ExitCode.UNKNOWN) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.name = "RecmpError";
+  }
+  code;
+  exitCode;
+};
+var ConfigError = class extends RecmpError {
+  constructor(message) {
+    super("CONFIG_ERROR", message, 2);
+    this.name = "ConfigError";
+  }
+};
+var AudioCaptureError = class extends RecmpError {
+  constructor(message) {
+    super("AUDIO_CAPTURE_ERROR", message, 3);
+    this.name = "AudioCaptureError";
+  }
+};
+var TranscriptionError = class extends RecmpError {
+  constructor(message, statusCode) {
+    super("TRANSCRIPTION_ERROR", message, 4);
+    this.statusCode = statusCode;
+    this.name = "TranscriptionError";
+  }
+  statusCode;
+};
+var NetworkError = class extends RecmpError {
+  constructor(message) {
+    super("NETWORK_ERROR", message, 5);
+    this.name = "NetworkError";
+  }
+};
+var LocalWhisperError = class extends RecmpError {
+  constructor(message) {
+    super("LOCAL_WHISPER_ERROR", message, ExitCode.LOCAL_WHISPER);
+    this.name = "LocalWhisperError";
+  }
+};
+var InputError = class extends RecmpError {
+  constructor(message) {
+    super("INPUT_ERROR", message, ExitCode.INPUT);
+    this.name = "InputError";
+  }
+};
+
+export { AudioCaptureError, ConfigError, ExitCode, InputError, LocalWhisperError, NetworkError, RecmpError, TranscriptionError };

package/dist/chunk-NY5EJT5D.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { log } from './chunk-DDXRBIWU.js';
+import { LocalWhisperError } from './chunk-NUWDWBJQ.js';
+import { execFile } from 'child_process';
+import { existsSync } from 'fs';
+import { mkdtemp, rm, readFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { basename, join } from 'path';
+import { promisify } from 'util';
+
+var execFileAsync = promisify(execFile);
+var CANDIDATE_BINS = ["whisper-cli", "whisper", "main"];
+async function findWhisperBin(configPath) {
+  const explicit = configPath ?? process.env.RECMP3_WHISPER_BIN;
+  if (explicit) {
+    if (!existsSync(explicit)) {
+      throw new LocalWhisperError(`whisper binary not found at: ${explicit}`);
+    }
+    return explicit;
+  }
+  const which = process.platform === "win32" ? "where" : "which";
+  for (const name of CANDIDATE_BINS) {
+    try {
+      const { stdout } = await execFileAsync(which, [name]);
+      const found = stdout.trim().split("\n")[0];
+      if (found) return found;
+    } catch {
+    }
+  }
+  throw new LocalWhisperError(
+    'whisper.cpp binary not found. Install whisper.cpp and ensure "whisper-cli" is on PATH, or set RECMP3_WHISPER_BIN / config provider.local.binPath.'
+  );
+}
+function findWhisperModel(configPath) {
+  const model = configPath ?? process.env.RECMP3_WHISPER_MODEL;
+  if (!model) {
+    throw new LocalWhisperError(
+      "No whisper model configured. Set RECMP3_WHISPER_MODEL / config provider.local.modelPath to a .bin model file (e.g. ggml-base.en.bin)."
+    );
+  }
+  if (!existsSync(model)) {
+    throw new LocalWhisperError(`whisper model not found at: ${model}`);
+  }
+  return model;
+}
+
+// src/transcription/local-whisper.ts
+var execFileAsync2 = promisify(execFile);
+var LocalWhisperProvider = class {
+  constructor(config = {}) {
+    this.config = config;
+  }
+  config;
+  name = "local-whisper";
+  maxFileSizeBytes = Number.POSITIVE_INFINITY;
+  supportedFormats = ["wav", "mp3", "flac", "ogg"];
+  async transcribe(input) {
+    const { audioPath, language, signal } = input;
+    const t0 = Date.now();
+    const bin = await findWhisperBin(this.config.binPath);
+    const model = findWhisperModel(this.config.modelPath);
+    const lang = language ?? this.config.language;
+    log.info(`Transcribing locally with whisper.cpp: ${basename(audioPath)}`);
+    const workDir = await mkdtemp(join(tmpdir(), "recmp3-whisper-"));
+    const outPrefix = join(workDir, "out");
+    const args = ["-m", model, "-f", audioPath, "-oj", "-of", outPrefix];
+    if (lang) args.push("-l", lang);
+    try {
+      await execFileAsync2(bin, args, { signal, maxBuffer: 64 * 1024 * 1024 });
+    } catch (err) {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {
+      });
+      throw new LocalWhisperError(
+        `whisper.cpp failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    const jsonPath = `${outPrefix}.json`;
+    if (!existsSync(jsonPath)) {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {
+      });
+      throw new LocalWhisperError("whisper.cpp produced no JSON output.");
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile(jsonPath, "utf-8"));
+    } catch (err) {
+      throw new LocalWhisperError(
+        `Failed to parse whisper.cpp output: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
+    const segments = (parsed.transcription ?? []).map((s) => ({
+      startSec: (s.offsets?.from ?? 0) / 1e3,
+      endSec: (s.offsets?.to ?? 0) / 1e3,
+      text: (s.text ?? "").trim()
+    }));
+    const text = segments.map((s) => s.text).join(" ").replace(/\s+/g, " ").trim();
+    const latencyMs = Date.now() - t0;
+    return {
+      text,
+      language: parsed.result?.language ?? lang,
+      durationSec: segments.length ? segments[segments.length - 1].endSec : void 0,
+      segments,
+      raw: parsed,
+      provider: "local-whisper",
+      model: basename(model),
+      latencyMs
+    };
+  }
+  async ping() {
+    const t0 = Date.now();
+    try {
+      await findWhisperBin(this.config.binPath);
+      findWhisperModel(this.config.modelPath);
+      return { ok: true, latencyMs: Date.now() - t0 };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+};
+
+export { LocalWhisperProvider };