Code examples, integrations, and templates for Speechmatics APIs and SDKs.
Explore code examples for transcription, voice-agent applications, and third-party integrations. Each example explains its setup, dependencies, and limitations.
Examples • Integrations • Use Cases • Developer Guides
Browse Examples • Quick Start • Contributing • portal • Documentation • Discord Community
Speechmatics provides Speech to Text (STT) and Text to Speech (TTS). Use the Batch API for pre-recorded audio, the Realtime API for streaming audio, and agent STT for transcript segments and turn events. Your application or framework combines these with a large language model (LLM), tools, and conversation logic to build a voice agent.
Flexible Deployment - SaaS on Cloud and on-prem options. Availability depends on the API and model; check the deployment documentation. Agent STT is available on SaaS on Cloud only.
Advanced Features - Model-specific capabilities include a custom dictionary, speaker diarization, speaker identification, smart formatting, and speech intelligence. Check the model comparison before combining features. Speaker focus in an integration may be implemented by the application or framework.
- What is Speechmatics?
- Quick Start
- Example Categories
- Community Projects
- Migration Guides
- Finding Examples
- Example Structure
- Contributing
- Support & Resources
- License
- Links
1. Get your API key from the portal. Use Python 3.12 to match the repository's Python CI environment, and check the selected example for additional requirements.
2. Install the SDK for your use case in a virtual environment. When running an Academy example, install its supplied requirements as shown below:
# Choose the package for your use case:
# Batch transcription
pip install speechmatics-batch
# Realtime streaming
pip install speechmatics-rt
# Agent STT: transcript segments plus speech and turn events
pip install speechmatics-agent-stt
# Text to Speech
pip install speechmatics-tts
# Deprecated Voice SDK: maintain existing client-side segmentation integrations
pip install speechmatics-voice📦 Package Details • Click to see what's included in each package
speechmatics-batch - Asynchronous transcription with the Batch API
- Upload audio files for processing
- Retrieve transcripts with word timings and supported speaker and entity metadata
- Request speech intelligence features supported by the selected model
speechmatics-rt - WebSocket streaming with the Realtime API
- Stream audio for live transcription
- Configure latency for models that support latency controls
- Partial and final transcripts
speechmatics-agent-stt - Agent STT with Linden 1, built on speechmatics-rt and using the /v2/agent endpoint
- Segment-level transcripts instead of word groups, plus speech and turn events
- Use the service's voice activity detection (VAD) to close turns by default
- 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
speechmatics-tts - Text to Speech
- Convert text to natural-sounding speech
- Multiple voices
- Read generated audio incrementally or save the complete response
speechmatics-voice - The deprecated Voice SDK, retained for existing applications
- Client-side turn detection selected through presets
- Speaker diarization and client-side segmentation
- Optional machine-learning turn detection:
pip install "speechmatics-voice[smart]" - Start new voice-agent transcription integrations with agent STT; your application supplies the LLM, TTS, tools, and conversation logic
SDK Documentation | API Reference
The commands below use PowerShell. macOS/Linux alternatives are shown in comments.
# 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
# Create a virtual environment (macOS/Linux: python3 -m venv .venv)
python -m venv .venv
# Activate the virtual environment (PowerShell)
.\.venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
# Install dependencies
python -m pip install -r requirements.txt
# Copy the environment template (PowerShell)
Copy-Item ..\.env.example .env
# macOS/Linux: cp ../.env.example .env
# Edit .env and add your SPEECHMATICS_API_KEY
# Run the example
python main.pyCaution
Never hardcode API keys in your source code. Always use environment variables (.env files) or secure secret management systems. Never commit .env to version control - only .env.example with placeholder values.
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-projectYou are now in the copied example directory. Follow its Quick Start, beginning with cd python and the virtual environment setup, then install dependencies, configure .env, and run the example.
Start with the fundamentals below, or choose an integration or focus to explore related examples and demos. Browse the complete catalog to find examples by package, feature, language, or difficulty.
Fundamental examples for getting started with the Speechmatics SDK.
Suggested path: Hello World → Batch vs Realtime → Configuration Guide, then choose a feature below. The table groups introductory examples first; folder numbers are stable identifiers rather than a required lesson sequence.
| Example | Description | Packages | Difficulty |
|---|---|---|---|
| Hello World - Your First Transcription | Transcribe a sample audio file with the Batch SDK. | Batch | beginner |
| Batch vs Realtime - Understanding API Modes | Compare file transcription with Batch and microphone streaming with Realtime. | Batch, Realtime | beginner |
| Configuration Guide - Common Configuration Options | Configure speaker labels, a custom dictionary, and formatting for Batch transcription. | Batch | beginner |
| Text to Speech | Convert text into speech with the TTS SDK. | TTS | beginner |
| Channel Diarization | Transcribe separate audio channels and label each channel. | Realtime | beginner |
| Melia 1 Multilingual Transcription | Transcribe audio that switches between languages with Melia 1. | Batch | beginner |
| Speech intelligence - Sentiment, Topics and Summaries | Extract sentiment, topics, and summaries from a recording. | Batch | intermediate |
| Multilingual & Translation | Stream English microphone audio and display Spanish and Russian translations. | Realtime | intermediate |
| Basic Turn Detection | Detect the end of speech using silence-based turn detection. | Realtime | intermediate |
| Intelligent Turn Detection Legacy | Compare turn-detection presets in the deprecated Voice SDK. | Voice SDK (legacy), Realtime | intermediate |
| Speaker ID & Speaker Focus Legacy | Save speaker identifiers and apply speaker focus with the deprecated Voice SDK. | Voice SDK (legacy), Realtime | intermediate |
| Preview WebSocket API Explorer Preview | Explore raw WebSocket clients for the Voice API preview. | Direct API / configuration | intermediate |
| Agent STT Linden 1 - Segments, Turns and Speakers | Handle transcript segments, turns, and speakers with Agent STT Linden 1. | Agent STT | intermediate |
Choose an integration to explore its examples and setup guides. Groups with several examples open a hub; a single example opens its own guide.
| Integration | Examples | What you'll build | Languages |
|---|---|---|---|
 |
1 example | Agora RTC/RTM with Speechmatics Realtime transcription and a managed LLM and speech synthesis pipeline. | Python, TypeScript |
 |
6 examples | Voice assistants with Agent STT, speaker controls, browser tools, and SIP telephony. | Python, JavaScript |
 |
2 examples | Local microphone and browser WebRTC voice agents using the Speechmatics adapter. | Python |
 |
4 examples | Phone agents through LiveKit SIP or direct Media Streams; the direct example uses the legacy Voice SDK. | Python |
 |
1 example | Managed voice assistants with Speechmatics streaming transcription and a custom dictionary. | Python |
 |
1 example | Desktop healthcare dictation with Speechmatics STT and configurable LLM formatting. | Configuration |
Explore examples by industry or workflow. Each collection brings together related examples from across the Academy; an example can appear in more than one collection.
| Focus | Examples | What you'll build | Languages |
|---|---|---|---|
| Healthcare | 5 examples | Medical transcription, clinical dictation, and consultation interfaces. | Python, JavaScript, Configuration |
| Telephony | 5 examples | Phone assistants, SIP and Media Streams, and recorded-call analysis. | Python |
| Multilingual | 6 examples | Translation, bilingual transcription, and multilingual code-switching. | Python, JavaScript, Dart |
| Voice agents | 16 examples | Speech interfaces, turn handling, and complete conversational pipelines. | Python, TypeScript, JavaScript |
| Captions and insights | 5 examples | Captions, live transcript displays, sentiment, topics, and summaries. | Python, JavaScript, Dart |
| Mobile | 1 example | Mobile audio capture and transcription applications. | Dart |
Projects built by the Speechmatics community. Community projects can use any language and follow the community submission requirements, including the repository's current CI checks.
Note
No community projects yet - yours could be the first! See How to Submit.
Community projects have two quality tiers:
Browse all community projects | Submit a project | Community Template
Switching from another Speech to Text provider? Use the migration guides to compare concepts, configuration, and code patterns. Check current SDK versions before adapting snippets.
| From | Guide | Features Covered | Status |
|---|---|---|---|
| Deepgram | Migration Guide | Batch, Streaming, Diarization, custom dictionary | Available |
| AssemblyAI | Migration Guide | Transcription, Audio Intelligence, Real-time | Not yet included |
| Google Cloud Speech | Migration Guide | Batch, Streaming, Multi-language | Not yet included |
| AWS Transcribe | Migration Guide | Batch Jobs, Streaming, custom dictionary | Not yet included |
| Azure Speech | Migration Guide | REST API, WebSocket, Pronunciation | Not yet included |
Note
The migration guide provides:
- Feature Mapping - Compare related features and their differences
- Code Comparison - Side-by-side before/after examples
- Migration Checklist - Step-by-step migration process
- Evaluation - Compare services on representative audio and current capabilities
- Code Examples - Supporting scripts with the setup and compatibility notes in the guide
Browse the catalog by package · feature · integration · language · collection · difficulty.
Follow each example's README for its dependencies, setup, and compatibility notes.
Small Python examples generally follow this structure. Web and mobile applications use framework-specific layouts described in their READMEs:
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
The example template calls for:
- What You'll Learn - Key concepts covered
- Prerequisites - Required setup
- Quick Start - Step-by-step instructions
- How It Works - Step-by-step explanation
- Key Features - Demonstrated capabilities
- Expected Output - Sample results
- Next Steps - Related examples
- Troubleshooting - Common issues
- Resources - Relevant documentation
We welcome contributions! There are many ways to help:
- 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
- Choose category (basics/integrations/use-cases)
- Follow structure (see EXAMPLE_TEMPLATE.md)
- Add metadata to docs/index.yaml and regenerate the discovery pages
- Write README using the template
- Test thoroughly
- Submit PR with clear description
See CONTRIBUTING.md for detailed guidelines.
Note
All examples must meet these standards:
- Clean, readable code following the conventions of its implementation language
- Follows SDK best practices
- Includes error handling and resource cleanup
- No hardcoded secrets
- Complete documentation
- Tested with the documented runtime; validation and untested live steps are stated
- Metadata in index.yaml
- GitHub Issues: Report bugs or request examples
- GitHub Community Discussions: Ask questions, share projects
- Discord Community: Join our Discord
- Email Support: devrel@speechmatics.com
- SDK Repository: speechmatics-python-sdk
- API Documentation: docs.speechmatics.com · Release notes
- Developer portal: portal.speechmatics.com
- Blog: speechmatics.com/blog
- Example Template - Template for new examples
- Contributing Guide - How to contribute
This project is licensed under the MIT License - see the LICENSE file for details.
SDK · Documentation · portal