# voice-keyboard

**Repository Path**: ArtfulCoder/voice-keyboard

## Basic Information

- **Project Name**: voice-keyboard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-14
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Voice Keyboard

A custom iOS keyboard that enables voice recording with AI-powered transcription using OpenAI's Whisper API and on-device WhisperKit.

## Features

- Voice-to-text transcription with a single tap
- **Dual transcription modes:**
  - Cloud-based via OpenAI Whisper API (highest accuracy)
  - On-device via WhisperKit (works offline)
  - Auto mode (cloud with local fallback)
- Multi-language support (13+ languages)
- Auto-punctuation and smart capitalization
- Voice commands ("new line", "period", etc.)
- Secure API key storage in Keychain
- Audio level visualization

## Requirements

- iOS 16.0+
- Xcode 15.0+
- [XcodeGen](https://github.com/yonaskolb/XcodeGen) (for project generation)
- Apple Developer account (for device testing)

## Setup

### 1. Generate Xcode Project

Install XcodeGen if you haven't:
```bash
brew install xcodegen
```

Generate the project:
```bash
cd voice-keyboard
xcodegen generate
```

### 2. Configure Signing

1. Open `VoiceKeyboard.xcodeproj` in Xcode
2. Select the project in the navigator
3. For both targets (VoiceKeyboard and VoiceKeyboardExtension):
   - Select your Team in Signing & Capabilities
   - Update the Bundle Identifier if needed (must be unique)
4. Ensure App Groups are configured with the same group ID

### 3. Configure App Groups (Important!)

Both the main app and keyboard extension must share the same App Group for settings and API key sharing:

1. In Xcode, select the VoiceKeyboard target
2. Go to Signing & Capabilities
3. Add "App Groups" capability if not present
4. Ensure `group.com.voicekeyboard.shared` is enabled
5. Repeat for VoiceKeyboardExtension target

### 4. Build and Run

1. Select an iOS device (keyboard extensions don't work in Simulator)
2. Build and run the VoiceKeyboard scheme
3. After installation, enable the keyboard:
   - Go to Settings > General > Keyboard > Keyboards
   - Tap "Add New Keyboard"
   - Select "Voice Keyboard"
   - Tap "Voice Keyboard" again and enable "Allow Full Access"

## Usage

### Main App

1. Open the Voice Keyboard app
2. Grant microphone permission when prompted
3. Configure your preferred settings:
   - **API Key**: Enter your OpenAI API key for cloud transcription
   - **Mode**: Choose between Cloud, Local, or Auto
   - **Language**: Select your preferred transcription language
   - **Local Model**: Choose model size (Tiny/Base/Small)

### Keyboard

1. Switch to Voice Keyboard in any text field
2. Tap the microphone button to start recording
3. Speak clearly
4. Tap again to stop and transcribe
5. Text is automatically inserted at the cursor

### Voice Commands

While recording, you can say:
- "new line" or "new paragraph" - Insert line breaks
- "period", "comma", "question mark" - Insert punctuation

## Architecture

```
VoiceKeyboard/
├── VoiceKeyboard/              # Main app
│   ├── VoiceKeyboardApp.swift  # App entry point
│   └── ContentView.swift       # Settings UI
├── VoiceKeyboardExtension/     # Keyboard extension
│   ├── KeyboardViewController.swift
│   └── KeyboardView.swift      # SwiftUI keyboard UI
└── Shared/                     # Shared code
    ├── AudioRecorder.swift     # Voice recording
    ├── TranscriptionService.swift
    ├── WhisperAPIService.swift # OpenAI API
    ├── WhisperLocalService.swift # WhisperKit
    └── SettingsManager.swift   # App Group settings
```

## API Key

To use cloud transcription:
1. Get an API key from [OpenAI Platform](https://platform.openai.com/api-keys)
2. Enter it in the main app settings
3. The key is stored securely in the iOS Keychain

## Privacy

- **Cloud mode**: Audio is sent to OpenAI's servers for transcription
- **Local mode**: All processing happens on-device, no data leaves your phone
- Microphone access is only used during active recording
- No audio is stored permanently

## Troubleshooting

### Keyboard not appearing
- Ensure the keyboard is enabled in Settings > General > Keyboard > Keyboards
- Enable "Allow Full Access" for network and microphone features

### Transcription not working
- Check microphone permission in main app
- For cloud mode: verify API key is set correctly
- For local mode: wait for model to download on first use

### "Full Access" required
The keyboard needs Full Access for:
- Network requests (cloud transcription)
- Microphone access
- Shared settings with main app

## License

MIT License