@hasna/recordings 0.1.0 → 0.1.2

package/src/native/RecordingsHelper.swift

@@ -0,0 +1,352 @@
+import Cocoa
+import Carbon
+
+// ── RecordingsHelper ────────────────────────────────────────────────────────
+// Lightweight menu bar app that toggles speech recording with a global hotkey.
+// Press the hotkey to start recording, press again to stop + transcribe + paste.
+// Works like Wispr Flow — no UI chrome, just a menu bar icon and a hotkey.
+
+class AppDelegate: NSObject, NSApplicationDelegate {
+    var statusItem: NSStatusItem!
+    var isRecording = false
+    var recordProcess: Process?
+    var currentAudioPath: String?
+    var hotkeyRef: EventHotKeyRef?
+    var spaceDownTime: Date?
+    var longPressTimer: Timer?
+    let longPressDuration: TimeInterval = 1.0  // Hold space for 1 second to activate
+
+    let recordingsDir: String = {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        return "\(home)/.recordings"
+    }()
+
+    let audioDir: String = {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        return "\(home)/.recordings/audio"
+    }()
+
+    let recordingsBin: String = {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        return "\(home)/.bun/bin/recordings"
+    }()
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        // Create audio dir
+        try? FileManager.default.createDirectory(atPath: audioDir, withIntermediateDirectories: true)
+
+        // Menu bar icon
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        updateIcon()
+
+        // Menu
+        let menu = NSMenu()
+        menu.addItem(NSMenuItem(title: "Hold Space (1s) to Record", action: #selector(toggleRecording), keyEquivalent: ""))
+        menu.addItem(NSMenuItem.separator())
+        menu.addItem(NSMenuItem(title: "Quit", action: #selector(quit), keyEquivalent: "q"))
+        statusItem.menu = menu
+
+        // Register global hotkey: F5
+        registerHotkey()
+
+        showNotification(title: "Recordings", body: "Ready — hold Space for 1s to record")
+    }
+
+    func updateIcon() {
+        if let button = statusItem.button {
+            button.title = isRecording ? "⏺" : "🎙"
+        }
+    }
+
+    // ── Global Hotkey ───────────────────────────────────────────────────────
+
+    func registerHotkey() {
+        // Hold Space for 1+ second to start recording, release to stop.
+        // Uses CGEventTap to monitor all keyboard events globally.
+        // Normal space presses (< 1 second) pass through untouched.
+
+        let eventMask: CGEventMask = (1 << CGEventType.keyDown.rawValue) | (1 << CGEventType.keyUp.rawValue) | (1 << CGEventType.flagsChanged.rawValue)
+
+        guard let tap = CGEvent.tapCreate(
+            tap: .cgSessionEventTap,
+            place: .headInsertEventTap,
+            options: .defaultTap,
+            eventsOfInterest: eventMask,
+            callback: { (proxy, type, event, refcon) -> Unmanaged<CGEvent>? in
+                let appDelegate = Unmanaged<AppDelegate>.fromOpaque(refcon!).takeUnretainedValue()
+                let keyCode = event.getIntegerValueField(.keyboardEventKeycode)
+
+                // Space bar = keycode 49
+                guard keyCode == 49 else {
+                    return Unmanaged.passRetained(event)
+                }
+
+                if type == .keyDown {
+                    // Ignore key repeat events (auto-repeat while held)
+                    let isRepeat = event.getIntegerValueField(.keyboardEventAutorepeat)
+                    if isRepeat != 0 {
+                        // Already tracking this press — suppress the repeat
+                        if appDelegate.spaceDownTime != nil {
+                            return nil  // Swallow repeat while we're tracking
+                        }
+                        return Unmanaged.passRetained(event)
+                    }
+
+                    if appDelegate.spaceDownTime == nil {
+                        appDelegate.spaceDownTime = Date()
+                        // Start a timer — if space is still held after 1s, begin recording
+                        DispatchQueue.main.async {
+                            appDelegate.longPressTimer?.invalidate()
+                            appDelegate.longPressTimer = Timer.scheduledTimer(withTimeInterval: appDelegate.longPressDuration, repeats: false) { _ in
+                                if appDelegate.spaceDownTime != nil && !appDelegate.isRecording {
+                                    appDelegate.startRecording()
+                                }
+                            }
+                        }
+                    }
+                    // Let the keyDown through for now (normal typing)
+                    return Unmanaged.passRetained(event)
+
+                } else if type == .keyUp {
+                    let wasLongPress = appDelegate.isRecording
+
+                    if appDelegate.isRecording {
+                        // Space released after recording — stop and transcribe
+                        DispatchQueue.main.async {
+                            appDelegate.stopAndTranscribe()
+                        }
+                    }
+
+                    // Cancel timer
+                    DispatchQueue.main.async {
+                        appDelegate.longPressTimer?.invalidate()
+                        appDelegate.longPressTimer = nil
+                    }
+                    appDelegate.spaceDownTime = nil
+
+                    if wasLongPress {
+                        // Swallow the keyUp so it doesn't type a space
+                        return nil
+                    }
+                    return Unmanaged.passRetained(event)
+                }
+
+                return Unmanaged.passRetained(event)
+            },
+            userInfo: Unmanaged.passUnretained(self).toOpaque()
+        ) else {
+            showNotification(title: "Error", body: "Could not create event tap. Grant Accessibility permission in System Settings > Privacy > Accessibility")
+            return
+        }
+
+        let runLoopSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0)
+        CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, .commonModes)
+        CGEvent.tapEnable(tap: tap, enable: true)
+    }
+
+    // ── Recording ────────────────────────────────────────────────────────────
+
+    @objc func toggleRecording() {
+        if isRecording { stopAndTranscribe() } else { startRecording() }
+    }
+
+    func startRecording() {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyyMMdd'T'HHmmss"
+        let filename = "recording-\(formatter.string(from: Date())).wav"
+        let filepath = "\(audioDir)/\(filename)"
+        currentAudioPath = filepath
+
+        // Run ffmpeg via bash — pipe stdin so we can send 'q' to stop gracefully
+        let process = Process()
+        let stdinPipe = Pipe()
+        process.executableURL = URL(fileURLWithPath: "/bin/bash")
+        process.arguments = ["-c", """
+            export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+            if command -v ffmpeg &>/dev/null; then
+                ffmpeg -f avfoundation -i ":0" -ar 16000 -ac 1 -t 300 "\(filepath)" -y 2>/dev/null
+            elif command -v rec &>/dev/null; then
+                rec -r 16000 -c 1 -b 16 "\(filepath)" trim 0 300
+            else
+                exit 1
+            fi
+        """]
+        process.standardInput = stdinPipe
+        process.standardOutput = FileHandle.nullDevice
+        process.standardError = FileHandle.nullDevice
+
+        do {
+            try process.run()
+            recordProcess = process
+            stdinPipeRef = stdinPipe
+            isRecording = true
+            updateIcon()
+            showNotification(title: "Recording...", body: "Press F5 to stop")
+        } catch {
+            showNotification(title: "Error", body: "Could not start recording: \(error.localizedDescription)")
+        }
+    }
+
+    var stdinPipeRef: Pipe?
+
+    func stopAndTranscribe() {
+        guard let process = recordProcess else { return }
+
+        // Send 'q' to ffmpeg stdin for graceful stop (flushes WAV header)
+        if let pipe = stdinPipeRef {
+            pipe.fileHandleForWriting.write("q".data(using: .utf8)!)
+            try? pipe.fileHandleForWriting.close()
+        }
+        // Wait for graceful exit, then force if needed
+        Thread.sleep(forTimeInterval: 1.0)
+        if process.isRunning {
+            process.terminate()
+            Thread.sleep(forTimeInterval: 0.3)
+        }
+        if process.isRunning {
+            process.interrupt()
+        }
+        recordProcess = nil
+        stdinPipeRef = nil
+        isRecording = false
+        updateIcon()
+
+        guard let audioPath = currentAudioPath else { return }
+        currentAudioPath = nil
+
+        // Check if audio file exists and has content
+        let fileManager = FileManager.default
+        guard fileManager.fileExists(atPath: audioPath) else {
+            showNotification(title: "Error", body: "Audio file not created — check mic permissions")
+            return
+        }
+
+        let attrs = try? fileManager.attributesOfItem(atPath: audioPath)
+        let size = attrs?[.size] as? Int ?? 0
+        if size < 1000 {
+            showNotification(title: "Error", body: "Audio too short (\(size) bytes) — try speaking longer")
+            return
+        }
+
+        showNotification(title: "Transcribing...", body: "Processing your recording")
+
+        // Transcribe in background
+        DispatchQueue.global(qos: .userInitiated).async { [self] in
+            let output = self.runCommand(self.recordingsBin, arguments: ["transcribe", audioPath, "--json"])
+
+            // The CLI outputs "Transcribing...\n" then the text, then JSON on --json
+            // Find the JSON object in the output
+            var text = ""
+
+            // Try to find JSON in the output
+            if let jsonStart = output.range(of: "{"),
+               let jsonEnd = output.range(of: "}", options: .backwards) {
+                let jsonStr = String(output[jsonStart.lowerBound...jsonEnd.upperBound])
+                if let data = jsonStr.data(using: .utf8),
+                   let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+                    if let pt = json["processed_text"] as? String, !pt.isEmpty {
+                        text = pt
+                    } else if let rt = json["raw_text"] as? String, !rt.isEmpty {
+                        text = rt
+                    }
+                }
+            }
+
+            // Fallback: grab everything after the last newline before JSON
+            if text.isEmpty {
+                let lines = output.components(separatedBy: "\n").filter { !$0.isEmpty && !$0.contains("Transcribing") && !$0.contains("{") }
+                for line in lines {
+                    let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if !trimmed.isEmpty && !trimmed.hasPrefix("Saved") {
+                        text = trimmed
+                        break
+                    }
+                }
+            }
+
+            guard !text.isEmpty else {
+                DispatchQueue.main.async {
+                    let dbg = output.prefix(200)
+                    self.showNotification(title: "Error", body: "Empty transcription. Output: \(dbg)")
+                }
+                return
+            }
+
+            DispatchQueue.main.async {
+                // Copy to clipboard
+                let pasteboard = NSPasteboard.general
+                pasteboard.clearContents()
+                pasteboard.setString(text, forType: .string)
+
+                // Auto-paste into the frontmost app (like Wispr Flow)
+                self.simulatePaste()
+
+                self.showNotification(title: "Done", body: String(text.prefix(80)))
+            }
+        }
+    }
+
+    // ── Helpers ─────────────────────────────────────────────────────────────
+
+    func simulatePaste() {
+        // Simulate Cmd+V
+        let source = CGEventSource(stateID: .hidSystemState)
+
+        let keyDown = CGEvent(keyboardEventSource: source, virtualKey: 0x09, keyDown: true) // V key
+        keyDown?.flags = .maskCommand
+        keyDown?.post(tap: .cghidEventTap)
+
+        let keyUp = CGEvent(keyboardEventSource: source, virtualKey: 0x09, keyDown: false)
+        keyUp?.flags = .maskCommand
+        keyUp?.post(tap: .cghidEventTap)
+    }
+
+    func runCommand(_ command: String, arguments: [String]) -> String {
+        let process = Process()
+        let pipe = Pipe()
+        let errPipe = Pipe()
+        process.executableURL = URL(fileURLWithPath: "/bin/bash")
+
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        let args = arguments.map { "\"\($0)\"" }.joined(separator: " ")
+        process.arguments = ["-c", """
+            export PATH="\(home)/.bun/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+            "\(command)" \(args)
+        """]
+        process.standardOutput = pipe
+        process.standardError = errPipe
+
+        do {
+            try process.run()
+            process.waitUntilExit()
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            return String(data: data, encoding: .utf8) ?? ""
+        } catch {
+            return "ERROR: \(error.localizedDescription)"
+        }
+    }
+
+    func showNotification(title: String, body: String) {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
+        process.arguments = ["-e", "display notification \"\(body)\" with title \"\(title)\""]
+        process.standardOutput = FileHandle.nullDevice
+        process.standardError = FileHandle.nullDevice
+        try? process.run()
+    }
+
+    @objc func quit() {
+        if let process = recordProcess {
+            process.interrupt()
+        }
+        NSApplication.shared.terminate(nil)
+    }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory) // Menu bar only, no dock icon
+let delegate = AppDelegate()
+app.delegate = delegate
+app.run()

package/src/types/index.ts

@@ -0,0 +1,138 @@
+// ── Recording Types ──────────────────────────────────────────────────────────
+
+export interface Recording {
+  id: string;
+  audio_path: string | null;
+  raw_text: string;
+  processed_text: string | null;
+  processing_mode: ProcessingMode;
+  model_used: string;
+  enhancement_model: string | null;
+  duration_ms: number;
+  language: string | null;
+  tags: string[];
+  agent_id: string | null;
+  project_id: string | null;
+  session_id: string | null;
+  metadata: Record<string, unknown>;
+  created_at: string;
+}
+
+export type ProcessingMode = "raw" | "enhanced";
+
+export interface CreateRecordingInput {
+  audio_path?: string;
+  raw_text: string;
+  processed_text?: string;
+  processing_mode?: ProcessingMode;
+  model_used?: string;
+  enhancement_model?: string;
+  duration_ms?: number;
+  language?: string;
+  tags?: string[];
+  agent_id?: string;
+  project_id?: string;
+  session_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RecordingFilter {
+  agent_id?: string;
+  project_id?: string;
+  session_id?: string;
+  processing_mode?: ProcessingMode;
+  tags?: string[];
+  search?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  offset?: number;
+}
+
+// ── Agent Types ─────────────────────────────────────────────────────────────
+
+export interface Agent {
+  id: string;
+  name: string;
+  description: string | null;
+  role: string;
+  metadata: Record<string, unknown>;
+  created_at: string;
+  last_seen_at: string;
+}
+
+// ── Project Types ───────────────────────────────────────────────────────────
+
+export interface Project {
+  id: string;
+  name: string;
+  path: string;
+  description: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+// ── Config Types ────────────────────────────────────────────────────────────
+
+export interface RecordingsConfig {
+  openai_api_key: string;
+  enhancement_api_key: string;
+  transcription_model: string;
+  enhancement_model: string;
+  language: string;
+  audio_format: "wav" | "mp3" | "m4a" | "webm";
+  sample_rate: number;
+  record_command: string;
+  hotkey: string;
+  auto_enhance: boolean;
+  enhance_triggers: string[];
+  db_path: string;
+  audio_dir: string;
+  max_recording_seconds: number;
+}
+
+// ── Transcription Types ─────────────────────────────────────────────────────
+
+export interface TranscriptionResult {
+  text: string;
+  duration_ms: number;
+  model: string;
+  language: string | null;
+}
+
+export interface EnhancementResult {
+  original: string;
+  enhanced: string;
+  model: string;
+  reasoning: string | null;
+}
+
+// ── Errors ──────────────────────────────────────────────────────────────────
+
+export class RecordingNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Recording not found: ${id}`);
+    this.name = "RecordingNotFoundError";
+  }
+}
+
+export class RecordingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RecordingError";
+  }
+}
+
+export class TranscriptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TranscriptionError";
+  }
+}
+
+export class EnhancementError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EnhancementError";
+  }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/README.md

@@ -1,145 +0,0 @@
-# @hasna/recordings
-
-Local AI-powered voice recording & transcription. Record audio, transcribe with OpenAI Whisper, polish transcripts, and search across everything.
-
-## Install
-
-```bash
-bun add -g @hasna/recordings
-```
-
-Or run directly:
-
-```bash
-bunx @hasna/recordings
-```
-
-## Quick Start
-
-1. Set your API key:
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
-
-2. Start the server:
-
-```bash
-recordings serve
-```
-
-3. Open the web UI at `http://localhost:3456` or use the API directly.
-
-## Features
-
-- Record audio from your microphone (via sox)
-- Transcribe recordings with OpenAI Whisper
-- AI-polish transcripts (remove filler words, fix grammar)
-- Full-text search across all transcriptions
-- Web UI for managing recordings
-- MCP server for Claude Desktop integration
-- REST API for programmatic access
-- SQLite-backed metadata storage
-
-## CLI
-
-```bash
-# Start the API server
-recordings serve
-
-# Start MCP server (stdio transport)
-recordings mcp
-
-# Print version
-recordings --version
-
-# Print help
-recordings --help
-```
-
-## MCP Server
-
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "recordings": {
-      "command": "bunx",
-      "args": ["@hasna/recordings", "mcp"]
-    }
-  }
-}
-```
-
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `start_recording` | Start microphone recording |
-| `stop_recording` | Stop the current recording |
-| `list_recordings` | List all recordings |
-| `get_recording` | Get recording details |
-| `delete_recording` | Delete a recording |
-| `transcribe_recording` | Transcribe a recording |
-| `transcribe_audio` | Transcribe an audio file by path |
-| `polish_text` | AI-polish raw text |
-| `search_transcriptions` | Search across transcriptions |
-| `get_config` | Get configuration |
-| `update_config` | Update configuration |
-| `get_status` | Get server status |
-
-## API Endpoints
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/status` | Server status |
-| GET | `/api/recordings` | List recordings |
-| GET | `/api/recordings/:id` | Get recording |
-| DELETE | `/api/recordings/:id` | Delete recording |
-| POST | `/api/recordings/start` | Start recording |
-| POST | `/api/recordings/stop` | Stop recording |
-| POST | `/api/recordings/:id/transcribe` | Transcribe recording |
-| POST | `/api/recordings/:id/polish` | Polish transcript |
-| POST | `/api/transcribe` | Upload & transcribe audio file |
-| GET | `/api/search?q=query` | Search transcriptions |
-| GET | `/api/config` | Get config |
-| PUT | `/api/config` | Update config |
-
-## Data Storage
-
-All data is stored in `~/.recordings/`:
-
-```
-~/.recordings/
-├── config.json          # User configuration
-├── recordings.db        # SQLite database (metadata + transcripts)
-├── audio/               # Recorded audio files (.wav)
-├── uploads/             # Uploaded audio files
-└── exports/             # Exported transcripts
-```
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPENAI_API_KEY` | Yes | OpenAI API key for Whisper transcription |
-
-## Prerequisites
-
-- [Bun](https://bun.sh) >= 1.3.9
-- [sox](https://sox.sourceforge.net/) for audio recording (`brew install sox`)
-- An [OpenAI API key](https://platform.openai.com/api-keys)
-
-## Development
-
-```bash
-git clone https://github.com/hasna/recordings.git
-cd recordings
-bun install
-bun run dev
-```
-
-## License
-
-Apache-2.0