soniox-transcribe 0.1.0

Generate subtitles from audio/video using Soniox Speech-to-Text API

soniox-transcribe

CLI tool for generating subtitles from audio/video files using the Soniox Speech-to-Text API.

Features

• Subtitle formats: SRT, VTT, TXT
• Video support: Automatically extracts audio from video files via ffmpeg
• Speaker diarization: Speaker labels enabled by default
• 60+ languages: With automatic language identification
• Context support: Custom terms and background text to improve accuracy (up to ~8,000 tokens)

Installation

pip install soniox-transcribe

For video file support, ffmpeg must be installed:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Configuration

Set your Soniox API key as an environment variable:

export SONIOX_API_KEY=<your-api-key>

Get your API key at console.soniox.com.

Alternatively, create a .env file in your working directory:

SONIOX_API_KEY=<your-api-key>

Usage

# Basic transcription (outputs .srt by default)
soniox-transcribe video.mp4

# Specify output file (format inferred from extension)
soniox-transcribe video.mp4 -o video.vtt

# Explicit format
soniox-transcribe audio.wav -f txt

# Transcribe from URL
soniox-transcribe --url https://example.com/audio.mp3

# Disable speaker diarization
soniox-transcribe interview.wav --no-speaker

# Add custom vocabulary
soniox-transcribe lecture.mp3 -t "Transformer" -t "BERT" -t "GPT"

# Provide background text for better accuracy
soniox-transcribe meeting.mp3 --context-text "Discussion about Q4 revenue targets"

# Use a context file
soniox-transcribe meeting.mp3 --context-text-file agenda.txt

Options

Option	Description
-o, --output	Output file path (default: input with .srt extension)
-f, --format	Output format: srt, vtt, txt
-u, --url	Transcribe from a public URL instead of a local file
-l, --language	Language hints (default: zh, en); repeatable
--no-speaker	Disable speaker diarization and labels
--max-chars	Max characters per subtitle line (default: 42)
-m, --model	Soniox model (default: stt-async-v4)
-t, --context-term	Custom terms/vocabulary; repeatable
--context-text	Background text for accuracy improvement
--context-text-file	File containing background text
-c, --context	JSON string with full context configuration
--context-file	JSON file with full context configuration

Supported Formats

Audio: mp3, wav, flac, aac, ogg, m4a, wma

Video: mp4, mkv, avi, mov, webm, flv, wmv, m4v (requires ffmpeg)

License

MIT