whisper-smith

whisper-smith is a small Python CLI/app helper for transcribing audio files with OpenAI speech-to-text models.

Features

• Transcribe local audio files
• CLI-first workflow for quick terminal use
• Output as txt, json, srt, or vtt
• Automatically infer output format from output file extension
• Load environment variables from .env

Run on Google Colab (free GPU)

No local setup needed. Open the notebook directly in Colab and run the full speaker-aligned transcript pipeline on a free T4 GPU:

The notebook covers: install → set API keys → upload audio → run pipeline → download result. Use a GPU runtime for the best diarization performance. The notebook also includes an advanced GPU pipeline for explicitly moving the pyannote model to CUDA.

Requirements

• Python 3.10+
• An OpenAI API key (OPENAI_API_KEY)
• For large-file fallback: either system ffmpeg in PATH, or Python package imageio-ffmpeg
• For optional speaker diarization: a Hugging Face token (HUGGINGFACE_TOKEN) and pyannote.audio

Installation

Option 1: uv (recommended)

uv sync

Option 2: pip

pip install -e .

Optional speaker diarization dependencies

uv sync --extra diarize

or:

pip install -e ".[diarize]"

Configuration

Set your API key in the environment or in a .env file:

export OPENAI_API_KEY="your_api_key_here"
export HUGGINGFACE_TOKEN="your_huggingface_token_here"

Or create .env in project root:

OPENAI_API_KEY=your_api_key_here
HUGGINGFACE_TOKEN=your_huggingface_token_here

CLI Usage Guide

Basic command:

whisper-smith <audio_path>

Show help:

whisper-smith --help

1) Print transcript to terminal (default txt)

whisper-smith data/sample.m4a

2) Save transcript to a file

whisper-smith data/sample.m4a --output data/sample.txt

3) Choose output format explicitly

whisper-smith data/sample.m4a --format json --output data/sample.json

Supported CLI formats: txt, json, srt, vtt

4) Let format be inferred from output extension

whisper-smith data/sample.m4a --output data/sample.srt

5) Overwrite existing file

whisper-smith data/sample.m4a --output data/sample.txt --overwrite

6) Run speaker diarization

whisper-smith data/sample.m4a --diarize --output data/sample.diarization.json

Diarization currently supports JSON output only. Optional speaker hints:

whisper-smith data/sample.m4a --diarize --format json --num-speakers 2

7) Create speaker-aligned transcript JSON

Run the full pipeline from one audio file:

whisper-smith data/sample.m4a --align --output data/sample.aligned.json

This writes the main aligned transcript JSON to data/sample.aligned.json and also writes intermediate artifacts beside it:

data/sample.transcript.json
data/sample.diarization.json

To put the intermediate artifacts in a separate directory:

whisper-smith data/sample.m4a --align --output data/sample.aligned.json --artifacts-dir data/artifacts

8) Convert transcript JSON to CSV

Turn transcript or aligned JSON into a spreadsheet-friendly CSV:

whisper-smith json-to-csv data/sample.aligned.json --output data/sample.csv

The CSV columns are start, end, start_dttm, speaker, and text. Use --initial-datetime to make start_dttm relative to a real recording start time:

whisper-smith json-to-csv data/sample.aligned.json --output data/sample.csv --initial-datetime 2026-06-10T09:00:00

Python Usage

from pathlib import Path
from whisper_smith.transcribe import transcribe_audio
from whisper_smith.exporters import export_transcript

result = transcribe_audio(Path("data/sample.m4a"))
print(result.text)

srt = export_transcript(result, "srt")
Path("data/sample.srt").write_text(srt, encoding="utf-8")

Speaker diarization

from pathlib import Path
from whisper_smith.diarize import diarize_audio

result = diarize_audio(Path("data/sample.m4a"))

for segment in result.segments:
    print(segment.start, segment.end, segment.speaker)

diarize_audio uses HUGGINGFACE_TOKEN from the environment, or accepts hf_token="..." explicitly.

The default local model is pyannote/speaker-diarization-3.1, which is compatible with the Intel macOS dependency set. You may pass a different model explicitly from Python or with --diarization-model when running on a newer platform.

Notes

• If --output is omitted, transcript is printed to stdout.
• If --format is omitted, format is inferred from --output extension when possible.
• If an output file already exists, add --overwrite to replace it.
• Transcription uses a timestamp-capable OpenAI model by default so JSON, SRT, and VTT outputs have segment timestamps.
• For large audio files, whisper-smith automatically splits audio into chunks and merges transcript text.
• If diarization fails with torchaudio missing AudioMetaData, refresh the optional diarization dependencies with uv lock --upgrade-package torch --upgrade-package torchaudio and then uv sync --extra diarize.

Development

Run tests:

pytest