Feedback: guides-speechmatics_to_aai_streaming

Documentation Feedback

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

---

Claude Sonnet 4 Feedback

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

Technical Documentation Analysis: Speechmatics to AssemblyAI Migration Guide

Overall Assessment

This migration guide provides comprehensive code examples but suffers from structural issues, missing critical information, and several user experience problems that could lead to migration failures.

Critical Issues & Recommendations

1. Missing Prerequisites & Setup Information

Issues:

• No system requirements (Python version, OS compatibility)
• Missing PyAudio installation challenges (common pain point)
• No environment setup guidance
• Missing API key format validation

Recommendations:

## Prerequisites

### System Requirements
- Python 3.7 or higher
- Operating System: Windows 10+, macOS 10.14+, or Linux (Ubuntu 18.04+)
- Microphone access permissions

### Install PyAudio (Common Issues)
PyAudio installation often fails. Try these solutions:

**macOS:**
```bash
brew install portaudio
pip install pyaudio

Ubuntu/Debian:

sudo apt-get install portaudio19-dev python3-pyaudio
pip install pyaudio

Windows:

pip install pipwin
pipwin install pyaudio

API Key Format

• Speechmatics: sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• AssemblyAI: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (no prefix)

### 2. **Poor Document Structure**

**Issues:**
- Code comparison appears before explanation
- Steps are buried within massive code blocks
- No clear migration path overview
- Missing quick reference section

**Recommended Structure:**
```markdown
# Migration Overview
## Key Differences Summary (table format)
## Migration Checklist
## Step-by-step Guide
## Code Examples
## Troubleshooting
## Quick Reference

3. Inadequate Key Differences Explanation

Issues:

• Differences are scattered throughout the document
• No side-by-side comparison table
• Missing performance/feature differences

Add this section:

## Key Differences at a Glance

| Aspect | Speechmatics | AssemblyAI |
|--------|-------------|------------|
| **Authentication** | `Bearer {token}` | `{api_key}` (no Bearer) |
| **Connection Setup** | Handshake required | Immediate streaming |
| **Audio Format** | Float32 (pcm_f32le) | Int16 (pcm_s16le) |
| **Sample Rate** | Dynamic/16kHz | Fixed 16kHz recommended |
| **Partial Results** | `AddPartialTranscript` | `Turn` with `turn_is_formatted: false` |
| **Final Results** | `AddTranscript` | `Turn` with `turn_is_formatted: true` |
| **Session End** | `EndOfTranscript` | `Termination` |
| **Error Handling** | `Error` message type | Standard WebSocket errors |

4. Code Examples Issues

Problems:

• Overwhelming single code blocks (200+ lines)
• No incremental examples
• Missing error scenarios
• No minimal working examples

Solutions:

Add minimal examples first:

# Minimal AssemblyAI streaming example
import websocket
import json

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

ws = websocket.WebSocketApp(
    "wss://streaming.assemblyai.com/v3/ws?sample_rate=16000",
    header={"Authorization": "YOUR_API_KEY"},
    on_message=on_message
)
ws.run_forever()

5. Missing Troubleshooting Section

Add comprehensive troubleshooting:

## Common Migration Issues

### Connection Problems
**Symptom:** WebSocket connection fails
**Speechmatics:** Check Bearer token format
**AssemblyAI:** Verify API key has no Bearer prefix

### Audio Format Errors
**Symptom:** No transcription results
**Solution:**
- Speechmatics expects Float32, AssemblyAI expects Int16
- Verify sample rate matches connection parameters

### Authentication Failures
**Speechmatics:** `{"message": "Error", "type": "authentication_error"}`
**AssemblyAI:** HTTP 401 or connection refused

### Performance Issues
**High Latency:** Reduce FRAMES_PER_BUFFER to 400-800
**Dropped Audio:** Increase buffer size, check network stability

6. Missing Migration Validation

Add validation section:

## Validate Your Migration

### Test Checklist
- [ ] Connection establishes successfully
- [ ] Partial transcripts appear in real-time
- [ ] Final transcripts are properly formatted
- [ ] Session terminates cleanly
- [ ] Error handling works correctly

### Performance Validation
```python
import time

# Add timing validation to your code
start_time = time.time()
transcript_count = 0

def on_message(ws, message):
    global transcript_count, start_time
    transcript_count += 1

    if transcript_count % 10 == 0:
        elapsed = time.time() - start_time
        print(f"Performance: {transcript_count/elapsed:.2f} messages/second")

7. Improve Quick Reference

Add at the end:

## Quick Reference

### URL Patterns
```python
# Speechmatics
"wss://eu2.rt.speechmatics.com/v2/en"

# AssemblyAI
"wss://streaming.assemblyai.com/v3/ws?sample_rate=16000"

Message Type Mapping

# Speechmatics → AssemblyAI
"RecognitionStarted" → "Begin"
"AddPartialTranscript" → "Turn" (turn_is_formatted: false)
"AddTranscript" → "Turn" (turn_is_formatted: true)
"EndOfTranscript" → "Termination"
"EndOfStream" → {"type": "Terminate"}

8. User Experience Improvements

Issues:

• No progress indicators in migration steps
• Missing estimated time to complete
• No success criteria defined

Add:

## Migration Timeline
- **Preparation:** 15 minutes (API keys, dependencies)
- **Code Migration:** 30-45 minutes
- **Testing & Validation:** 15-30 minutes
- **Total Estimated Time:** 1-1.5 hours

## Success Criteria
✅ Real-time transcription working
✅ Latency < 500ms for partials
✅ Clean session termination
✅ Error handling functional

9. Missing Advanced Features

Add section:

## Advanced Feature Migration

### Language Detection
**Speechmatics:** `"language": "auto"`
**AssemblyAI:** Not needed (automatic)

### Custom Vocabularies
**Speechmatics:** Custom dictionary in config
**AssemblyAI:** `word_boost` parameter

### Speaker Labels
**Both:** Available but different configuration

10. Environment-Specific Guidance

Add:

## Environment-Specific Notes

### Production Considerations
- Use temporary tokens for client-side implementations
- Implement connection retry logic
- Add proper logging and monitoring
- Consider connection pooling for high volume

### Development vs Production
- Development: Use API keys directly
- Production: Generate temporary tokens
- Testing: Use shorter timeout values

Summary

The documentation needs significant restructuring with clearer progressive disclosure, better error handling guidance, and more practical migration validation steps. The current version may overwhelm users and lead to implementation failures due to missing critical setup information and troubleshooting guidance.

---