# Voice Skill - Echo, Voice of the Gods

Comprehensive speech-to-text and text-to-speech capabilities.
Works fully offline on Raspberry Pi.

## Features

### Speech-to-Text (Transcription)
- Whisper AI - State-of-the-art transcription (runs locally)
- Any audio format - wav, mp3, m4a, flac, ogg, webm, etc.
- 100+ languages with auto-detection
- Translation - Transcribe any language directly to English
- Timestamps - Word and segment-level timing
- Real-time - Live transcription from microphone

### Text-to-Speech
- Offline - pyttsx3 (works without internet)
- Online - Google TTS, Microsoft Edge TTS
- Save to file - Generate MP3 files

### Meeting Transcription
- Speaker diarization - Who said what
- Multi-speaker - Identify different voices
- Auto-save - JSON transcripts with metadata

## Usage Examples

```
"Transcribe this audio file"
"What did they say in this recording?"
"Start listening" / "Stop listening"
"Transcribe my meeting recording with speaker labels"
"Translate this Spanish audio to English"
"Say 'Hello world' out loud"
"Change transcription model to small"
```

## Whisper Models

Choose based on your hardware:

| Model | Disk | RAM | Best For |
|-------|------|-----|----------|
| tiny | 75MB | 1GB | Pi 4, real-time |
| base | 150MB | 1.5GB | Pi 4, general use |
| small | 500MB | 2GB | Desktop, good balance |
| medium | 1.5GB | 5GB | Desktop, high accuracy |
| large | 3GB | 10GB | GPU, best accuracy |

Recommendation: Start with tiny or base on Raspberry Pi.

## Installation

### Basic (Transcription)
```bash
# Standard Whisper
pip install openai-whisper

# OR faster-whisper (recommended, more efficient)
pip install faster-whisper

# FFmpeg for audio format conversion
sudo apt install ffmpeg
```

### For Microphone Input
```bash
pip install pyaudio
sudo apt install portaudio19-dev
```

### For Text-to-Speech
```bash
# Offline TTS
pip install pyttsx3
sudo apt install espeak

# OR online (better quality)
pip install gtts

# OR Microsoft Edge TTS (best quality, free)
pip install edge-tts
```

### For Speaker Diarization (Optional)
```bash
pip install pyannote.audio
# Requires HuggingFace token: export HF_TOKEN="hf_..."
```

## Raspberry Pi Optimization

For best performance on Pi 4:

1. Use tiny or base model - Larger models will be slow
2. Install faster-whisper - 4x more efficient than standard Whisper
3. Use int8 quantization - Automatic with faster-whisper on CPU

```bash
# Recommended Pi setup
pip install faster-whisper pyaudio pyttsx3
sudo apt install ffmpeg portaudio19-dev espeak
```

## Configuration

Settings stored in ~/.familiar/data/voice_config.json

Change via commands:
- "Set transcription model to base"
- "Change language to Spanish"

## File Locations

- Audio files: ~/.familiar/data/audio/
- Transcripts: ~/.familiar/data/transcripts/
- Config: ~/.familiar/data/voice_config.json

## Tools

| Tool | Description |
|------|-------------|
| transcribe | Transcribe audio file to text |
| transcribe_meeting | Transcribe with speaker identification |
| listen | Record from microphone and transcribe |
| start_live_transcription | Begin real-time transcription |
| stop_live_transcription | End real-time transcription |
| speak | Convert text to speech |
| voice_settings | View/change configuration |
| list_models | Show available Whisper models |
