spch is a command-line tool that lets you clone any voice from a short audio sample, transcribe audio and video to text, and synthesize speech that sounds like the original speaker — entirely on your own hardware. No cloud APIs, no subscription fees, no data leaving your machine.

It pairs F5-TTS for high-quality zero-shot voice cloning with faster-whisper for fast transcription, and optionally hooks into Ollama for LLM-powered transcript cleanup.

✨ Features

• Voice Profile Creation — Extract a clean reference voice from any audio or video file (MP3, MP4, WAV, FLAC, M4A, MKV, MOV, and more).
• Zero-Shot Voice Cloning — Synthesize speech in any cloned voice using F5-TTS. No training required — a 5–15 second sample is enough.
• Speech-to-Text — Transcribe audio or video to TXT, SRT, VTT, and JSON — all in a single command.
• Ollama Integration — Optional LLM-powered transcription cleanup that fixes punctuation and removes filler words.
• Atomic Writes — Profiles and outputs are written atomically, so a crash never leaves you with a half-written file.
• Progress Indicators — Rich spinners and tables keep you informed during every long-running operation.
• GPU Acceleration — Automatic CUDA and Apple Silicon (MPS) detection for faster inference when available.

🧠 How It Works

spch operates on a simple three-step model:

   ┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
   │  Audio/Video │────▶│  Voice Profile   │────▶│  Cloned Speech   │
   │  (any file)  │     │  (reference.wav) │     │  (F5-TTS synth)  │
   └─────────────┘     └──────────────────┘     └──────────────────┘
         │                                           ▲
         │              ┌──────────────┐             │
         └─────────────▶│ Transcription │────────────┘
                        │ (faster-      │   (reference text
                        │  whisper)     │    feeds the clone)
                        └──────────────┘

1. Create a voice profile from an audio or video clip — spch extracts a clean reference sample and transcribes what's being said.
2. Transcribe any media file to text in multiple formats.
3. Synthesize new speech in the cloned voice from typed text or a script file.

📋 Requirements

🚀 Getting Started

1. Install ffmpeg

ffmpeg is required for audio and video processing.

# macOS (Homebrew)
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget)
winget install Gyan.FFmpeg

# Windows (Chocolatey)
choco install ffmpeg

Verify it's available:

ffmpeg -version

2. Install spch

Option A — Install as a global tool (recommended for end users):

# With pip
pip install spch

# With uv
uv tool install spch

After installation, the spch command is available everywhere on your system.

⚡ Quick Examples

# Clone a voice from a video, taking the first 10 seconds
spch profile create -n narrator -i intro.mp4 --duration 10

# List your saved voices
spch profile list

# Inspect a profile
spch profile info narrator

# Synthesize an MP3 from inline text
spch speak -p narrator -t "Welcome to the show." --fmt mp3

# Transcribe in Spanish
spch transcribe -i entrevista.mp3 -l es -f srt

# Delete a profile without confirmation prompt
spch profile delete oldvoice --force

📖 Command Overview

For every flag, option, default value, and usage scenario, see the Command Reference ⟶

⚙️ Configuration

All settings are stored in ~/.spch/config.json and loaded on every invocation. Run spch configure to change them interactively. Key settings:

📁 Storage Layout

Everything spch creates lives under ~/.spch/ by default:

~/.spch/
├── config.json                  # Configuration
├── profiles/
│   └── myvoice/
│       ├── profile.json         # Metadata + reference text
│       └── reference.wav        # Reference audio (5–15 s)
└── outputs/
    ├── transcriptions/
    │   └── recording/
    │       ├── recording.txt
    │       ├── recording.srt
    │       └── recording_cleaned.txt   # If Ollama cleanup is enabled
    └── synthesis/
        ├── speech_a1b2c3d4.wav         # Inline --text output
        └── script/                     # --file output (one file per line)
            ├── script_001.wav
            └── script_002.wav

You can change the profiles and outputs directories with spch configure.

🎧 Supported Formats

Input (voice profile creation & transcription):

Output:

🔧 Troubleshooting

# Install: https://ollama.com
ollama serve          # start the server
ollama pull llama3.2  # pull a model

# Wrong — "configure" is not a standalone program
uv run configure

# Correct
uv run spch configure

[tool.uv]
link-mode = "copy"

📚 Documentation

• COMMAND.md — Complete command reference with every flag, option, default, and real-world scenario recipes.

📄 License

MIT — see the LICENSE file for details.

Option B — Run directly from a project clone (for development):

git clone https://github.com/spch-contributors/spch.git
cd spch
uv sync
# Prefix all commands with "uv run", e.g.:
uv run spch --help

3. Configure

Run the interactive setup wizard once before first use:

spch configure

This walks you through choosing storage directories, compute devices (CPU/CUDA/MPS), output formats, Whisper model size, and Ollama settings. You can re-run it any time to change something.

4. Check your system

spch status

This verifies that ffmpeg, F5-TTS, faster-whisper, and PyTorch are installed and reports your active compute device. It also shows your current configuration and how many voice profiles you have.

5. Create your first voice profile

spch profile create --name myvoice -i recording.mp3

spch extracts a clean reference sample (trims to 15 seconds by default), transcribes the reference text, and saves the profile. The first run also downloads the F5-TTS model weights (~1 GB).

6. Synthesize speech in the cloned voice

# From inline text
spch speak -p myvoice -t "Hello, this is my cloned voice speaking!"

# From a script file (one utterance per line)
spch speak -p myvoice -F script.txt

7. Transcribe audio or video

# Transcribe to SRT + TXT
spch transcribe -i meeting.mp4 -f srt,txt

# Transcribe to all formats, skip Ollama cleanup
spch transcribe -i podcast.mp3 -f txt,srt,vtt,json --no-cleanup