shh

Voice transcription CLI using OpenAI Whisper.

---

Features

• Record from microphone (press Enter to stop)
• Format with AI (casual, business, neutral)
• Translate to any language
• Auto-copy to clipboard
• Async architecture
• Live progress display

Quick Start

# Install with pipx (recommended)
pipx install shh-cli

# Setup API key
shh setup

# Start recording (press Enter to stop)
shh

Installation

Using pipx (recommended)

pipx install shh-cli

Using pip

pip install shh-cli

Development Setup

git clone https://github.com/mariuspruvot/shh.git
cd shh
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Usage

Basic Recording

# Quick record - press Enter to stop
shh

# Minimal output (just result + "Done")
shh --quiet
shh -q

Formatting Styles

# Casual style (removes filler words, conversational)
shh --style casual

# Business style (professional, formal)
shh --style business

# Neutral style (no formatting, Whisper output as-is)
shh --style neutral

Translation

# Transcribe and translate to English
shh --translate English

# Combine formatting and translation
shh --style business --translate French

# Set default translation language
shh config set default_translation_language English

# Now recordings auto-translate without --translate flag
shh

Output Modes

# Rich UI (default) - colors, panels, live progress
shh

# Quiet mode - minimal output for scripting
shh --quiet

# Set quiet mode as default
shh config set quiet_mode true

# Override quiet mode with verbose flag
shh --verbose

# Combine with other options
shh --quiet --style casual --translate English

Configuration

# Show current configuration
shh config show

# Set default style
shh config set default_style casual

# Set default translation language
shh config set default_translation_language English

# Get specific setting
shh config get default_style

# Reset to defaults (preserves API key)
shh config reset

# Edit config file directly in $EDITOR
shh config edit

Configuration File

Configuration is stored in a platform-specific location:

• macOS: ~/Library/Application Support/shh/config.json
• Linux: ~/.config/shh/config.json
• Windows: %APPDATA%\shh\config.json

You can also use environment variables with the SHH_ prefix:

export SHH_OPENAI_API_KEY="sk-..."
export SHH_DEFAULT_STYLE="casual"
export SHH_DEFAULT_TRANSLATION_LANGUAGE="English"

Tech Stack

• Python 3.11+ (async/await)
• OpenAI Whisper (transcription)
• PydanticAI (formatting)
• Typer (CLI)
• Rich (terminal UI)
• sounddevice (audio recording)

Development

# Run tests
uv run poe test

# Type checking
uv run poe type

# Linting
uv run poe lint

# Formatting
uv run poe format

# All checks (type + lint + test)
uv run poe check

Architecture

Pragmatic layered architecture: CLI → Core → Adapters

CLI        → Commands, orchestration
Core       → Domain models (TranscriptionStyle)
Adapters   → APIs, audio, clipboard

See docs/architecture/overview.md for details.

License

MIT

Contributing

See CONTRIBUTING.md.