voiceType2 0.4.1
Type with your voice using hotkey-activated speech recognition
Requires Python: >=3.11
Keywords: accessibility, speech-recognition, transcription, voice-typing

# voiceType - type with your voice

![voiceType Logo](voicetype/assets/imgs/yellow-splotch-logo.png)

[![Tests](https://github.com/Adam-D-Lewis/voicetype/actions/workflows/tests.yaml/badge.svg)](https://github.com/Adam-D-Lewis/voicetype/actions/workflows/tests.yaml)

## Features

- Press a hotkey (default: `Pause/Break` key) to start recording audio.
- Release the hotkey to stop recording.
- The recorded audio is transcribed to text (e.g., using OpenAI's Whisper model).
- The transcribed text is typed into the currently active application.

## Prerequisites

- Python 3.8+
- `pip` (Python package installer)
- For Linux installation: `systemd` (common in most modern Linux distributions).
- An OpenAI API Key (if using OpenAI for transcription).

## Installation

### Option 1: Install from PyPI

```bash
pip install voicetype2
```

### Option 2: Install from Source

1.  **Clone the repository (including submodules):**
    ```bash
    git clone --recurse-submodules https://github.com/Adam-D-Lewis/voicetype.git
    cd voicetype
    ```

    If you already cloned without `--recurse-submodules`, initialize the submodules:
    ```bash
    git submodule update --init --recursive
    ```

2.  **Set up a Python virtual environment (recommended):**
    ```bash
    python3 -m venv .venv
    source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
    ```

3.  **Install the package and its dependencies:**
    This project uses `pyproject.toml` with `setuptools`. Install the `voicetype` package and its dependencies using pip:
    ```bash
    pip install .
    ```
    This command reads `pyproject.toml`, installs all necessary dependencies, and makes the `voicetype` script available (callable as `python -m voicetype`).

4.  **Run the installation script (for Linux with systemd):**
    If you are on Linux and want to run VoiceType as a systemd user service (recommended for background operation and auto-start on login), use the CLI entrypoint installed with the package. Ensure you're in the environment where you installed dependencies.
    ```bash
    voicetype install
    ```
    During install you'll be prompted to choose a provider [litellm, local]. If you choose `litellm` you'll then be prompted for your `OPENAI_API_KEY`. Values are stored in `~/.config/voicetype/.env` with restricted permissions.

    The script will:
    - Create a systemd service file at `~/.config/systemd/user/voicetype.service`.
    - Store your OpenAI API key in `~/.config/voicetype/.env` (with restricted permissions).
    - Reload the systemd user daemon, enable the `voicetype.service` to start on login, and start it immediately.

    For other operating systems, or if you prefer not to use the systemd service on Linux, you can run the application directly after installation (see Usage).

## Configuration

VoiceType can be configured using a `settings.toml` file. The application looks for configuration files in the following locations (in priority order):

1. `./settings.toml` - Current directory
2. `~/.config/voicetype/settings.toml` - User config directory
3. `/etc/voicetype/settings.toml` - System-wide config

### Available Settings

VoiceType uses a pipeline-based configuration system. See [settings.example.toml](settings.example.toml) for a complete, documented example configuration including:

- Stage definitions (RecordAudio, Transcribe, CorrectTypos, TypeText, LLMAgent)
- Local and cloud transcription options with fallback support
- Pipeline configuration with hotkey bindings
- Telemetry and logging settings

**Note:** If you used `voicetype install` and configured litellm during installation, your API key is stored separately in `~/.config/voicetype/.env`.

## Monitoring Pipeline Performance with OpenTelemetry

VoiceType includes built-in OpenTelemetry instrumentation to track pipeline execution and stage performance. When enabled, traces are exported to a local file for offline analysis.

### Enabling Telemetry

Telemetry is disabled by default. To enable it, add to your `settings.toml`:

```toml
[telemetry]
enabled = true
```

### Trace File Location

Traces are automatically saved to:
- Linux: `~/.config/voicetype/traces.jsonl`
- macOS: `~/Library/Application Support/voicetype/traces.jsonl`
- Windows: `%APPDATA%/voicetype/traces.jsonl`

### What You Can See

Each pipeline execution creates a trace with:
- **Overall pipeline duration** - Total time from start to finish
- **Individual stage timings** - How long each stage (RecordAudio, Transcribe, etc.) took
- **Pipeline metadata** - Pipeline name, ID, stage count
- **Error tracking** - Any exceptions or failures with stack traces

### Example Trace

Each span is written as a JSON line:
```json
{
  "name": "pipeline.default",
  "context": {...},
  "start_time": 1234567890,
  "end_time": 1234567895,
  "attributes": {
    "pipeline.id": "abc-123",
    "pipeline.name": "default",
    "pipeline.duration_ms": 5200
  }
}
```

### Managing Trace Files

**Automatic rotation:**
Trace files are automatically rotated when they reach 10 MB. Rotated files are timestamped (e.g., `traces.20250117_143022.jsonl`) and kept indefinitely.

**View traces:**
```bash
# Pretty-print the current trace file
cat ~/.config/voicetype/traces.jsonl | jq

# View all trace files (including rotated)
cat ~/.config/voicetype/traces*.jsonl | jq

# Or just view in any text editor
cat ~/.config/voicetype/traces.jsonl
```

**Clear old traces:**
```bash
# Delete all trace files
rm ~/.config/voicetype/traces*.jsonl
```

**Analyze with grep:**
```bash
# Find slow stages in current file
grep "duration_ms" ~/.config/voicetype/traces.jsonl | grep -E "duration_ms\":[0-9]{4,}"

# Search across all trace files
grep "duration_ms" ~/.config/voicetype/traces*.jsonl | grep -E "duration_ms\":[0-9]{4,}"
```

### Configuration

**Custom trace file location:**
```toml
[telemetry]
enabled = true
trace_file = "~/my-custom-traces.jsonl"
```

**Adjust rotation size or disable rotation:**
```toml
[telemetry]
enabled = true
rotation_max_size_mb = 50  # Rotate at 50 MB instead of 10 MB

# Or disable rotation entirely
# rotation_enabled = false
```

**Export to OTLP endpoint only (disable file export):**
```toml
[telemetry]
enabled = true
export_to_file = false
otlp_endpoint = "http://localhost:4317"
```

## Usage

-   **If using the Linux systemd service:** The service will start automatically on login. VoiceType will be listening for the hotkey in the background.
-   **To run manually (e.g., for testing or on non-Linux systems):**
    Activate your virtual environment and run:
    ```bash
    python -m voicetype
    ```

**Using the Hotkey:**
1.  Press and hold the configured hotkey (default is `Pause/Break`).
2.  Speak clearly.
3.  Release the hotkey to stop recording.
4.  The transcribed text should then be typed into your currently active application.

## Managing the Service (Linux with systemd)

If you used `voicetype install`:

-   **Check service status:**
    ```bash
    voicetype status
    ```
    Alternatively:
    ```bash
    systemctl --user status voicetype.service
    ```

-   **View service logs:**
    ```bash
    journalctl --user -u voicetype.service -f
    ```

-   **Restart the service:**
    (e.g., after changing the `OPENAI_API_KEY` in `~/.config/voicetype/.env`)
    ```bash
    systemctl --user restart voicetype.service
    ```

-   **Stop the service:**
    ```bash
    systemctl --user stop voicetype.service
    ```

-   **Start the service manually (if not enabled to start on login):**
    ```bash
    systemctl --user start voicetype.service
    ```

-   **Disable auto-start on login:**
    ```bash
    systemctl --user disable voicetype.service
    ```

-   **Enable auto-start on login (if previously disabled):**
    ```bash
    systemctl --user enable voicetype.service
    ```

## Uninstallation (Linux with systemd)

To stop the service, disable auto-start, and remove the systemd service file and associated configuration:
```bash
voicetype uninstall
```
This will:
- Stop and disable the `voicetype.service`.
- Remove the service file (`~/.config/systemd/user/voicetype.service`).
- Remove the environment file (`~/.config/voicetype/.env` containing your API key).
- Attempt to remove the application configuration directory (`~/.config/voicetype`) if it's empty.

If you installed the package using `pip install .`, you can uninstall it from your Python environment with:
```bash
pip uninstall voicetype
```

## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

## Architecture

VoiceType uses a pipeline-based architecture with resource-based concurrency control. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for:
- Complete system architecture diagram (Mermaid UML)
- Component descriptions and responsibilities
- Execution flow and lifecycle
- Design principles and extension points

### Vendored Dependencies

VoiceType includes a vendored version of [pynput](https://github.com/moses-palmer/pynput) located in `voicetype/_vendor/pynput/`. This vendored version includes a not-yet-merged bug fix and allows for better control over keyboard/mouse input handling functionality across different platforms

## Development

Preferred workflow: Pixi

- Pixi is the preferred way to create and manage the development environment for this project. It ensures reproducible, cross-platform setups using the definitions in pyproject.toml.

Setup Pixi
- Install Pixi:
  - Linux/macOS (official installer):
    - curl -fsSL https://pixi.sh/install.sh | bash
  - macOS (Homebrew):
    - brew install prefix-dev/pixi/pixi
  - Verify:
    - pixi --version

Development Environments

Available Pixi environments:
- **local**: Standard development environment (default)
  - `pixi install -e local && pixi shell -e local`
- **dev**: Development with testing tools
  - `pixi install -e dev && pixi shell -e dev`
- **cpu**: CPU-only (no CUDA dependencies)
  - `pixi install -e cpu && pixi shell -e cpu`
- **windows-build**: Build Windows installers (PyInstaller + dependencies)
  - `pixi install -e windows-build && pixi shell -e windows-build`

Run the application
- pixi run voicetype
  - Equivalent to:
    - python -m voicetype

Run tests
- If a test task is defined:
  - pixi run test
- Otherwise (pytest directly):
  - pixi run python -m pytest

Lint and format
- If tasks are defined:
  - pixi run lint
  - pixi run fmt
- Or run tools directly:
  - pixi run ruff format
  - pixi run ruff check .

Pre-commit hooks (recommended)
- Install hooks:
  - pixi run pre-commit install
- Run on all files:
  - pixi run pre-commit run --all-files

Building Windows Installers (Windows only)

Using Pixi:
- Setup build environment:
  - `pixi install -e windows-build`
  - `pixi shell -e windows-build`
- Install NSIS (one-time):
  - Download from https://nsis.sourceforge.io/Download
  - Or via Chocolatey: `choco install nsis`
- Build installer:
  - `pixi run -e windows-build build-windows`
  - Output: `dist/VoiceType-Setup.exe`

Or build executable only (no installer):
- `pixi run -e windows-build build-exe`
- Output: `dist/voicetype/voicetype.exe`

Clean build artifacts:
- `pixi run -e windows-build clean-build`

See [docs/BUILDING.md](docs/BUILDING.md) for detailed build instructions.

Alternative: Python venv (fallback)
- Ensure Python 3.11+ is installed.
- Create and activate a venv:
  - python -m venv .venv
  - source .venv/bin/activate
- Editable install with dev dependencies:
  - pip install -U pip
  - pip install -e ".[dev]"
- Run the app:
  - python -m voicetype

Notes
- Dependency definitions live in pyproject.toml
- After changing dependencies, update pyproject.toml then run:
  - pixi install
## License
This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.