stt-utils 0.1.1

A utility library for working with speech-to-text transcriptions.

stt-utils

A utility library for working with word-level speech-to-text timestamps. The main goal is to simplify working with timestamps generated by openai's whisper model with "word" timestamp_granularities.

Features

• Realign word timestamps with the full text
• Merge several transcriptions together
• (Optional dependency) Split long audio into smaller segments by the moments of silence.

Installation

pip install stt-utils

With audio tools support:

pip install "stt-utils[audio]"

Usage

Python API

Align word timestamps from openai whisper

from stt_utils import UnprocessedTranscription, Transcription

transcription = openai_client.audio.transcriptions.create(
    model="whisper-1",
    file=audio_file,
    response_format="verbose_json",
    timestamp_granularities=["word"],
)

unprocessed_transcription = UnprocessedTranscription(**transcription.model_dump())
aligned_transcription = Transcription.from_unprocessed_transcription(unprocessed_transcription)

aligned_transcription.dump_prevew()

Split an audio file in roughly 10 minute segments with splits in moments of silence.

from stt_utils.splitter import split_audio_on_silence
from pydub import AudioSegment

audio = AudioSegment.from_file("example_audio.mp3")

splitted = split_audio_on_silence(audio)

for i, segment in enumerate(splitted):
    segment.export(f"segment_{i}.wav")

Command Line Interface

Split audio files from the command line:

python -m stt_utils.splitter audio.mp3 [OPTIONS]

Options:

• --segment-length FLOAT: Target segment length in seconds (default: 600)
• --segment-delta FLOAT: Allowed deviation from segment length in seconds (default: 30)
• --silence-thresh-delta INT: Silence threshold delta in dB (default: -16)
• --min-silence-len FLOAT: Minimum silence length in seconds (default: 0.5)
• --output-dir PATH: Output directory for split segments (default: current directory)

Example:

python -m stt_utils.splitter audio.mp3 --segment-length 600 --output-dir ./segments

Development

It is recomended to use uv toolset for development.

Testing

There are unittests available in the tests/ directory.

uv run pytest

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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