Working examples, integrations, and templates for the Speechmatics SDK's.
Comprehensive collection of code examples demonstrating real-world applications, third-party integrations, and best practices.
Examples • Integrations • Use Cases • Copy-Paste Ready
Browse Examples • Quick Start • Contributing • Portal • Documentation • Discord Community
What is Speechmatics?
Speechmatics is a leading Automatic Speech Recognition (ASR) platform providing highly accurate speech-to-text (STT) and text-to-speech (TTS) APIs. Whether you're building real-time voice assistants, conversational voice AI agents, transcription services, or call center tools, Speechmatics provides the foundation for accurate, scalable speech AI.
Flexible Deployment - Cloud SaaS, on-premises, air-gapped environments, or on-device edge deployment.
Advanced Features - Domain-specific models, custom dictionaries, speaker diarization, speaker identification, and speaker focus for multi-speaker scenarios and much more.
📋 Table of Contents
- What is Speechmatics?
- Quick Start
- Theory
- Example Categories
- Community Projects
- Migration Guides
- Finding Examples
- Example Structure
- Contributing
- Support & Resources
⚡ Quick Start
Prerequisites
1. Get your API Key portal.speechmatics.com
2. Install the SDK for your use case:
# Choose the package for your use case:
Batch transcription
pip install speechmatics-batch
Real-time streaming
pip install speechmatics-rt
Speech-to-text for voice agents: segments plus speech and turn events
pip install speechmatics-agent-stt
Text-to-speech
pip install speechmatics-tts
Voice agent SDK: conversation management and turn-detection presets
pip install speechmatics-voice📦 Package Details • Click to see what's included in each package
speechmatics-batch - Async batch transcription API
- Upload audio files for processing
- Get transcripts with highly accurate timestamps, speakers, entities
- Supports all audio intelligence features
- Stream audio for live transcription
- Ultra-low latency
- Partial and final transcripts
speechmatics-rt
- Segment-level transcripts instead of word groups, plus speech and turn events
- Turn detection included and on by default, from the service's own VAD: streaming audio is all it needs
- Or set
TurnDetectionMode.EXTERNALto close each turn yourself, when Pipecat, LiveKit or your own VAD already owns that decision - Pick this for the transcription layer alone, with your own code driving the conversation
- Convert text to natural-sounding speech
- Multiple voices
- Streaming and batch modes
- Built-in turn detection, selected from presets rather than wired up yourself
- Speaker diarization and conversation management
- Optional ML-based smart turn:
pip install speechmatics-voice[smart] - Pick this when you want the agent loop provided rather than bringing your own
SDK Documentation | API Reference
Option 1: Clone and Run
# Clone the repository
git clone https://github.com/speechmatics/speechmatics-academy.git
cd speechmatics-academy
Navigate to an example
cd basics/01-hello-world/python
Setup virtual environment
python -m venv .venv
Activate virtual environment (Windows)
.venv\Scripts\activate
On Mac/Linux: source .venv/bin/activate
Install dependencies
pip install -r requirements.txt
Set up environment variables
cp ../.env.example .env
Edit .env and add your SPEECHMATICS_API_KEY
Run the example
python main.py[!CAUTION]
Never hardcode API keys in your source code. Always use environment variables (.envfiles) or secure secret management systems. Never commit.envto version control - only.env.examplewith placeholder values.
Option 2: Direct Copy
Use degit to copy individual examples:
# Install degit
npm install -g degit
Copy an example
degit speechmatics/speechmatics-academy/basics/01-hello-world my-project
cd my-project📖 Theory
New to speech recognition? Start here to understand the core concepts before diving into code.
| Topic | Description | |-------|-------------| | Introduction to ASR | How automatic speech recognition converts audio to text using acoustic and language models | | Introduction to LLMs | Understanding large language models and their role in voice AI applications | | Prompt Engineering | Crafting effective prompts for voice agents and conversational AI | | Choosing the Right Model | Comparing model types, capabilities, and when to use each |
[!NOTE]
Theory guides are coming soon. In the meantime, check out the "How It Works" sections in each example.
📚 Example Categories
Fundamentals
Fundamental examples for getting started with the Speechmatics SDK.
| Example | Description | Packages | Difficulty |
|---------|-------------|----------|------------|
| Hello World | The absolute simplest transcription example | Batch | Beginner |
| Batch vs Real-time | Learn the difference between API modes | Batch RT | Beginner |
| Configuration Guide | Common configuration options | Batch | Beginner |
| Text-to-Speech | Convert text to natural-sounding speech | TTS | Beginner |
| Channel Diarization | Multi-channel transcription with speaker attribution | Voice RT | Beginner |
| Melia Multilingual | Transcribe multilingual, code-switching audio with the Melia model | Batch | Beginner |
| Audio Intelligence | Extract insights with sentiment, topics, and summaries | Batch | Intermediate |
| Multilingual & Translation | Transcribe 50+ languages and translate | RT | Intermediate |
| Basic Turn Detection | Silence-based turn detection with Real-Time SDK | RT | Intermediate |
| Intelligent Turn Detection | Smart turn detection with Voice SDK presets | Voice | Intermediate |
| Speaker ID & Speaker Focus | Extract speaker IDs and control which speakers drive conversation | Voice | Intermediate |
| Voice API Explorer | Explore every Voice API WebSocket feature - RT and Voice modes, all profiles, mid-session control | WebSocket | Intermediate |
| Agent STT | Segment-level transcripts, speech and turn events, speaker voiceprints, and choosing who closes the turn | Agent STT | Intermediate |
Integrations
Third-party framework and service integrations.
| Integration | Example | Features | Languages |
|-------------|---------|----------|-----------|
| 
| Simple Voice Bot | Local audio, VAD, diarization, focus speakers, passive filtering, LLM, TTS, interruptions | Python |
| | Simple Voice Bot (Web) | Browser-based WebRTC, VAD, diarization, focus speakers, passive filtering, LLM, TTS | Python |
| 
| Outbound Dialer | REST API, outbound calls, Media Streams, Speechmatics STT, ElevenLabs TTS | Python |
|
Use Cases
Example applications for specific industries.
| Industry | Example | Features | |----------|---------|----------| | Healthcare | Medical Transcription | Real-time, custom medical vocabulary, HIPAA compliance | | Media | Video Captioning | SRT generation, timestamp sync, batch processing | | Contact Center | Call Analytics | Channel diarization, sentiment analysis, topic detection, summarization | | Business | AI Receptionist | LiveKit voice agent, Twilio SIP, Google Calendar booking, function calling | | Entertainment | Santa Voice Agent | LiveKit, ElevenLabs TTS, custom vocabulary, Twilio SIP telephony | | Healthcare | Medical Assistant | Bilingual AR+EN, speaker diarization, GPT-4o extraction, SOAP notes, ICD-10 | | Healthcare | Medical Microbatching | Continuous mic capture via Batch API, Silero VAD chunking, concurrent jobs, HIPAA-friendly on-prem | | Business | Alphanumerics Form Filler | LiveKit voice agent, real-time STT with smart turn detection, browser RPC form filling, digit-by-digit confirmation | | Mobile | Mobile Transcription App | Flutter (Android & iOS), Batch API, Melia-1 multilingual transcription, speaker diarization & identification, translation, speech intelligence | | Events | Wall of Voices | Real-time Melia multilingual transcription, per-word language tags, browser WebSocket audio, right-to-left rendering, short-lived token endpoint | | Healthcare | Oak Consultation Studio · Live demo | Oak 1 multilingual medical transcription, automatic file and microphone transcription, synchronized playback, speaker/channel exploration, Python serverless backend |
🌍 Community Projects
Projects built by the Speechmatics community. Community projects can be written in any language and have lighter quality requirements than official examples.
[!NOTE]
No community projects yet - yours could be the first! See How to Submit.
Community projects have two quality tiers:
!Verified Maintainer-audited, fully template-compliant, tested end-to-end
!Community Basic structure, working code, light review
Browse all community projects | Submit a project | Community Template
🔄 Migration Guides
Switching from another speech-to-text provider? Our migration guides help you transition smoothly with feature mappings, code comparisons, and practical examples.
| From | Guide | Features Covered | Status | |------|-------|------------------|--------| | Deepgram | Migration Guide | Batch, Streaming, Diarization, Custom Vocabulary | Available | | AssemblyAI | Migration Guide | Transcription, Audio Intelligence, Real-time | Coming Soon | | Google Cloud Speech | Migration Guide | Batch, Streaming, Multi-language | Coming Soon | | AWS Transcribe | Migration Guide | Batch Jobs, Streaming, Custom Vocabulary | Coming Soon | | Azure Speech | Migration Guide | REST API, WebSocket, Pronunciation | Coming Soon |
[!NOTE]
Each migration guide includes:
- Feature Mapping - Direct equivalent features comparison
- Code Comparison - Side-by-side before/after examples
- Migration Checklist - Step-by-step migration process
- Advantages - Benefits of switching to Speechmatics
- Working Examples - Complete runnable code
🔍 Finding Examples
Find examples for the SDK package you installed:By Package
| Package | Description | Examples |
|---------|-------------|----------|
| speechmatics-batch | Async transcription of audio files | Hello World, Batch vs Real-time, Configuration Guide, Audio Intelligence, Multilingual & Translation, Video Captioning, Call Analytics, Medical Microbatching |
| speechmatics-rt | Real-time transcription | Batch vs Real-time, Configuration Guide, Multilingual & Translation, Basic Turn Detection, Channel Diarization, Medical Transcription, Medical Assistant, Medical Microbatching, Alphanumerics Form Filler, Wall of Voices |
| speechmatics-voice | Voice agent with conversation management | Intelligent Turn Detection, Speaker ID & Speaker Focus, Twilio Outbound Dialer |
| speechmatics-agent-stt | Segment-level STT for voice agents | Agent STT |
| speechmatics-tts | Text-to-speech synthesis | Text-to-Speech |
By Feature
| Feature | Examples | |---------|----------| | Batch Transcription | Hello World, Batch vs Real-time, Configuration Guide, Audio Intelligence, Video Captioning, Call Analytics, Medical Microbatching, Mobile Transcription App, Melia Multilingual, Oak Consultation Studio | | Real-time | Batch vs Real-time, Configuration Guide, Basic Turn Detection, Voice API Explorer, Agent STT, Agora Conversational AI Agent, LiveKit Voice Assistant, Medical Transcription, Medical Assistant, Alphanumerics Form Filler, Wall of Voices | | Turn Detection | Basic Turn Detection, Intelligent Turn Detection, Voice API Explorer, Agent STT | | Voice Agents | Intelligent Turn Detection, Speaker ID & Speaker Focus, Voice API Explorer, Agent STT, Agora Conversational AI Agent, LiveKit Voice Assistant, Pipecat Voice Bot, Pipecat Voice Bot (Web), Twilio Outbound Dialer, VAPI Voice Assistant, AI Receptionist, Santa Voice Agent, Alphanumerics Form Filler, Speaker Focus Voice Agent | | Speaker Diarization | Configuration Guide, Speaker ID & Speaker Focus, Channel Diarization, Voice API Explorer, Agent STT, LiveKit Voice Assistant, Call Analytics, Medical Assistant, Mobile Transcription App, Speaker Focus Voice Agent, Oak Consultation Studio | | Speaker Identification | Speaker ID & Speaker Focus, Agent STT, Voice API Explorer, LiveKit Voice Assistant, Mobile Transcription App, Speaker Focus Voice Agent | | Sentiment Analysis | Audio Intelligence, Call Analytics | | Topic Detection | Audio Intelligence, Call Analytics, Mobile Transcription App | | Summarization | Audio Intelligence, Call Analytics, Mobile Transcription App | | Translation | Multilingual & Translation, Mobile Transcription App | | Text-to-Speech | Text-to-Speech |
By Integration
| Integration | Examples | Documentation | Status | |-------------|----------|---------------|--------| | Agora | Conversational AI Voice Agent | Agora Conversational AI Docs | Available | | LiveKit | Simple Voice Assistant, Telephony with Twilio, AI Receptionist, Santa Voice Agent, Alphanumerics Form Filler, Speaker Focus Voice Agent | LiveKit Docs | Available | | Pipecat AI | Simple Voice Bot, Simple Voice Bot (Web) | Pipecat Docs | Available | | Twilio | Outbound Dialer, Telephony with Twilio, AI Receptionist, Santa Voice Agent | Twilio Media Streams | Available | | VAPI | Voice Assistant | docs.vapi.ai | Available | | Tambourine | Healthcare Dictation | GitHub | Available |
By Language
| Language | Examples | Status | |----------|----------|--------| | Python | Hello World, Batch vs Real-time, Configuration Guide, Audio Intelligence, Multilingual & Translation, Text-to-Speech, Basic Turn Detection, Intelligent Turn Detection, Speaker ID & Speaker Focus, Channel Diarization, Voice API Explorer, Agora Conversational AI Agent, LiveKit Voice Assistant, LiveKit Telephony, Pipecat Voice Bot, Pipecat Voice Bot (Web), Twilio Outbound Dialer, VAPI Voice Assistant, Medical Transcription, Video Captioning, Call Analytics, AI Receptionist, Santa Voice Agent, Medical Assistant, Medical Microbatching, Alphanumerics Form Filler, Melia Multilingual, Speaker Focus Voice Agent, Wall of Voices, Agent STT, Oak Consultation Studio | Available | | Dart / Flutter | Mobile Transcription App | Available | | JavaScript | Oak Consultation Studio | Available | | TypeScript | Agora Conversational AI Agent | Available | | C# | - | Coming Soon |
By Difficulty
| Difficulty | Examples | |------------|----------| | Beginner | Hello World, Batch vs Real-time, Configuration Guide, Text-to-Speech, Channel Diarization, VAPI Voice Assistant, Tambourine Healthcare Dictation, Video Captioning, Call Analytics, Melia Multilingual | | Intermediate | Audio Intelligence, Multilingual & Translation, Basic Turn Detection, Intelligent Turn Detection, Speaker ID & Speaker Focus, Voice API Explorer, Agora Conversational AI Agent, LiveKit Voice Assistant, Pipecat Voice Bot, Pipecat Voice Bot (Web), Medical Transcription, Medical Microbatching, Alphanumerics Form Filler, Mobile Transcription App, Speaker Focus Voice Agent, Wall of Voices, Agent STT, Oak Consultation Studio | | Advanced | LiveKit Telephony, Twilio Outbound Dialer, AI Receptionist, Santa Voice Agent, Medical Assistant |
📁 Example Structure
Every example follows a consistent structure:
example-name/
├── python/
│ ├── main.py # Primary Python implementation
│ ├── requirements.txt # Python dependencies
│ └── .gitignore # Ignore venv/, __pycache__/, .env
├── assets/ # Sample files, images, etc.
│ ├── sample.wav # Sample audio (if needed)
│ └── agent.md # Agent prompt (for voice agents)
├── .env.example # Environment variables template
└── README.md # Main documentation (REQUIRED)[!NOTE]
Each example includes:
> 1. What You'll Learn - Key concepts covered
2. Prerequisites - Required setup
3. Quick Start - Step-by-step instructions
4. How It Works - Step-by-step explanation
5. Key Features - Demonstrated capabilities
6. Expected Output - Sample results
7. Next Steps - Related examples
8. Troubleshooting - Common issues
9. Resources - Relevant documentation
🤝 Contributing
We welcome contributions! There are many ways to help:
Ways to Contribute
- Add New Examples - Share your implementations
- Submit Community Projects - Share your own projects in any language (learn more)
- Improve Existing Examples - Fix bugs, add features
- Add Language Support - Port examples to other languages
- Fix Documentation - Improve README files
- Report Issues - Help us improve quality
Adding a New Example
- Choose category (basics/integrations/use-cases)
- Follow structure (see EXAMPLE_TEMPLATE.md)
- Add metadata to docs/index.yaml
- Write README using the template
- Test thoroughly
- Submit PR with clear description
Quality Standards
[!NOTE]
All examples must meet these standards:
- Clean, readable, well-commented Python code
- Follows SDK best practices
- Includes proper error handling
- No hardcoded secrets
- Complete documentation
- Tested end-to-end
- Metadata in index.yaml
🆘 Support & Resources
Getting Help
- GitHub Issues: Report bugs or request examples
- GitHub Community Discussions: Ask questions, share projects
- Discord Community: Join our Discord
- Email Support: [email protected]
Resources
- SDK Repository: speechmatics-python-sdk
- API Documentation: docs.speechmatics.com
- Developer Portal: portal.speechmatics.com
- Blog: speechmatics.com/blog
Documentation
- Example Template - Template for new examples
- Contributing Guide - How to contribute
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🔗 Links
- SDK: github.com/speechmatics/speechmatics-python-sdk
- Docs: docs.speechmatics.com
- Portal: portal.speechmatics.com