@hasna/recordings

Local AI-powered voice recording & transcription. Record audio, transcribe with OpenAI Whisper, polish transcripts, and search across everything.

Install

bun add -g @hasna/recordings

Or run directly:

bunx @hasna/recordings

Quick Start

1. Set your API key:

export OPENAI_API_KEY="sk-..."

2. Start the server:

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

# 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):

{
  "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 >= 1.3.9
• sox for audio recording (brew install sox)
• An OpenAI API key

Development

git clone https://github.com/hasna/recordings.git
cd recordings
bun install
bun run dev

License

Apache-2.0