Feedback: guides-dg_to_aai_streaming

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/guides/dg_to_aai_streaming
Category: guides
Generated: 05/08/2025, 4:42:01 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:42:00 pm

Technical Documentation Analysis & Feedback

Overall Assessment

This migration guide provides a solid foundation but suffers from several clarity, completeness, and usability issues that could frustrate users attempting to migrate from Deepgram to AssemblyAI.

---

🚨 Critical Issues

1. Incomplete Prerequisites

Problem: Missing essential setup information Impact: Users will encounter immediate blockers

Missing Information:

• Python version requirements
• Required package versions and installation commands
• System dependencies (microphone permissions, audio drivers)
• Supported operating systems

Fix:

## Prerequisites

Before starting this migration, ensure you have:

### System Requirements
- Python 3.7 or higher
- A working microphone with system permissions
- Audio drivers properly installed

### Required Python Packages
```bash
pip install websocket-client pyaudio

Additional Setup

• macOS: May require brew install portaudio
• Linux: May require sudo apt-get install python3-pyaudio
• Windows: Ensure microphone permissions are enabled

### 2. **Code Structure Problems**
**Problem**: The side-by-side comparison is overwhelming and hard to follow
**Impact**: Users get lost in implementation details before understanding concepts

**Solution**: Restructure with progressive disclosure:

```markdown
## Migration Overview

### Key Differences at a Glance
| Aspect | Deepgram | AssemblyAI |
|--------|----------|------------|
| Endpoint | `wss://api.deepgram.com/v1/listen` | `wss://streaming.assemblyai.com/v3/ws` |
| Auth Format | `Token {API_KEY}` | Just `{API_KEY}` |
| Model Selection | Required (`nova-3`) | Automatic (latest model) |
| Message Types | `Results` + `is_final` | `Begin`, `Turn`, `Termination` |
| Termination | `CloseStream` | `Terminate` |

### Step-by-Step Migration Process
1. [Update Authentication](#authentication)
2. [Modify Connection Parameters](#connection-parameters)
3. [Update Message Handling](#message-handling)
4. [Adjust Shutdown Logic](#shutdown-logic)

---

📋 Missing Information

1. Error Handling & Troubleshooting

Add comprehensive error scenarios:

## Common Migration Issues

### Authentication Errors
- **Error**: `401 Unauthorized`
- **Cause**: Invalid API key format
- **Fix**: Remove "Token" prefix from authorization header

### Connection Issues
- **Error**: `Connection refused`
- **Cause**: Network restrictions or invalid endpoint
- **Fix**: Check firewall settings and endpoint URL

### Audio Stream Errors
- **Error**: `Error opening microphone stream`
- **Cause**: Missing permissions or audio drivers
- **Fix**: Grant microphone permissions and install required audio libraries

2. Configuration Options

Document available parameters:

## Advanced Configuration

### Available Connection Parameters
```python
CONNECTION_PARAMS = {
    "sample_rate": 16000,        # 8000, 16000, 22050, 44100
    "format_turns": True,        # Enable/disable punctuation
    "word_boost": ["custom"],    # Boost specific words
    "disable_partial_transcripts": False  # Turn off interim results
}

Supported Audio Formats

• Sample rates: 8kHz, 16kHz, 22.05kHz, 44.1kHz
• Encoding: PCM 16-bit
• Channels: Mono (1 channel recommended)

### 3. **Performance & Limits**
Critical missing information:

```markdown
## Service Limits & Performance

### Rate Limits
- **Deepgram**: [Current limits]
- **AssemblyAI**: 5 concurrent connections per API key

### Session Limits
- Maximum session duration: 8 hours
- Automatic timeout: 60 seconds of silence
- Maximum audio buffer: 10MB

### Performance Tips
- Use 16kHz sample rate for optimal accuracy
- Send audio in 50ms chunks (800 frames)
- Implement exponential backoff for reconnections

---

🔧 Improved Examples

1. Minimal Working Example

Start with a basic example:

"""
Minimal AssemblyAI Streaming Example
Run this first to verify your setup works
"""
import websocket
import json
import pyaudio
import threading

API_KEY = "your-api-key-here"
ENDPOINT = "wss://streaming.assemblyai.com/v3/ws?sample_rate=16000"

def on_message(ws, message):
    data = json.loads(message)
    if data.get('type') == 'Turn':
        print(data.get('transcript', ''))

def stream_audio():
    audio = pyaudio.PyAudio()
    stream = audio.open(format=pyaudio.paInt16, channels=1,
                       rate=16000, input=True, frames_per_buffer=800)

    ws = websocket.WebSocketApp(ENDPOINT,
                               header={"Authorization": API_KEY},
                               on_message=on_message)

    # Implementation details...

if __name__ == "__main__":
    stream_audio()

2. Migration Checklist

Provide actionable steps:

## Migration Checklist

### Phase 1: Basic Setup ✅
- [ ] Install required packages
- [ ] Get AssemblyAI API key
- [ ] Test microphone access
- [ ] Run minimal example

### Phase 2: Update Code ✅
- [ ] Change endpoint URL
- [ ] Update authentication format
- [ ] Modify message parsing logic
- [ ] Update shutdown commands

### Phase 3: Testing ✅
- [ ] Test basic transcription
- [ ] Verify error handling
- [ ] Test session termination
- [ ] Performance validation

---

🏗️ Structure Improvements

1. Better Navigation

# Streaming Migration Guide: Deepgram to AssemblyAI

## Table of Contents
1. [Quick Start](#quick-start) ⚡
2. [Key Differences](#key-differences)
3. [Step-by-Step Migration](#migration-steps)
4. [Code Comparison](#code-comparison)
5. [Testing & Validation](#testing)
6. [Troubleshooting](#troubleshooting)
7. [Advanced Features](#advanced-features)

## Quick Start (5 minutes) ⚡
*Get a basic example running first, then migrate your full implementation*

2. Progressive Complexity

• Start with concept overview
• Provide minimal working example
• Show detailed implementation
• Cover edge cases and optimization

---

🎯 User Experience Improvements

1. Validation Steps

## Verify Your Migration

### Test Your Setup
```bash
# 1. Test API key
curl -H "Authorization: YOUR_API_KEY" \
     "https://api.assemblyai.com/v2/account"

# 2. Test microphone
python -c "import pyaudio; print('PyAudio working!')"

2. Migration Timeline

## Expected Migration Time

- **Simple implementation**: 30 minutes
- **Complex error handling**: 2-3 hours
- **Full feature migration**: 1 day
- **Testing & optimization**: Additional day

3. Support Resources

## Getting Help

### Quick References
- [API Documentation](link)
- [Error Code Reference](link)
- [Audio Configuration Guide](link)

### Community Support
- [Discord Community](link)
- [GitHub Issues](link)
- [Support Email](email)

---

📝 Specific Code Improvements

1. Add Input Validation

def validate_config():
    """Validate configuration before starting stream"""
    if not API_KEY or API_KEY == "YOUR-API-KEY":
        raise ValueError("Please set your API key")

    if SAMPLE_RATE not in [8000, 16000, 22050, 44

---