livetranscriber

A single-file helper with minimal external dependencies that streams microphone audio to Deepgram for real-time speech-to-text. This is available as a package on PyPI.

Features

Simple API - single LiveTranscriber class.
Configurable - every Deepgram LiveOptions parameter can be overridden via keyword arguments; sensible Nova-3 defaults are provided.
Mandatory callback - forces the calling code to supply a function that will be invoked for every final transcript chunk (empty / interim chunks are ignored).
Output capture - optional output_path writes each final transcript line to disk.
Pause / resume - you may call pause or resume from your callback.
Graceful shutdown - Ctrl-C or stop shuts everything down and releases resources.

Installation

Install the package directly from PyPI using pip:

pip install livetranscriber

Alternatively, if you are working with the source code or a specific requirements file, you can install the dependencies listed in requirements.txt:

deepgram-sdk>=4,<5
numpy>=1.24  # build-time requirement of sounddevice
sounddevice>=0.4

Install with uv (preferred) or plain pip:

uv venv .venv && source .venv/bin/activate
uv pip install -r requirements.txt

or

pip install -r requirements.txt

Python Version:

Python 3.11 is required.

Environment Setup

Export your Deepgram API key (see https://console.deepgram.com). For persistent access, add the following line to your shell profile file (e.g., ~/.zshrc, ~/.bashrc, or ~/.profile) and restart your terminal or source the file:

export DEEPGRAM_API_KEY="dg_…"

Example Usage

Here are examples demonstrating how to use the livetranscriber package.

Minimal Example

A basic example showing the essential setup:

from livetranscriber import LiveTranscriber

def simple_callback(text: str):
    print("NEW >", text)

tr = LiveTranscriber(callback=simple_callback)
tr.run()

Comprehensive Example

A more detailed example demonstrating various features like output to file and pause/resume:

import time
from livetranscriber import LiveTranscriber

def comprehensive_callback(text: str):
    print("Transcript received:", text)

    # Example: Pause transcription if a specific phrase is detected
    if "pause recording" in text.lower():
        print("Status: PAUSING...")
        transcriber.pause()
        print("Status: RECORDING PAUSED. Say 'resume recording' to continue.")

    # Example: Resume transcription if another phrase is detected
    if "resume recording" in text.lower():
        print("Status: RESUMING...")
        transcriber.resume()
        print("Status: RECORDING RESUMED.")

    # Example: Stop transcription if a stop phrase is detected
    if "stop recording" in text.lower():
        print("Status: STOPPING...")
        transcriber.stop()

# Instantiate with various options
output_file = "transcript_output.txt"
transcriber = LiveTranscriber(
    callback=comprehensive_callback,
    output_path=output_file, # Output transcript to a file
    model="nova-3-general", # Specify a model
    language="en-US",     # Specify a language
    punctuate=True,         # Enable punctuation
    smart_format=True       # Enable smart formatting (like numbers)
)

try:
    print(f"Starting transcription. Transcript will also be saved to {output_file}")
    print("Instructions: Press Ctrl+C to stop, or say 'pause recording', 'resume recording', or 'stop recording'.")
    transcriber.run() # Blocks until stop() is called or Ctrl-C is pressed
except KeyboardInterrupt:
    print("\nInterrupted by user. Stopping.")
finally:
    print("Transcription session ended.")

API