Metadata-Version: 2.4
Name: heathen-tts
Version: 0.1.0
Summary: Offline, modular Text-to-Speech with distinctive voice synthesis for local LLMs
Author: HeathenS
License: Apache-2.0
Project-URL: Homepage, https://github.com/IllTemperedMutatedSeaBass/HeathenS_Talkings
Project-URL: Documentation, https://github.com/IllTemperedMutatedSeaBass/HeathenS_Talkings/blob/main/docs
Project-URL: Repository, https://github.com/IllTemperedMutatedSeaBass/HeathenS_Talkings
Project-URL: Issues, https://github.com/IllTemperedMutatedSeaBass/HeathenS_Talkings/issues
Keywords: tts,speech-synthesis,voice-cloning,stt,offline,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyttsx3>=2.99
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: librosa>=0.10.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: structlog>=23.0.0
Provides-Extra: tts
Requires-Dist: soundfile>=0.12.0; extra == "tts"
Provides-Extra: stt
Requires-Dist: faster-whisper>=1.0.0; extra == "stt"
Requires-Dist: pyaudio>=0.2.13; extra == "stt"
Provides-Extra: voice-cloning
Provides-Extra: streaming
Requires-Dist: fastapi>=0.100.0; extra == "streaming"
Requires-Dist: uvicorn>=0.23.0; extra == "streaming"
Requires-Dist: python-multipart>=0.0.6; extra == "streaming"
Provides-Extra: jester
Requires-Dist: httpx>=0.24.0; extra == "jester"
Provides-Extra: cli
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Provides-Extra: full
Requires-Dist: heathen-tts[cli,jester,streaming,stt,tts,voice-cloning]; extra == "full"

# HeathenS_Talkings

> **Offline, modular Text-to-Speech with distinctive voice synthesis**

A standalone Python toolkit for low-latency speech synthesis featuring voice cloning, distinctive voice character (e.g., Stephen Hawking's robotic prosody), and real-time streaming. Designed for local LLM integration, accessibility tools, and creative AI applications.

## Features

- 🎙️ **Voice Cloning** — adapt TTS models to sound like specific speakers (5–10 min audio)
- ⚡ **Low Latency** — streaming synthesis for real-time conversation (~30ms/character)
- 📡 **Streaming Output** — SSE-compatible audio streaming for web/app integration
- 🔇 **Offline Inference** — 100% local, no cloud dependencies, no API keys
- 🎛️ **Modular Design** — use just TTS, just STT, or the full pipeline
- 🛠️ **CLI + Python API** — simple CLI commands or integrate via Python
- 🎯 **Distinctive Voices** — built for character synthesis (not just naturalness)

## Quick Start

```bash
# Install
pip install heathen-tts

# Synthesize text to speech
hts tts "Hello, this is Stephen Hawking"

# Transcribe audio to text
hts stt audio.wav

# Real-time listen & respond (with local LLM or manual input)
hts listen

# Train a custom voice from samples
hts clone --voice-name mycustom --samples ./my_audio_samples/
```

See [Getting Started](docs/getting_started.md) for details.

## Architecture

This project is built as **5 independent modules**:

1. **TTS Engine** — convert text to audio (Glow-TTS, XTTS v2, Piper)
2. **STT Engine** — convert audio to text (Faster-Whisper, Wav2Vec)
3. **Voice Cloning** — fine-tune models or adapt speakers
4. **Streaming** — real-time audio output and pipelining
5. **CLI & Integrations** — user interface and optional bridges to larger systems

Each module is independently useful; together they form a complete I/O pipeline. See [ARCHITECTURE.md](ARCHITECTURE.md) for design details.

## Use Cases

- 🤖 **Personal Assistants** — add a voice to local LLMs (works with Ollama, llama.cpp, vLLM)
- 🎬 **Voice Synthesis** — create character voices for media or storytelling
- ♿ **Accessibility** — generate audio for text in distinctive or preferred voices
- 🔬 **Research** — experiment with TTS model behavior and adaptation
- 🎮 **Games & Creative Tools** — real-time voice generation for NPCs or interactive media

## Installation

```bash
# Basic TTS only
pip install heathen-tts[tts]

# TTS + STT
pip install heathen-tts[tts,stt]

# Full suite (TTS, STT, voice cloning, streaming)
pip install heathen-tts[full]

# Development
git clone https://github.com/IllTemperedMutatedSeaBass/HeathenS_Talkings
cd HeathenS_Talkings
pip install -e .[full]
```

## Examples

See `/examples` for complete working examples:

- `basic_tts.py` — simple text-to-speech
- `streaming_tts.py` — real-time streaming audio
- `voice_cloning.py` — train a custom voice
- `stt_demo.py` — speech-to-text
- `jester_integration.py` — use with JesterAI (when ready)

## Documentation

- [Getting Started](docs/getting_started.md)
- [Architecture](ARCHITECTURE.md)
- [API Reference](docs/api_reference.md)
- [Model Comparison](docs/model_comparison.md)
- [Voice Cloning Guide](docs/voice_cloning_guide.md)
- [Integration Guide](docs/integration_guide.md)

## Integration with JesterAI

HeathenS_Talkings can optionally integrate as the C4 (TTS) component in JesterAI's distributed meeting intelligence system. This is **not** required — the project is fully standalone. When JesterAI resumes, adapters will be available. See [integration_guide.md](docs/integration_guide.md).

## Development

- Python 3.10+
- torch (CPU or CUDA)
- librosa, scipy, numpy
- Optional: Ollama (for local LLM text source)

**Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and guidelines.

## License

MIT / Apache 2.0 (to be decided)

## Related Projects

- [Glow-TTS](https://github.com/jaywalnut310/glow-tts) — fast, deterministic TTS
- [XTTS v2](https://github.com/coqui-ai/TTS) — voice cloning and synthesis
- [Faster-Whisper](https://github.com/guillaumekln/faster-whisper) — fast speech-to-text
- [Silero VAD](https://github.com/snakers4/silero-vad) — voice activity detection
- [Piper TTS](https://github.com/rhasspy/piper) — lightweight TTS

---

**Status:** Phase 1 (TTS baseline) under development.
See [ARCHITECTURE.md](ARCHITECTURE.md) for phase timeline.
