Guide to common Speechmatics configuration options including diarization, custom vocabulary, and output formats.

Stop searching through docs - common config options explained with working examples in one place!

• Common configuration parameters
• Speaker diarization setup
• Custom vocabulary for accuracy
• Output format options
• Punctuation and formatting controls
• Language and dialect selection

• Speechmatics API Key: Get one from portal.speechmatics.com
• Python 3.8+
• Completed Hello World example

Step 1: Create and activate a virtual environment

On Windows:

cd python
python -m venv .venv
.venv\Scripts\activate

On Mac/Linux:

cd python
python3 -m venv .venv
source .venv/bin/activate

Step 2: Install dependencies and run

pip install -r requirements.txt
cp ../.env.example .env
# Edit .env and add your SPEECHMATICS_API_KEY
python main.py

What it does: Identifies and labels different speakers in the audio

config = TranscriptionConfig(
    language="en",
    diarization="speaker",  # Enable speaker detection
    speaker_diarization_config={
        "prefer_current_speaker": True  # Reduce frequent speaker label changes
    }
)

Output:

SPEAKER S1: Hello, how are you today?
SPEAKER S2: I'm doing great, thanks for asking!

# Use max_speakers ONLY when you know the exact count
speaker_diarization_config={
    "max_speakers": 2  # Only if you're certain there are exactly 2 speakers
}

What it does: Improves accuracy for domain-specific terms

config = TranscriptionConfig(
    language="en",
    additional_vocab=[
        {"content": "Speechmatics", "sounds_like": ["speech matics", "speech mattics"]},
        {"content": "transcription"},
        {"content": "API", "sounds_like": ["A P I", "ay pee eye"]},
        {"content": "demo"},
    ]
)

Use cases:

• Product names (e.g., "Speechmatics")
• Technical jargon (e.g., "API", "transcription")
• Industry-specific terms
• Acronyms and abbreviations

What it does: Controls punctuation and entity detection

config = TranscriptionConfig(
    language="en",
    enable_entities=True,  # Detect dates, times, numbers, currencies
    punctuation_overrides={
        "sensitivity": 0.4,  # Control punctuation frequency (0.0-1.0)
        "permitted_marks": [".", "?", "!"]  # Limit allowed punctuation marks
    }
)

What it does: Customize output language format and optimize for specific domains

config = TranscriptionConfig(
    language="en",
    output_locale="en-US",  # RFC-5646 format
    domain="medical",       # Optimize for specific domain
)

Available domains:

• medical - Medical terminology

What it does: Specify language and enable language identification

from speechmatics.batch import JobConfig, JobType, TranscriptionConfig, LanguageIdentificationConfig

config = JobConfig(
    type=JobType.TRANSCRIPTION,
    transcription_config=TranscriptionConfig(language="en"),
    language_identification_config=LanguageIdentificationConfig(
        expected_languages=["en", "es", "fr"]  # Optional: hint at expected languages
    )
)

Supported languages: 50+ languages including English, Spanish, French, German, Japanese, Chinese, and more.

What it does: Balance between speed and accuracy

config = TranscriptionConfig(
    language="en",
    operating_point="enhanced",  # or "standard"
)

• standard - Fast, good accuracy
• enhanced - Slower, best accuracy

Here's an example combining multiple options:

import asyncio
import os
from dotenv import load_dotenv
from speechmatics.batch import AsyncClient, TranscriptionConfig, OperatingPoint

load_dotenv()

async def main():
    api_key = os.getenv("SPEECHMATICS_API_KEY")

    async with AsyncClient(api_key=api_key) as client:
        # Comprehensive configuration
        config = TranscriptionConfig(
            language="en",

            # Speaker diarization
            diarization="speaker",

            # Custom vocabulary with phonetic alternatives
            additional_vocab=[
                {"content": "Speechmatics", "sounds_like": ["speech matics", "speech mattics"]},
                {"content": "transcription"},
                {"content": "API", "sounds_like": ["A P I", "ay pee eye"]},
                {"content": "demo"},
            ],

            # Formatting
            enable_entities=True,  # Detect dates, times, numbers

            # Quality
            operating_point="enhanced",
        )

        # Transcribe with config
        result = await client.transcribe("audio.wav", transcription_config=config)
        print(result.transcript_text)

if __name__ == "__main__":
    asyncio.run(main())

======================================================================
SPEECHMATICS CONFIGURATION GUIDE
======================================================================

 Configuration:
   Language: en
   Diarization: speaker
   Custom vocabulary: 4 terms
   Entity detection: True
   Operating point: OperatingPoint.ENHANCED

 Transcribing with full configuration...

======================================================================
RESULTS
======================================================================

Transcript:
SPEAKER S1: Welcome to Speechmatics transcription API demo.
SPEAKER S2: This example shows multiple configuration options in action.
SPEAKER S1: Today is January 15th, 2025 at 3:30 p.m..
SPEAKER S2: The meeting will cost approximately $500 for the project.

Detected Entities:
----------------------------------------------------------------------
   • January 15th @ 8.48s
   • 2025 @ 9.64s
   • 3:30 p.m. @ 11.20s
   • $500 @ 15.80s

(Entity types: date, time, money, percentage, cardinal)

 Configuration demo complete!

 This example showed:
   • Speaker diarization
   • Custom vocabulary with phonetic alternatives (sounds_like)
   • Entity detection (dates, times, numbers, etc.)
   • Enhanced accuracy mode

Speaker Diarization:

• Automatic speaker detection and labeling
• Support for multi-speaker scenarios
• prefer_current_speaker for stable captioning (reduces label switching)
• Optional max_speakers limit (use with caution)

Custom Vocabulary:

• Domain-specific term accuracy
• Phonetic alternatives with sounds_like
• Support for acronyms and product names

Entity Detection:

• Automatic formatting of dates, times, numbers
• Currency detection and formatting
• Named entity recognition

Quality Settings:

• Operating point configuration (Enhanced vs Standard)
• Language and dialect selection
• Output locale customization

• Audio Intelligence - Add sentiment analysis and topics
• Multilingual & Translation - Work with multiple languages
• Turn Detection - Real-time turn detection for conversations

"max_speakers parameter invalid"

• Value must be greater than or equal to 2
• Only works when diarization="speaker"

Diarization errors / speakers being merged incorrectly

• If you're using max_speakers and seeing incorrect speaker attribution, remove it
• max_speakers forces the system to fit all speakers into that number, causing merging errors if the actual count is higher
• For unknown speaker counts, omit max_speakers entirely and let auto-detection handle it
• Consider using prefer_current_speaker: True instead for more stable speaker labels

"Custom vocabulary not working"

• Ensure terms are spelled correctly
• Use sounds_like for ambiguous terms
• Limit to 1000 terms for best performance

"Output format not supported"

• Check you're using: txt, json-v2, srt, or vtt
• Some formats only available in batch mode

• Formating Reference
• Supported Languages
• Output Formats

Help us improve this guide:

• Found an issue? Report it
• Have suggestions? Open a discussion

Time to Complete: 15 minutes Difficulty: Beginner API Mode: Batch (works with Real-time too)

Back to Basics | Back to Academy