Speechmatics Python Client

https://github.com/speechmatics/speechmatics-python
Admin
This Python client library and CLI for Speechmatics Realtime and Batch ASR v2 APIs provides an...
Tokens:12,631
Snippets:160
Trust Score:8.9
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install speechmatics-python from source

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/wer/README.md

Install the source code directly from the GitHub repository.

```bash
git clone https://github.com/speechmatics/speechmatics-python.git && python setup.py install
```

--------------------------------

### Clone and Install from Source

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Clone the repository and install the package from source code. This method is useful if you need to run the source code directly.

```bash
git clone https://github.com/speechmatics/speechmatics-python.git && cd speechmatics-python && python setup.py install
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Installs the pre-commit framework to automatically check code formatting and linting on each commit. Run this command if pre-commit is not already installed.

```bash
pre-commit install
```

--------------------------------

### Install Development Dependencies and Run Tests

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Installs necessary development dependencies and executes tests for the library. Ensure you have the requirements-dev.txt file available.

```bash
pip install -r requirements-dev.txt
make test
```

--------------------------------

### Install Speechmatics Python Client

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Install the Speechmatics Python client from PyPI. Use the optional dependencies for metrics tools.

```bash
pip install speechmatics-python
```

```bash
pip install speechmatics-python[metrics]
```

--------------------------------

### Install speechmatics-python Package

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Install the speechmatics-python package using pip. This is the recommended way to get started with the CLI tool.

```bash
pip install speechmatics-python
```

--------------------------------

### Install Speechmatics Python from Source

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Install the Speechmatics Python client from source code. Windows users may need the --user flag.

```bash
git clone https://github.com/speechmatics/speechmatics-python
cd speechmatics-python && python setup.py install
```

```bash
python setup.py install --user
```

--------------------------------

### Install Dependencies

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/notification_flow/README.md

Installs the necessary Python packages for the project. Ensure you have Python 3.7 or higher.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Streamlink

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcribe_from_youtube/README.md

Installs the streamlink package, which is required for transcribing online videos.

```bash
pip3 install streamlink
```

--------------------------------

### Install Requirements (macOS)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcript_distribution_server/README.md

Installs necessary tools like ffmpeg and websocat, and project dependencies using pip.

```bash
brew install ffmpeg
pip3 install -r requirements.txt

# For testing
brew install websocat
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Installs the necessary dependencies for developing the Speechmatics Python SDK. Ensure you have a compatible Python version (3.7-3.10) installed.

```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

--------------------------------

### Start Real-time Transcription (Enterprise SaaS)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Starts a real-time transcription session for enterprise SaaS customers, specifying a custom runtime URL.

```bash
# Point URL to the a SaaS enterprise runtime
URL=wss://neu.rt.speechmatics.com/v2/en

speechmatics transcribe --url $URL example_audio.wav
```

--------------------------------

### LAB File Format

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Example of the LAB file format for speaker diarization. Each line specifies start time, end time, and speaker.

```text
<start time> <end time> <speaker>
```

--------------------------------

### Start Transcript Distribution Server

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcript_distribution_server/README.md

Starts the Speechmatics transcript distribution server on a specified port.

```bash
python3 transcript_distribution_server.py --port 8765
```

--------------------------------

### Start Real-time Transcription (On-Prem)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Initiates a real-time transcription session for on-premises customers, pointing to a local Speechmatics runtime instance.

```bash
# Point URL to the local instance of the realtime appliance
URL=ws://realtimeappliance.yourcompany:9000/v2

speechmatics transcribe --url $URL --lang en --ssl-mode none example_audio.wav
```

--------------------------------

### Start Real-time Transcription (SaaS)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Initiates a real-time transcription session for self-service SaaS customers using a local WAV audio file.

```bash
speechmatics transcribe --lang en example_audio.wav
```

--------------------------------

### Run YouTube Transcription Example

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcribe_from_youtube/README.md

Executes the youtube_transcribe module to transcribe a given YouTube video URL. The authentication token is automatically picked up from the Speechmatics configuration.

```bash
python3 -m youtube_transcribe --input-url https://youtu.be/x438-2c59l8
```

--------------------------------

### CTM File Format

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Example of the CTM file format for speaker diarization. Each line specifies file ID, speaker, start time, end time, word, and confidence.

```text
<file id> <speaker> <start time> <end time> <word> <confidence>
```

--------------------------------

### JSON Diarisation Reference Format

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Example of the JSON format for diarisation reference. It includes speaker name, word, start time, and duration.

```json
[
    {
        "speaker_name": "Speaker 1",
        "word": "Seems",
        "start": 0.75,
        "duration": 0.29
    },
]
```

--------------------------------

### Real-time Transcription with Partials (Ubuntu/ALSA)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Transcribes audio from the microphone in real-time, enabling partial word results as they become available. Requires ffmpeg and ALSA setup.

```bash
ffmpeg -loglevel quiet -f alsa -i hw:0 -f f32le -acodec pcm_f32le -ar 44100 - \
    | speechmatics transcribe --url $URL --ssl-mode none --enable-partials --raw pcm_f32le --sample-rate 44100 -
```

--------------------------------

### Start Notification Server

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/notification_flow/README.md

Runs the Python script that listens for and receives webhook notifications from the Speechmatics API. Ensure your server is publicly accessible or use a service like webhook.site for local testing.

```bash
python server.py
```

--------------------------------

### Initial JSON Message for Server

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcript_distribution_server/README.md

The initial JSON message required by the server to start streaming from a specified URL and language.

```json
{"url": "https://cdn.bitmovin.com/content/assets/art-of-motion-dash-hls-progressive/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd", "language": "en"}
```

--------------------------------

### Real-time Transcription of Online Stream

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Transcribes an online audio stream in real-time. Requires ffmpeg to be installed and accessible in the system's PATH.

```bash
ffmpeg -v 0 -i https://cdn.bitmovin.com/content/assets/art-of-motion-dash-hls-progressive/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd \
  -f s16le -ar 44100 -ac 1 -acodec pcm_s16le - | \
  speechmatics transcribe --raw pcm_s16le --sample-rate 44100 -
```

--------------------------------

### Real-time Transcription with Translation via FFmpeg

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Start a real-time transcription session using microphone audio piped through FFmpeg to the Speechmatics transcriber. Includes translation to French.

```bash
ffmpeg -loglevel quiet -f alsa -i hw:0 -f f32le -acodec pcm_f32le -ar 44100 - \
    | speechmatics rt transcribe --url $URL --ssl-mode none --raw pcm_f32le --sample-rate 44100 \
--print-json --translation-langs fr -
```

--------------------------------

### Get Batch Job Status

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieves the current status of a transcription job. Requires the job ID.

```bash
speechmatics batch job-status [-h] [--url URL] [--auth-token AUTH_TOKEN]
                              [--ssl-mode {regular,insecure,none}]
                              [--generate-temp-token] [--profile PROFILE]
                              --job-id JOB_ID
```

--------------------------------

### Get Batch Job Results

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieves the results of a transcription job. Specify the job ID and desired output format.

```bash
speechmatics batch get-results [-h] [--url URL] [--auth-token AUTH_TOKEN]
                               [--ssl-mode {regular,insecure,none}]
                               [--generate-temp-token] [--profile PROFILE]
                               [--output-format {txt,json,json-v2,srt}]
                               --job-id JOB_ID
```

--------------------------------

### Get Speechmatics Batch Job Status

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Retrieve the status of a previously submitted batch job. Requires the job ID obtained from the submit command.

```bash
# $JOB_ID is from the submit command output
speechmatics batch job-status --job-id $JOB_ID
```

--------------------------------

### Show CLI Help from Source Code

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/README.md

Execute the main module directly from the source code to access the command-line interface help.

```bash
python3 -m asr_metrics.cli -h
```

--------------------------------

### Run Kitchen Sync CLI for Batch Transcription

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/sync/README.md

This command-line interface demonstrates how to use the kitchen sync module for batch transcription of audio files. It requires an API key and a directory containing audio files.

```bash
python3 -m examples.sync.kitchen $API_KEY mp3s/
```

--------------------------------

### Search Transcripts using Kitchen Sync CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/sync/README.md

This command-line interface demonstrates how to search through existing transcripts using the kitchen sync module. It requires an API key, a directory of audio files, and a search term.

```bash
python3 -m examples.sync.kitchen $API_KEY mp3s/ --search earnings
```

--------------------------------

### Show CLI Help for sm-metrics

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/README.md

Use this command to view all available options for the sm-metrics command-line interface.

```bash
sm-metrics -h
```

--------------------------------

### List Available Input Devices (Ubuntu/ALSA)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Lists the available sound cards and audio input devices on an Ubuntu system using ALSA. This is useful for configuring microphone input for transcription.

```bash
cat /proc/asound/cards
```

--------------------------------

### Connect Client with Websocat

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcript_distribution_server/README.md

Connects a client to the running transcript distribution server using websocat.

```bash
websocat ws://127.0.0.1:8765
```

--------------------------------

### Show WER help command

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/wer/README.md

Display all available commands and options for the sm-metrics wer command.

```bash
sm-metrics wer -h
```

--------------------------------

### List Available Microphone Input Devices (macOS)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Lists the audio input devices available on macOS using ffmpeg. This helps in identifying the correct device identifier for piping microphone audio.

```bash
ffmpeg -f avfoundation -list_devices true -i ""
```

--------------------------------

### Realtime Transcription with Library Usage

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/index.md

Illustrates how to transcribe a waveform audio file using the Realtime API. Requires setting up connection settings, event handlers for partial and full transcripts, and transcription configuration.

```python
import speechmatics

LANGUAGE = "en"
AUDIO_FILE_PATH = "/path/to/file"
CONNECTION_URL = f"wss://eu2.rt.speechmatics.com/v2/{LANGUAGE}"
AUTH_TOKEN = "add token here"

# Create a transcription client
ws = speechmatics.client.WebsocketClient(
    speechmatics.models.ConnectionSettings(
        url=CONNECTION_URL,
        auth_token=AUTH_TOKEN,
    )
)


# Define an event handler to print the partial transcript
def print_partial_transcript(msg):
    print(f"(PART) {msg['metadata']['transcript']}")


# Define an event handler to print the full transcript
def print_transcript(msg):
    print(f"(FULL) {msg['metadata']['transcript']}")


# Register the event handler for partial transcript
ws.add_event_handler(
    event_name=speechmatics.models.ServerMessageType.AddPartialTranscript,
    event_handler=print_partial_transcript,
)

# Register the event handler for full transcript
ws.add_event_handler(
    event_name=speechmatics.models.ServerMessageType.AddTranscript,
    event_handler=print_transcript,
)

settings = speechmatics.models.AudioSettings()

# Define transcription parameters
conf = speechmatics.models.TranscriptionConfig(
    language=LANGUAGE,
    enable_partials=True,
)

with open("example.wav", 'rb') as file:
    ws.run_synchronously(file, conf, settings)
```

--------------------------------

### Configure CLI Environment

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Manages local CLI configuration settings. Use 'set' to configure values and 'unset' to remove them.

```bash
speechmatics config [-h] {set,unset} ...
```

--------------------------------

### Run sm-metrics CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/wer/README.md

Execute the sm-metrics command-line interface module directly for WER calculations.

```bash
cd speechmatics-python && python3 -m asr_metrics.cli wer <options>
```

--------------------------------

### Run from Source Code

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Execute the diarization metrics tool directly from the source code using the Python module.

```bash
python3 -m asr_metrics.cli <reference file> <transcript_file>
```

--------------------------------

### Configure Transcriber URLs for CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Sets the URLs for connecting to real-time and batch Speechmatics transcribers. These can be used instead of the --url flag.

```bash
speechmatics config set --rt-url wss://eu2.rt.speechmatics.com/v2 --batch-url https://asr.api.speechmatics.com/v2
```

--------------------------------

### transcribe

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Real-time commands. RETAINED FOR LEGACY COMPATIBILITY.

```APIDOC
## transcribe

### Description
Real-time commands. RETAINED FOR LEGACY COMPATIBILITY.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Positional Arguments
- **FILEPATHS** (list of strings) - Required - Paths to audio files for transcription.

#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--streaming-mode** (flag) - Optional - Enable streaming mode.
- **--enable-partials** (flag) - Optional - Enable partial results.
- **--enable-transcription-partials** (flag) - Optional - Enable transcription partials.
- **--enable-translation-partials** (flag) - Optional - Enable translation partials.
- **--punctuation-sensitivity** (string) - Optional - Sensitivity for punctuation.
- **--speaker-diarization-max-speakers** (integer) - Optional - Maximum number of speakers for diarization.
- **--speaker-diarization-sensitivity** (string) - Optional - Sensitivity for speaker diarization.
- **--speaker-diarization-prefer-current-speaker** (flag) - Optional - Prefer current speaker in diarization.
- **--max-delay** (string) - Optional - Maximum delay for real-time processing.
- **--max-delay-mode** (string) - Optional - Mode for maximum delay (fixed, flexible).
- **--raw** (string) - Optional - Encoding for raw audio input.
- **--sample-rate** (integer) - Optional - Sample rate of the audio.
- **--chunk-size** (integer) - Optional - Chunk size for audio processing.
- **--buffer-size** (integer) - Optional - Buffer size for audio processing.
- **--print-json** (flag) - Optional - Print results in JSON format.
- **--diarization** (string) - Optional - Speaker diarization mode (none, speaker, channel).
- **--audio-events** (flag) - Optional - Enable audio events.
- **--event-types** (list of strings) - Optional - Types of audio events to enable.
- **--extra-headers** (list of strings) - Optional - Additional headers in KEY=VALUE format.
- **--url** (string) - Optional - URL for the Speechmatics API.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--ssl-mode** (string) - Optional - SSL mode for the connection (regular, insecure, none).
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
- **--config-file** (string) - Optional - Path to a configuration file.
- **--lang** (string) - Optional - Language of the audio.
- **--volume-threshold** (integer) - Optional - Volume threshold for silence detection.
- **--end-of-utterance-silence-trigger** (integer) - Optional - Silence duration to trigger end of utterance.
- **--remove-disfluencies** (flag) - Optional - Remove disfluencies from the transcript.
- **--replacement-words** (list of strings) - Optional - Words to replace in the transcript.
- **--replacement-words-file** (string) - Optional - File containing words to replace.
- **--operating-point** (string) - Optional - Operating point for the transcription model (standard, enhanced).
- **--domain** (string) - Optional - Domain for the transcription model.
- **--output-locale** (string) - Optional - Locale for the output.
- **--additional-vocab** (list of strings) - Optional - Additional vocabulary to use.
- **--additional-vocab-file** (string) - Optional - File containing additional vocabulary.
- **--punctuation-permitted-marks** (list of strings) - Optional - Permitted punctuation marks.
- **--enable-entities** (flag) - Optional - Enable entity recognition.
- **--translation-langs** (list of strings) - Optional - Target languages for translation.
- **--langid-langs** (list of strings) - Optional - Expected languages for language identification.
- **--multichannel** (list of strings) - Optional - Channels to process for multichannel audio.

### Request Example
```bash
speechmatics transcribe --lang en-US --streaming-mode audio.wav
```
```

--------------------------------

### Run Diarization Metrics CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/diarization/README.md

Execute the diarization metrics CLI tool with reference and hypothesis files. Use the -h flag for further guidance.

```bash
sm-metrics diarization <reference file> <hypothesis file>
```

```bash
sm-metrics diarization -h
```

--------------------------------

### Run Unit Tests

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Executes all unit tests for the Speechmatics Python SDK using the provided Makefile. Ensure tests are updated or added for any new changes.

```bash
make unittests
```

--------------------------------

### Run Formatting and Linting

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Executes code formatting and linting checks using the provided Makefile. This ensures code adheres to project standards.

```bash
make format
make lint
```

--------------------------------

### Run All Pre-commit Checks

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Manually runs all configured pre-commit checks across all files in the repository. This is useful for verifying code quality before committing.

```bash
pre-commit run --all-files
```

--------------------------------

### Set CLI Configuration

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Sets configuration values for the local CLI environment, such as authentication tokens or API URLs.

```bash
speechmatics config set [-h] [--auth-token AUTH_TOKEN]
                        [--realtime-url REALTIME_URL] [--batch-url BATCH_URL]
                        [--generate-temp-token] [--profile PROFILE]
```

--------------------------------

### Compute WER and show transcript diff

Source: https://github.com/speechmatics/speechmatics-python/blob/master/asr_metrics/wer/README.md

Use the sm-metrics binary to compute WER and visualize differences between reference and hypothesis transcripts. Ensure files are UTF-8 encoded.

```bash
sm-metrics wer --diff <reference_path> <hypothesis_path>
```

--------------------------------

### config set

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Set config for the local CLI environment.

```APIDOC
## config set

### Description
Set config for the local CLI environment.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--realtime-url** (string) - Optional - URL for the real-time API.
- **--batch-url** (string) - Optional - URL for the batch API.
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.

### Request Example
```bash
speechmatics config set --batch-url https://api.speechmatics.com/v2/
```
```

--------------------------------

### Synchronize with Speechmatics API

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/notification_flow/README.md

Runs the Python cronjob script to synchronize your system with the Speechmatics API. Use this if webhook notifications fail to arrive.

```bash
python cronjob.py
```

--------------------------------

### Real-Time Transcription with WebsocketClient

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Use the WebsocketClient for real-time transcription. Add event handlers for partial and final transcripts. The transcription is run synchronously with a file.

```python
from speechmatics.models import *
import speechmatics

# Change to your own file
PATH_TO_FILE = "tests/data/ch.wav"
LANGUAGE = "en"

# Generate an API key at https://portal.speechmatics.com/manage-access/
API_KEY = ""

# Create a transcription client from config defaults
sm_client = speechmatics.client.WebsocketClient(API_KEY)

sm_client.add_event_handler(
    event_name=ServerMessageType.AddPartialTranscript,
    event_handler=print,
)

sm_client.add_event_handler(
    event_name=ServerMessageType.AddTranscript,
    event_handler=print,
)

conf = TranscriptionConfig(
    language=LANGUAGE, enable_partials=True, max_delay=5, enable_entities=True,
)

print("Starting transcription (type Ctrl-C to stop):")
with open(PATH_TO_FILE, "rb") as fd:
    try:
        sm_client.run_synchronously(fd, conf)
    except KeyboardInterrupt:
        print("\nTranscription stopped.")

```

--------------------------------

### Submit WAV File for Batch ASR

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submits a local WAV audio file for asynchronous batch transcription processing.

```bash
speechmatics batch transcribe --lang en example_audio.wav
```

--------------------------------

### Enable JSON Output for Partials

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Adds the `--print-json` argument to the real-time transcription command to view the raw JSON messages being sent, instead of just the plaintext transcript.

```bash
speechmatics transcribe --url $URL --ssl-mode none --enable-partials --print-json --raw pcm_f32le --sample-rate 44100 -
```

--------------------------------

### Configure Speechmatics CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/notification_flow/README.md

Sets your Speechmatics API authentication token using the CLI. This token is required for API authentication. Alternatively, the token can be set directly in the code.

```bash
speechmatics config set --auth-token {YOUR_AUTH_TOKEN}
```

--------------------------------

### Configure Auth Token for CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Sets an authentication token for CLI commands. Auth tokens are stored in the TOML config file. This command overrides any existing token.

```bash
speechmatics config set --auth-token $AUTH_TOKEN
```

--------------------------------

### Batch Transcription with Custom Runtime URL

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submits a WAV file for batch ASR processing, specifying a custom runtime URL for enterprise SaaS or on-premises deployments.

```bash
# Point URL to a custom runtime (in this case, the trial runtime)
URL=https://trial.asr.api.speechmatics.com/v2/

speechmatics batch transcribe --url $URL example_audio.wav
```

--------------------------------

### Speechmatics CLI Main Usage

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

This is the primary usage command for the Speechmatics CLI tool. It shows the available top-level commands and global options.

```bash
speechmatics [-h] [-v] [--debug] [--ctrl CTRL] {rt,batch,transcribe,config} ...
```

--------------------------------

### Submit Batch Job with Summarization

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job that includes summarization. The output format is set to json-v2.

```bash
speechmatics batch transcribe --summarize --output-format json-v2 example_audio.wav
```

--------------------------------

### List Batch Jobs

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieves a list of the last 100 jobs submitted within the last 7 days for the SaaS or all jobs for the batch appliance.

```bash
speechmatics batch list-jobs [-h] [--url URL] [--auth-token AUTH_TOKEN]
                             [--ssl-mode {regular,insecure,none}]
                             [--generate-temp-token] [--profile PROFILE]
```

--------------------------------

### Pipe YouTube Audio to Speechmatics CLI

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/transcribe_from_youtube/README.md

An alternative method to transcribe YouTube videos by piping the audio stream through streamlink and ffmpeg to the main Speechmatics CLI transcription tool.

```bash
streamlink "https://www.youtube.com/watch?v=9Auq9mYxFEE" best --loglevel none --output - |\
ffmpeg -loglevel quiet -i pipe: -vn -f wav - |\
speechmatics rt transcribe -
```

--------------------------------

### Submit Batch Job with Topic Detection

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job that includes topic detection. The output format is set to json-v2.

```bash
speechmatics batch transcribe --detect-topics --output-format json-v2 example_audio.wav
```

--------------------------------

### Pipe Microphone Audio to Transcriber (macOS)

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Captures audio from the default microphone using ffmpeg and pipes it to the Speechmatics CLI for real-time transcription. Adjust sample rate and device if necessary.

```bash
ffmpeg -loglevel quiet -f avfoundation -i ":default" -f f32le -acodec pcm_f32le -ar 44100 - \
    | speechmatics transcribe --url $URL --ssl-mode none --raw pcm_f32le --sample-rate 44100 -
```

--------------------------------

### Submit Job with Custom Transcription Config File

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job using a JSON configuration file instead of command-line options. The config file path is specified using --config-file.

```bash
speechmatics transcribe --config-file transcription_config.json example_audio.wav
```

--------------------------------

### Use Auth Token with Specific Command

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Overrides the stored auth token for a single CLI command. This is useful for temporary or specific authentication needs.

```bash
speechmatics transcribe --auth-token $AUTH_TOKEN example_audio.wav
```

--------------------------------

### Run Client to Submit Jobs

Source: https://github.com/speechmatics/speechmatics-python/blob/master/examples/notification_flow/README.md

Executes the Python client script to submit jobs to the Speechmatics API. This script will trigger the notification process upon job completion.

```bash
python client.py
```

--------------------------------

### list-jobs

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieve JSON of the last 100 jobs submitted within the last 7 days for the SaaS or all of the jobs for the batch appliance.

```APIDOC
## list-jobs

### Description
Retrieve json of last 100 jobs submitted within the last 7 days for the SaaS or all of the jobs for the batch appliance.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--url** (string) - Optional - URL for the Speechmatics API.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--ssl-mode** (string) - Optional - SSL mode for the connection (regular, insecure, none).
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
```

--------------------------------

### Submit File for Asynchronous Batch Processing

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submits a file for asynchronous batch transcription processing. The CLI will return a job ID that can be used to check the status.

```bash
speechmatics batch submit example_audio.wav
```

--------------------------------

### Verbose Real-time Transcription Output

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Displays detailed messages exchanged over the WebSocket connection during real-time transcription. Useful for debugging.

```bash
speechmatics -v transcribe --url $URL --ssl-mode none example_audio.wav
```

--------------------------------

### Submit Batch Job with Sentiment Analysis

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job that includes sentiment analysis. The output format is set to json-v2.

```bash
speechmatics batch transcribe --sentiment-analysis --output-format json-v2 example_audio.wav
```

--------------------------------

### Real-time Transcription

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Initiates a real-time transcription. Supports various options for streaming, partial results, diarization, and audio configuration. RETAINED FOR LEGACY COMPATIBILITY.

```bash
speechmatics transcribe [-h] [--streaming-mode] [--enable-partials]
                        [--enable-transcription-partials]
                        [--enable-translation-partials]
                        [--punctuation-sensitivity PUNCTUATION_SENSITIVITY]
                        [--speaker-diarization-max-speakers SPEAKER_DIARIZATION_MAX_SPEAKERS]
                        [--speaker-diarization-sensitivity SPEAKER_DIARIZATION_SENSITIVITY]
                        [--speaker-diarization-prefer-current-speaker]
                        [--max-delay MAX_DELAY]
                        [--max-delay-mode {fixed,flexible}] [--raw ENCODING]
                        [--sample-rate SAMPLE_RATE] [--chunk-size CHUNK_SIZE]
                        [--buffer-size BUFFER_SIZE] [--print-json]
                        [--diarization {none,speaker,channel}]
                        [--audio-events] [--event-types EVENT_TYPES]
                        [--extra-headers KEY=VALUE [KEY=VALUE ...]]
                        [--url URL] [--auth-token AUTH_TOKEN]
                        [--ssl-mode {regular,insecure,none}]
                        [--generate-temp-token] [--profile PROFILE]
                        [--config-file CONFIG_FILE] [--lang LANGUAGE]
                        [--volume-threshold VOLUME_THRESHOLD]
                        [--end-of-utterance-silence-trigger END_OF_UTTERANCE_SILENCE_TRIGGER]
                        [--remove-disfluencies]
                        [--replacement-words [REPLACEMENT_WORDS ...]]
                        [--replacement-words-file REPLACEMENT_WORDS_FILE]
                        [--operating-point {standard,enhanced}]
                        [--domain DOMAIN] [--output-locale LOCALE]
                        [--additional-vocab [ADDITIONAL_VOCAB ...]]
                        [--additional-vocab-file VOCAB_FILEPATH]
                        [--punctuation-permitted-marks PUNCTUATION_PERMITTED_MARKS]
                        [--enable-entities]
                        [--translation-langs TRANSLATION_TARGET_LANGUAGES]
                        [--langid-langs LANGID_EXPECTED_LANGUAGES]
                        [--multichannel CHANNELS]
                        FILEPATHS [FILEPATHS ...]
```

--------------------------------

### Batch Transcription with BatchClient

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a file for batch transcription using BatchClient. The job is polled for completion. Error handling for common HTTP status codes is included.

```python
from speechmatics.models import ConnectionSettings, BatchTranscriptionConfig
from speechmatics.batch_client import BatchClient
from httpx import HTTPStatusError

API_KEY = "YOUR_API_KEY"
PATH_TO_FILE = "example.wav"
LANGUAGE = "en"

# Open the client using a context manager
with BatchClient(API_KEY) as client:
    try:
        job_id = client.submit_job(PATH_TO_FILE, BatchTranscriptionConfig(LANGUAGE))
        print(f'job {job_id} submitted successfully, waiting for transcript')

        # Note that in production, you should set up notifications instead of polling.
        # Notifications are described here: https://docs.speechmatics.com/features-other/notifications
        transcript = client.wait_for_completion(job_id, transcription_format='txt')
        # To see the full output, try setting transcription_format='json-v2'.
        print(transcript)
    except HTTPStatusError as e:
        if e.response.status_code == 401:
            print('Invalid API key - Check your API_KEY at the top of the code!')
        elif e.response.status_code == 400:
            print(e.response.json()['detail'])
        else:
            raise e

```

--------------------------------

### Speechmatics Real-time Transcribe Command Usage

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

This command initiates real-time transcription of audio files or streams, outputting results to the console. It includes numerous options for customization.

```bash
speechmatics rt transcribe [-h] [--streaming-mode] [--enable-partials] [--enable-transcription-partials] [--enable-translation-partials] [--punctuation-sensitivity PUNCTUATION_SENSITIVITY] [--speaker-diarization-max-speakers SPEAKER_DIARIZATION_MAX_SPEAKERS] [--speaker-diarization-sensitivity SPEAKER_DIARIZATION_SENSITIVITY] [--speaker-diarization-prefer-current-speaker] [--max-delay MAX_DELAY] [--max-delay-mode {fixed,flexible}] [--raw ENCODING] [--sample-rate SAMPLE_RATE] [--chunk-size CHUNK_SIZE] [--buffer-size BUFFER_SIZE] [--print-json] [--diarization {none,speaker,channel}] [--audio-events] [--event-types EVENT_TYPES] [--extra-headers KEY=VALUE [KEY=VALUE ...]] [--url URL] [--auth-token AUTH_TOKEN] [--ssl-mode {regular,insecure,none}] [--generate-temp-token] [--profile PROFILE] [--config-file CONFIG_FILE] [--lang LANGUAGE] [--volume-threshold VOLUME_THRESHOLD] [--end-of-utterance-silence-trigger END_OF_UTTERANCE_SILENCE_TRIGGER] [--remove-disfluencies] [--replacement-words [REPLACEMENT_WORDS ...]] [--replacement-words-file REPLACEMENT_WORDS_FILE] [--operating-point {standard,enhanced}] [--domain DOMAIN] [--output-locale LOCALE] [--additional-vocab [ADDITIONAL_VOCAB ...]] [--additional-vocab-file VOCAB_FILEPATH] [--punctuation-permitted-marks PUNCTUATION_PERMITTED_MARKS] [--enable-entities] [--translation-langs TRANSLATION_TARGET_LANGUAGES] [--langid-langs LANGID_EXPECTED_LANGUAGES] [--multichannel CHANNELS] FILEPATHS [FILEPATHS ...]
```

--------------------------------

### Speechmatics Batch Submit Command

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Use this command to submit one or more audio files for transcription in batch mode. This command allows for extensive configuration of the transcription process.

```bash
speechmatics batch submit [-h] [--url URL] [--auth-token AUTH_TOKEN]
                          [--ssl-mode {regular,insecure,none}]
                          [--generate-temp-token] [--profile PROFILE]
                          [--config-file CONFIG_FILE] [--lang LANGUAGE]
                          [--volume-threshold VOLUME_THRESHOLD]
                          [--end-of-utterance-silence-trigger END_OF_UTTERANCE_SILENCE_TRIGGER]
                          [--remove-disfluencies]
                          [--replacement-words [REPLACEMENT_WORDS ...]]
                          [--replacement-words-file REPLACEMENT_WORDS_FILE]
                          [--operating-point {standard,enhanced}]
                          [--domain DOMAIN] [--output-locale LOCALE]
                          [--additional-vocab [ADDITIONAL_VOCAB ...]]
                          [--additional-vocab-file VOCAB_FILEPATH]
                          [--punctuation-permitted-marks PUNCTUATION_PERMITTED_MARKS]
                          [--enable-entities]
                          [--translation-langs TRANSLATION_TARGET_LANGUAGES]
                          [--langid-langs LANGID_EXPECTED_LANGUAGES]
                          [--multichannel CHANNELS]
                          [--output-format {txt,json,json-v2,srt}]
                          [--speaker-diarization-sensitivity SPEAKER_DIARIZATION_SENSITIVITY]
                          [--speaker-diarization-prefer-current-speaker]
                          [--diarization {none,speaker,channel}]
                          [--channel-diarization-labels CHANNEL_DIARIZATION_LABELS [CHANNEL_DIARIZATION_LABELS ...]]
                          [--summarize]
                          [--summary-content-type {informative,conversational,auto}]
                          [--summary-length {brief,detailed}]
                          [--summary-type {paragraphs,bullets}]
                          [--sentiment-analysis] [--detect-topics]
                          [--topics TOPICS] [--detect-chapters]
                          FILEPATHS [FILEPATHS ...]
```

--------------------------------

### Submit Batch Job with Auto Language ID

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job with automatic language identification. Use --langid-langs to specify expected languages. The job may be rejected if confidence is low.

```bash
speechmatics batch transcribe --language auto --langid-langs en,es example_audio.wav
```

--------------------------------

### Speechmatics Real-time (rt) Sub-command Usage

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

This command is used for real-time audio processing. It specifies the 'rt' mode and lists its available sub-commands.

```bash
speechmatics rt [-h] {transcribe} ...
```

--------------------------------

### Transcribe Piped Audio Input

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Processes audio data piped from standard input to the CLI for transcription. Requires the audio data to be in a format the transcriber can process.

```bash
cat example_audio.wav | speechmatics transcribe --url $URL --ssl-mode none -
```

--------------------------------

### Submit Batch Job with Auto Chapters

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job that includes automatic chapter detection. The output format is set to json-v2.

```bash
speechmatics batch transcribe --detect-chapters --output-format json-v2 example_audio.wav
```

--------------------------------

### Speechmatics Batch Sub-command Usage

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

This command group is used for batch processing of audio files. It lists the available commands for managing batch jobs.

```bash
speechmatics batch [-h] {transcribe,submit,list-jobs,get-results,delete,job-status} ...
```

--------------------------------

### Submit Batch Job with Translation

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Submit a transcription job with translation to specified languages. Output format can be set to json-v2. Translation support is available in asynchronous mode.

```bash
speechmatics batch transcribe --translation-langs de,es --output-format json-v2 example_audio.wav
```

--------------------------------

### Retrieve Speechmatics Batch Job Results

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Fetch the transcription results for a completed batch job. Requires the job ID.

```bash
# $JOB_ID is from the submit command output
speechmatics batch get-results --job-id $JOB_ID
```

--------------------------------

### Unset CLI Configuration

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Removes specified configuration values from the CLI config file. Can unset authentication tokens or API URLs.

```bash
speechmatics config unset [-h] [--auth-token] [--generate-temp-token]
                          [--profile PROFILE] [--realtime-url] [--batch-url]
```

--------------------------------

### Speechmatics Batch Transcribe Command

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Use this command to transcribe one or more audio files in batch mode and wait for the results. It supports numerous options for language, output format, diarization, and more.

```bash
speechmatics batch transcribe [-h] [--url URL] [--auth-token AUTH_TOKEN]
                              [--ssl-mode {regular,insecure,none}] 
                              [--generate-temp-token] [--profile PROFILE]
                              [--config-file CONFIG_FILE] [--lang LANGUAGE]
                              [--volume-threshold VOLUME_THRESHOLD]
                              [--end-of-utterance-silence-trigger END_OF_UTTERANCE_SILENCE_TRIGGER]
                              [--remove-disfluencies]
                              [--replacement-words [REPLACEMENT_WORDS ...]]
                              [--replacement-words-file REPLACEMENT_WORDS_FILE]
                              [--operating-point {standard,enhanced}]
                              [--domain DOMAIN] [--output-locale LOCALE]
                              [--additional-vocab [ADDITIONAL_VOCAB ...]]
                              [--additional-vocab-file VOCAB_FILEPATH]
                              [--punctuation-permitted-marks PUNCTUATION_PERMITTED_MARKS]
                              [--enable-entities]
                              [--translation-langs TRANSLATION_TARGET_LANGUAGES]
                              [--langid-langs LANGID_EXPECTED_LANGUAGES]
                              [--multichannel CHANNELS]
                              [--output-format {txt,json,json-v2,srt}]
                              [--speaker-diarization-sensitivity SPEAKER_DIARIZATION_SENSITIVITY]
                              [--speaker-diarization-prefer-current-speaker]
                              [--diarization {none,speaker,channel}]
                              [--channel-diarization-labels CHANNEL_DIARIZATION_LABELS [CHANNEL_DIARIZATION_LABELS ...]]
                              [--summarize]
                              [--summary-content-type {informative,conversational,auto}]
                              [--summary-length {brief,detailed}]
                              [--summary-type {paragraphs,bullets}]
                              [--sentiment-analysis] [--detect-topics]
                              [--topics TOPICS] [--detect-chapters]
                              [--audio-events] [--event-types EVENT_TYPES]
                              FILEPATHS [FILEPATHS ...]
```

--------------------------------

### get-results

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieve results of a transcription job.

```APIDOC
## get-results

### Description
Retrieve results of a transcription job.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--url** (string) - Optional - URL for the Speechmatics API.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--ssl-mode** (string) - Optional - SSL mode for the connection (regular, insecure, none).
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
- **--output-format** (string) - Optional - Output format for the results (txt, json, json-v2, srt).
- **--job-id** (string) - Required - The ID of the job to retrieve results for.

### Request Example
```bash
speechmatics batch get-results --job-id YOUR_JOB_ID --output-format json
```
```

--------------------------------

### Run Specific Pytest Test

Source: https://github.com/speechmatics/speechmatics-python/blob/master/CONTRIBUTING.md

Targets and runs a specific unit test function using pytest. This is useful for debugging or focusing on a particular test case.

```bash
pytest -v tests/test_models.py::test_notification_config
```

--------------------------------

### config unset

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Remove specified config values from the CLI config file.

```APIDOC
## config unset

### Description
Remove specified config values from the CLI config file.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--auth-token** (flag) - Optional - Unset the auth-token config.
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
- **--realtime-url** (flag) - Optional - Unset the realtime-url config.
- **--batch-url** (flag) - Optional - Unset the batch-url config.

### Request Example
```bash
speechmatics config unset --batch-url
```
```

--------------------------------

### Remove Auth Token from CLI Config

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Unsets and removes the authentication token from the CLI's TOML configuration file.

```bash
speechmatics config unset --auth-token
```

--------------------------------

### Unset Transcriber URLs from CLI Config

Source: https://github.com/speechmatics/speechmatics-python/blob/master/README.md

Removes the configured real-time and batch transcriber URLs from the CLI's TOML configuration file.

```bash
speechmatics config unset --rt-url --batch-url
```

--------------------------------

### job-status

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Retrieve status of a transcription job.

```APIDOC
## job-status

### Description
Retrieve status of a transcription job.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--url** (string) - Optional - URL for the Speechmatics API.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--ssl-mode** (string) - Optional - SSL mode for the connection (regular, insecure, none).
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
- **--job-id** (string) - Required - The ID of the job to check the status for.

### Request Example
```bash
speechmatics batch job-status --job-id YOUR_JOB_ID
```
```

--------------------------------

### delete

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Delete the results of a transcription job.

```APIDOC
## delete

### Description
Delete the results of a transcription job.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Named Arguments
- **-h** (flag) - Optional - Show help message and exit.
- **--url** (string) - Optional - URL for the Speechmatics API.
- **--auth-token** (string) - Optional - Authentication token for the Speechmatics API.
- **--ssl-mode** (string) - Optional - SSL mode for the connection (regular, insecure, none).
- **--generate-temp-token** (flag) - Optional - Generate a temporary authentication token.
- **--profile** (string) - Optional - Profile to use for authentication.
- **--output-format** (string) - Optional - Output format for the results (txt, json, json-v2, srt).
- **--job-id** (string) - Required - The ID of the job to delete.
- **--force** (flag) - Optional - Force deletion without confirmation.

### Request Example
```bash
speechmatics batch delete --job-id YOUR_JOB_ID --force
```
```

--------------------------------

### Delete Batch Job Results

Source: https://github.com/speechmatics/speechmatics-python/blob/master/sphinx/cli_parser.md

Deletes the results of a transcription job. Requires the job ID and can be forced to bypass confirmation.

```bash
speechmatics batch delete [-h] [--url URL] [--auth-token AUTH_TOKEN]
                          [--ssl-mode {regular,insecure,none}]
                          [--generate-temp-token] [--profile PROFILE]
                          [--output-format {txt,json,json-v2,srt}] --job-id
                          JOB_ID [--force]
```
Tokens:
Raw