PAR CLI STT

A streaming speech-to-text library and command-line tool supporting multiple STT providers (ElevenLabs Scribe and Deepgram Nova-3) with typed provider options, a plugin architecture, and flexible output formats (plain text, SRT, VTT, JSON).

Use as a CLI — par-stt recording.wav Use as a library — from par_stt import create_provider

Companion project: par-cli-tts — the text-to-speech counterpart (ElevenLabs, OpenAI, Kokoro, Deepgram, Gemini).

• Features
• Technology Stack
• Prerequisites
• Installation
  • From PyPI
  • From Source
• Configuration
• Usage
• Command Line Options
• Providers
• Diagnostics
• Development
• Troubleshooting
• Contributing
• Publishing
• License
• Author
• Acknowledgments
• Support

• Two launch providers - Deepgram Nova-3 (streaming WebSocket, interim + final chunks) and ElevenLabs Scribe (batch, full transcript with language detection)
• Streaming-first core - Every provider exposes a uniform transcribe_async() surface; batch providers inherit a sync-wrapping default
• Plugin registry - Built-in providers plus third-party discovery via the par_stt.providers entry-point group
• Flexible output - Render transcripts as txt, srt, vtt, or json
• Configuration file - Set defaults in a YAML config file with optional named profiles, or use environment variables
• Typed options - DeepgramOptions / ScribeOptions dataclasses with schema introspection
• Cost estimates - Static per-minute pricing for quick planning
• Retry controls - Per-run or config-file retry/backoff settings for provider calls
• Rich terminal output - Colored output with post-transcription summaries
• Security first - API keys read from config (mode 0o600) or environment, sanitized in debug output
• CLI - Typer + Rich: --capabilities, --dump, --profile, shell completions, and more

• Python 3.11+ - Modern Python with type hints and async support
• ElevenLabs SDK - Official client for Scribe batch transcription
• Deepgram WebSocket - Streaming Nova-3 transcription via the websockets library (no SDK)
• Typer - Modern CLI framework with automatic help generation
• Rich - Terminal formatting and beautiful output
• Pydantic - Data validation and settings management
• Platformdirs - Cross-platform directory management
• PyYAML - Configuration file parsing
• Python-dotenv - Environment variable management
• NumPy / SoundFile - Audio loading and 16 kHz mono resampling

Builds with hatchling; gates with ruff + pyright + pytest.

To install PAR CLI STT, make sure you have Python 3.11+ installed.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

You will also need at least one provider API key:

• An ElevenLabs API key for Scribe (the default provider)
• And/or a Deepgram API key for Nova-3

libsndfile (bundled with the soundfile wheel on most platforms) is required for audio loading.

Install the latest version using uv:

uv tool install par-cli-stt

Or using pip:

pip install par-cli-stt

After installation, you can run the tool directly:

# Transcribe a file (uses the default provider, ElevenLabs Scribe)
par-stt recording.wav

# Show help
par-stt --help

Generate shell completion scripts directly from the installed CLI:

par-stt --completion bash > ~/.local/share/bash-completion/completions/par-stt
par-stt --completion zsh > ~/.zfunc/_par-stt
par-stt --completion fish > ~/.config/fish/completions/par-stt.fish

# Or print shell-specific installation guidance
par-stt --completion-install bash

For development or to get the latest features:

1. Clone the repository:

   git clone https://github.com/paulrobello/par-cli-stt.git
   cd par-cli-stt

2. Install the package dependencies using uv:

   uv sync

3. Run using uv:

   uv run par-stt recording.wav

API keys can be provided through environment variables or the config file. The config file is the recommended store for keys and is created with mode 0o600 (owner-only read/write).

Create a sample config file:

# Create a sample config file (prompts before overwriting if one exists)
par-stt --create-config

# Skip the overwrite prompt with -y / --yes (e.g. for scripted setup)
par-stt --create-config -y

# Edit the config file
$EDITOR ~/Library/Application\ Support/par-stt/config.yaml   # macOS
$EDITOR ~/.config/par-stt/config.yaml                        # Linux

Example configuration file:

# Default provider (elevenlabs, deepgram)
provider: elevenlabs

# Default model
# ElevenLabs Scribe (batch): scribe_v1
# Deepgram Nova-3 (streaming): nova-3
model: scribe_v1

# Default language hint (e.g. 'en', 'en-US'). Omit to let the provider auto-detect.
language: en

# Default output format: txt, srt, vtt, json
output_format: txt

# Default output directory for transcripts (omitted = current directory)
# output_dir: ~/Documents/transcripts

# API keys (optional - can also be set via environment variables)
elevenlabs_api_key: your-elevenlabs-api-key-here
deepgram_api_key: your-deepgram-api-key-here

# Named profiles override the base settings above when selected with --profile NAME.
profiles:
  meetings:
    provider: deepgram
    language: en
    diarize: true
  interviews:
    provider: elevenlabs
    diarize: true

If you already have an ElevenLabs key in par-tts's config, copy the same value here — the field name is identical.

Precedence: CLI flags > config file > environment variables.

If installed from PyPI:

# Transcribe with the default provider (ElevenLabs Scribe)
par-stt recording.wav

# Use Deepgram Nova-3 streaming instead
par-stt recording.wav --provider deepgram

# Write an SRT subtitle file
par-stt meeting.wav --provider deepgram --format srt --output meeting.srt

# Use a profile and a language hint
par-stt interview.mp3 --profile interviews --language en

# Label distinct speakers
par-stt panel.wav --provider deepgram --diarize

# Inspect providers without making a network call
par-stt --capabilities
par-stt --list-providers
par-stt --dump

If running from source, prefix commands with uv run:

uv run par-stt recording.wav
uv run par-stt recording.wav --provider deepgram

PAR STT can be used as a Python library in your own projects:

import par_stt

print(par_stt.__version__)
print(par_stt.list_providers())  # ['deepgram', 'elevenlabs']

# Sync batch transcription (returns a Transcript)
provider = par_stt.create_provider("elevenlabs", api_key=os.environ["ELEVENLABS_API_KEY"])
pcm = par_stt.read_audio("recording.wav")          # -> 16 kHz mono int16 PCM bytes
transcript = provider.transcribe(pcm, language="en")
print(transcript.text)
print(transcript.detected_language)

Deepgram exposes native async streaming (interim + final chunks):

import asyncio

provider = par_stt.create_provider("deepgram", api_key=os.environ["DEEPGRAM_API_KEY"])
pcm = par_stt.read_audio("recording.wav")

async def main() -> None:
    async for chunk in provider.transcribe_async(pcm):
        print(("FINAL " if chunk.is_final else "partial ") + chunk.text)

asyncio.run(main())

Render and write transcripts in any supported format:

par_stt.write_transcript(transcript, "srt", "out.srt")
par_stt.write_transcript(transcript, "json", "out.json")

The TranscriptionPipeline keeps a provider instance plus defaults for repeated use:

from par_stt import TranscriptionPipeline

pipeline = TranscriptionPipeline.from_provider_name(
    "elevenlabs", api_key=os.environ["ELEVENLABS_API_KEY"], language="en"
)
transcript = pipeline.transcribe_file("recording.wav")

Providers are discovered through plugin descriptors. The bundled providers are registered as built-in plugins, and third-party packages can expose additional providers with the Python entry point group par_stt.providers.

A plugin entry point may load one of:

• a par_stt.providers.ProviderPlugin object
• a zero-argument factory returning ProviderPlugin
• an SttProvider subclass with metadata attributes such as plugin_name, plugin_description, plugin_capabilities, plugin_default_model, and plugin_requires_api_key

Example third-party pyproject.toml:

[project.entry-points."par_stt.providers"]
my-provider = "my_package.stt:provider_plugin"

Use par-stt --capabilities to see built-in and installed plugin capabilities without initializing providers or requiring API keys.

• Model: scribe_v1 (default)
• Mode: Batch — accepts a complete audio file and returns the full transcript with detected language and word timing
• Features: Language auto-detection, speaker diarization, audio-event tagging
• Input: Container files (wav, mp3, m4a, ogg, flac, webm) are auto-detected; raw 16 kHz mono int16 PCM is reported as pcm_s16le_16 automatically (this is what read_audio emits)
• Output Formats: txt, srt, vtt, json
• Streaming: No (batch only); transcribe_async() yields the finalized transcript via the sync-wrapping default
• API key: elevenlabs_api_key in config, or ELEVENLABS_API_KEY env var
• Cost: ~$0.0065/min (approximate; verify against current ElevenLabs pricing)

• Model: nova-3 (default)
• Mode: Streaming over WebSocket — emits interim partials and finalized chunks as audio is processed
• Features: Language auto-detection, smart format, punctuation, profanity filter, speaker diarization, filler words
• Input: 16 kHz mono Linear16 PCM streamed to Deepgram (the library resamples and downmixes for you via read_audio)
• Output Formats: txt, srt, vtt, json
• Streaming: Yes (native transcribe_async())
• API key: deepgram_api_key in config, or DEEPGRAM_API_KEY / DG_API_KEY env var. Get a key at https://console.deepgram.com.
• Cost: ~$0.0043/min (= $4,300 per million minutes)

Offline environment checks are available to library consumers and the CLI — no network access required:

from par_stt import collect_diagnostics

for check in collect_diagnostics():
    print(check.name, check.ok, check.detail)

Checks cover provider API-key environment variables, the config file, the soundfile/libsndfile audio backend, and the optional ffmpeg binary.

# Clone repository
git clone https://github.com/paulrobello/par-cli-stt.git
cd par-cli-stt

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run formatting, linting, and type checks
make checkall

# Format, lint, and type check
make checkall

# Individual commands
make format      # Format with ruff
make lint        # Lint with ruff
make typecheck   # Type check with pyright

# Build and package
make package     # Build distribution packages
make clean       # Clean build artifacts

1. API Key Not Found

   • Ensure ELEVENLABS_API_KEY and/or DEEPGRAM_API_KEY is set, or add the key to the config file under elevenlabs_api_key: / deepgram_api_key:
   • Verify environment variable names match exactly (DG_API_KEY is also accepted for Deepgram)

2. "File is corrupted" / invalid_audio from Scribe (library use)

   • Scribe needs to know how to decode the bytes. The CLI handles this automatically; when calling the library with raw PCM, pass file_format="pcm_s16le_16" or let the provider sniff it from container magic bytes.

3. m4a / webm files fail to decode

   • The soundfile (libsndfile) backend does not read m4a/webm containers. Convert to wav, mp3, flac, or ogg first (e.g. ffmpeg -i in.m4a -ar 16000 -ac 1 out.wav).

4. Configuration File Issues

   • Run --create-config to generate a sample config
   • Check file location: ~/Library/Application Support/par-stt/config.yaml (macOS) or ~/.config/par-stt/config.yaml (Linux)
   • Verify YAML syntax (use spaces, not tabs)
   • CLI arguments override config file settings

5. Streaming errors (Deepgram)

   • Verify network connectivity and that DEEPGRAM_API_KEY is valid
   • Use --debug to inspect the WebSocket lifecycle

Enable debug mode for detailed information:

# Show debug information during execution
par-stt recording.wav -d

# Dump resolved configuration without transcribing
par-stt --dump

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and checks (make checkall)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

• Use type hints for all function parameters and returns
• Follow Google-style docstrings
• Ensure all tests pass before submitting a PR
• Update documentation for new features
• Keep commits atomic and well-described

Releases use GitHub Actions Trusted Publishing (OIDC) — there is no API token on disk, and no push/tag auto-trigger. Releases are a manual workflow dispatch.

Before the first release, register the project as a Trusted Publisher on both indexes:

1. On PyPI (https://pypi.org/manage/project/par-cli-stt/publishing/), add a Trusted Publisher pointing at:
   • PyPI project: par-cli-stt
   • Owner: paulrobello
   • Repository: paulrobello/par-cli-stt
   • Workflow filename: publish.yml
   • Environment name: pypi
2. Repeat on TestPyPI (https://test.pypi.org/manage/project/par-cli-stt/publishing/) with environment name testpypi.
3. In the GitHub repo, create the pypi and testpypi environments (Settings → Environments).

# 1. Bump the version in par_stt/__init__.py and commit.
# 2. Local sanity build:
make checkall && make package

# 3. Test publish (manual workflow dispatch on GitHub, or locally):
make test-publish   # uploads to TestPyPI; verify install from https://test.pypi.org

# 4. Production publish (manual workflow dispatch, or locally):
make publish        # uploads to PyPI

The GitHub workflow (.github/workflows/publish.yml) is workflow_dispatch-only with inputs for the publish target (testpypi | pypi | both), an optional GitHub Release, and a skip-tests toggle. It uses pypa/gh-action-pypi-publish@release/v1 with id-token: write (no API token secret).

This project is licensed under the MIT License - see the LICENSE file for details.

Paul Robello Email: probello@gmail.com GitHub: @paulrobello

• ElevenLabs for the Scribe speech-to-text API
• Deepgram for the Nova-3 streaming API
• Typer for the elegant CLI framework
• Rich for beautiful terminal formatting

If you find this tool useful, consider:

• Starring the repository
• Reporting bugs or requesting features
• Improving documentation
• Buying me a coffee