Metadata-Version: 2.4
Name: spch
Version: 0.1.0
Summary: Local voice-cloning pipeline using F5-TTS for zero-shot synthesis
Project-URL: Homepage, https://github.com/devcrypted/spch
Project-URL: Documentation, https://github.com/devcrypted/spch/blob/main/COMMAND.md
Project-URL: Repository, https://github.com/devcrypted/spch
Project-URL: Issues, https://github.com/devcrypted/spch/issues
Project-URL: Changelog, https://github.com/devcrypted/spch/releases
Project-URL: PyPI, https://pypi.org/project/spch/
Author: spch contributors
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: f5-tts>=0.5.0
Requires-Dist: faster-whisper>=1.0.3
Requires-Dist: numpy>=1.24.0
Requires-Dist: ollama>=0.3.3
Requires-Dist: pydantic>=2.9.0
Requires-Dist: rich>=13.9.0
Requires-Dist: soundfile>=0.12.0
Requires-Dist: typer>=0.12.5
Description-Content-Type: text/markdown

<div align="center">

# spch

**Local voice-cloning pipeline using F5-TTS for zero-shot synthesis.**

Zero-shot voice cloning, speech-to-text, and text-to-speech — all running locally on your machine.

[![PyPI version](https://img.shields.io/pypi/v/spch.svg)](https://pypi.org/project/spch/)
[![Python](https://img.shields.io/pypi/pyversions/spch.svg)](https://pypi.org/project/spch/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows-blue)](#requirements)

</div>

---

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](https://github.com/SWivid/F5-TTS) for high-quality zero-shot voice cloning with [faster-whisper](https://github.com/SYSTRAN/faster-whisper) for fast transcription, and optionally hooks into [Ollama](https://ollama.com) 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:

```text
   ┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
   │  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

| Requirement       | Required? | Notes                                                             |
| ----------------- | --------- | ----------------------------------------------------------------- |
| **Python ≥ 3.10** | Yes       |                                                                   |
| **ffmpeg**        | Yes       | Used for all audio/video extraction and conversion                |
| **Ollama**        | Optional  | Enables LLM-powered transcription cleanup                         |
| **CUDA GPU**      | Optional  | Speeds up TTS and transcription (falls back to CPU automatically) |

## 🚀 Getting Started

### 1. Install ffmpeg

ffmpeg is required for audio and video processing.

```bash
# 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:

```bash
ffmpeg -version
```

### 2. Install spch

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

```bash
# With pip
pip install spch

# With uv
uv tool install spch
```

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

## ⚡ Quick Examples

```bash
# 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

| Command                      | Description                                                  |
| ---------------------------- | ------------------------------------------------------------ |
| `spch configure`             | Interactive setup wizard (devices, formats, Ollama, storage) |
| `spch status`                | Check dependencies, configuration, and profile count         |
| `spch profile create`        | Create a voice profile from an audio or video file           |
| `spch profile list`          | List all saved voice profiles                                |
| `spch profile info <name>`   | Show detailed information about a profile                    |
| `spch profile delete <name>` | Delete a voice profile                                       |
| `spch transcribe`            | Convert speech (audio/video) to text in multiple formats     |
| `spch speak`                 | Synthesize speech from text using a voice profile            |

> **For every flag, option, default value, and usage scenario, see the [Command Reference ⟶](COMMAND.md)**

## ⚙️ Configuration

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

| Setting               | Default                  | Options                                           |
| --------------------- | ------------------------ | ------------------------------------------------- |
| TTS compute device    | `auto`                   | `auto` · `cuda` · `cpu` · `mps`                   |
| TTS output format     | `wav`                    | `wav` · `mp3` · `flac`                            |
| TTS NFE steps         | `32`                     | Higher = better quality, slower                   |
| Whisper model         | `base`                   | `tiny` · `base` · `small` · `medium` · `large-v3` |
| Whisper device        | `auto`                   | `auto` · `cuda` · `cpu`                           |
| Whisper language      | `en`                     | Any language code, or `auto`                      |
| Transcription outputs | `txt, srt`               | Any of `txt` · `srt` · `vtt` · `json`             |
| Ollama host           | `http://localhost:11434` | Any Ollama server URL                             |
| Ollama text cleanup   | `true`                   | `true` · `false`                                  |

## 📁 Storage Layout

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

```bash
~/.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):**

| Type  | Extensions                                                |
| ----- | --------------------------------------------------------- |
| Audio | `.mp3` `.wav` `.flac` `.m4a` `.aac` `.ogg` `.opus` `.wma` |
| Video | `.mp4` `.mkv` `.avi` `.mov` `.webm` `.flv` `.wmv`         |

**Output:**

| Operation        | Formats                        |
| ---------------- | ------------------------------ |
| Speech synthesis | `wav` · `mp3` · `flac`         |
| Transcription    | `txt` · `srt` · `vtt` · `json` |

## 🔧 Troubleshooting

<details>
<summary><b>ffmpeg is required but not found</b></summary>

Install ffmpeg using the instructions in [Getting Started](#-getting-started), then verify with `ffmpeg -version`. spch needs both `ffmpeg` and `ffprobe` on your PATH.
</details>

<details>
<summary><b>Ollama not running — skipping cleanup</b></summary>

Transcription cleanup is optional. If you want it, install and start Ollama:

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

Then re-run `spch configure` to select the model. If you don't want cleanup, run transcription with `--no-cleanup` or disable it in `spch configure`.
</details>

<details>
<summary><b>Synthesis is slow / using CPU instead of GPU</b></summary>

Run `spch status` to see which device PyTorch is using. If you have an NVIDIA GPU but it shows "CPU", make sure you have CUDA-enabled PyTorch installed. Set the device explicitly with `spch configure` → Compute device → `cuda`.
</details>

<details>
<summary><b>First synthesis takes a long time</b></summary>

The first `spch speak` call downloads the F5-TTS model weights (~1 GB) from Hugging Face. Subsequent calls load the cached model and are much faster.
</details>

<details>
<summary><b>Running with <code>uv run</code> — "Failed to spawn" error</b></summary>

If you installed spch from source and run it through `uv run`, remember that subcommands belong to the `spch` program — not `uv run`:

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

# Correct
uv run spch configure
```

</details>

<details>
<summary><b>uv warning: "Failed to hardlink files"</b></summary>

This happens when the uv cache and your project live on different drives/filesystems. It's harmless, but you can silence it by adding this to your `pyproject.toml`:

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

Or set the environment variable `UV_LINK_MODE=copy`.
</details>

## 📚 Documentation

- **[COMMAND.md](COMMAND.md)** — Complete command reference with every flag, option, default, and real-world scenario recipes.

## 📄 License

MIT — see the [LICENSE](LICENSE) file for details.

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

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
# 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
```
