stt-transcription

What this skill does

# Speech-to-Text Transcription

Comprehensive speech-to-text capabilities using multiple STT engines. Record audio, transcribe files, real-time processing, speaker identification, and multi-language support.

## Quick Start

When asked to transcribe audio:

1. **Choose engine**: Whisper (local/free), Google, Azure, or AssemblyAI
2. **Record or load**: Capture audio or use existing file
3. **Transcribe**: Convert speech to text
4. **Format**: Output as plain text, SRT, VTT, or JSON
5. **Enhance**: Add timestamps, speaker labels, punctuation

## Prerequisites

### System Requirements
- Python 3.8+
- Microphone (for recording)
- Audio file support: WAV, MP3, M4A, FLAC, OGG

### Install Dependencies

**Core (required):**
```bash
pip install sounddevice soundfile numpy --break-system-packages
```

**Whisper (OpenAI - local, free):**
```bash
pip install openai-whisper --break-system-packages
# For faster processing with GPU:
pip install openai-whisper torch --break-system-packages
```

**Google Speech (requires API key):**
```bash
pip install google-cloud-speech --break-system-packages
```

**Azure Speech (requires API key):**
```bash
pip install azure-cognitiveservices-speech --break-system-packages
```

**AssemblyAI (requires API key):**
```bash
pip install assemblyai --break-system-packages
```

**Optional enhancements:**
```bash
pip install pydub webrtcvad --break-system-packages  # Audio processing
pip install pyaudio --break-system-packages  # Alternative audio backend
```

See [reference/setup-guide.md](reference/setup-guide.md) for detailed installation.

## STT Engine Comparison

| Engine | Cost | Speed | Quality | Features | Best For |
|--------|------|-------|---------|----------|----------|
| **Whisper** | Free | Medium | High | Multilingual, local | Privacy, offline, free |
| **Google** | Pay-per-use | Fast | High | Punctuation, diarization | Real-time, accuracy |
| **Azure** | Pay-per-use | Fast | High | Translation, custom | Enterprise integration |
| **AssemblyAI** | Pay-per-use | Medium | Very High | Diarization, sentiment | Analysis, insights |

### Whisper (Recommended for most users)
- ✅ **Free and local** - No API costs, runs offline
- ✅ **High quality** - State-of-the-art accuracy
- ✅ **Multilingual** - 99+ languages
- ⚠️ **Speed** - Slower than cloud services (depends on hardware)
- ⚠️ **Resources** - Needs decent CPU/GPU

### Google Cloud Speech
- ✅ **Fast** - Real-time capable
- ✅ **Accurate** - Excellent for English
- ✅ **Features** - Automatic punctuation, speaker diarization
- ⚠️ **Cost** - $0.006 per 15 seconds (~$1.44/hour)
- ⚠️ **Privacy** - Audio sent to Google

### Azure Speech
- ✅ **Enterprise** - Microsoft integration
- ✅ **Translation** - Real-time translation
- ✅ **Custom** - Train custom models
- ⚠️ **Cost** - $1 per audio hour
- ⚠️ **Setup** - More complex configuration

### AssemblyAI
- ✅ **Features** - Speaker diarization, sentiment analysis
- ✅ **Quality** - Very accurate
- ✅ **Developer-friendly** - Simple API
- ⚠️ **Cost** - $0.00025 per second (~$0.90/hour)

## Core Operations

### Record Audio

**Simple recording:**
```bash
# Record 30 seconds
python scripts/record_audio.py --duration 30 --output recording.wav

# Record until stopped (Ctrl+C)
python scripts/record_audio.py --output recording.wav

# Record with voice activity detection
python scripts/record_audio.py --vad --output recording.wav
```

**Advanced recording:**
```bash
# Choose microphone
python scripts/list_devices.py  # List available mics
python scripts/record_audio.py --device 1 --output recording.wav

# Specify quality
python scripts/record_audio.py \
  --sample-rate 48000 \
  --channels 2 \
  --output recording.wav
```

### Transcribe Files

**Using Whisper (local, free):**
```bash
# Basic transcription
python scripts/transcribe_whisper.py --file recording.wav

# Choose model size (tiny, base, small, medium, large)
python scripts/transcribe_whisper.py \
  --file recording.wav \
  --model medium

# With timestamps
python scripts/transcribe_whisper.py \
  --file recording.wav \
  --timestamps \
  --output transcript.json

# Multiple languages
python scripts/transcribe_whisper.py \
  --file recording.wav \
  --language es  # Spanish
```

**Using Google Cloud:**
```bash
# Export API key
export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials.json"

# Transcribe
python scripts/transcribe_google.py \
  --file recording.wav \
  --language en-US

# With speaker diarization
python scripts/transcribe_google.py \
  --file recording.wav \
  --diarization \
  --speakers 2
```

**Using Azure:**
```bash
# Set credentials
export AZURE_SPEECH_KEY="your-key"
export AZURE_SPEECH_REGION="westus"

# Transcribe
python scripts/transcribe_azure.py --file recording.wav

# Real-time
python scripts/transcribe_azure_realtime.py --microphone
```

**Using AssemblyAI:**
```bash
# Set API key
export ASSEMBLYAI_API_KEY="your-key"

# Transcribe with features
python scripts/transcribe_assemblyai.py \
  --file recording.wav \
  --diarization \
  --sentiment \
  --topics
```

### Real-Time Transcription

**Stream from microphone:**
```bash
# Whisper streaming (chunked)
python scripts/stream_whisper.py

# Google streaming
python scripts/stream_google.py

# Azure continuous recognition
python scripts/stream_azure.py
```

### Format Output

**Plain text:**
```bash
python scripts/transcribe_whisper.py --file audio.wav --output transcript.txt
```

**JSON with metadata:**
```bash
python scripts/transcribe_whisper.py \
  --file audio.wav \
  --format json \
  --output transcript.json

# Output includes:
# - Text segments
# - Timestamps
# - Confidence scores
# - Language detection
```

**SRT subtitles:**
```bash
python scripts/transcribe_whisper.py \
  --file video.mp4 \
  --format srt \
  --output subtitles.srt
```

**VTT subtitles:**
```bash
python scripts/transcribe_whisper.py \
  --file video.mp4 \
  --format vtt \
  --output subtitles.vtt
```

## Common Workflows

### Workflow 1: Meeting Transcription

**Scenario:** Record and transcribe meeting with speaker labels

```bash
# 1. Record meeting
python scripts/record_audio.py \
  --output meeting.wav \
  --vad  # Stop on silence

# 2. Transcribe with speaker diarization
python scripts/transcribe_google.py \
  --file meeting.wav \
  --diarization \
  --speakers 4 \
  --output meeting.json

# 3. Format for readability
python scripts/format_transcript.py \
  --input meeting.json \
  --format markdown \
  --output meeting.md

# Result: Formatted transcript with speaker labels and timestamps
```

### Workflow 2: Voice Notes to Markdown

**Scenario:** Quick voice note → markdown document

```bash
# Record voice note
python scripts/quick_note.py

# (Records audio, transcribes with Whisper, saves as markdown)
# Output: voice-note-2025-01-20-14-30.md
```

### Workflow 3: Batch Transcription

**Scenario:** Transcribe multiple audio files

```bash
# Batch process folder
python scripts/batch_transcribe.py \
  --input ./recordings/ \
  --output ./transcripts/ \
  --engine whisper \
  --model base

# Progress shown for each file
```

### Workflow 4: Video Subtitles

**Scenario:** Generate subtitles for video

```bash
# Extract audio from video
python scripts/extract_audio.py --video lecture.mp4 --output audio.wav

# Generate subtitles
python scripts/transcribe_whisper.py \
  --file audio.wav \
  --format srt \
  --output lecture.srt

# Embed in video (requires ffmpeg)
python scripts/embed_subtitles.py \
  --video lecture.mp4 \
  --subtitles lecture.srt \
  --output lecture-subbed.mp4
```

### Workflow 5: Multi-Language Support

**Scenario:** Transcribe and translate

```bash
# Transcribe Spanish audio
python scripts/transcribe_whisper.py \
  --file spanish-audio.wav \
  --language es \
  --output transcript-es.txt

# Translate to English
python scripts/transcribe_whisper.py \
  --file spanish-audio.wav \
  --task translate \
  --output transcript-en.txt
```

## Whisper Model Sizes

| Model | Parameters | Size | Speed | VRAM | Accuracy |
|-----