speechflow 0.3.4

Async-first TTS (Text-to-Speech) wrapper library for Python

SpeechFlow

A unified async-first Python TTS (Text-to-Speech) library with multiple engine support.

Features

• Multiple TTS Engines: OpenAI, Google Gemini, FishAudio, Kokoro (local), Style-Bert-VITS2 (local)
• Async-First Design: Native async/await API with sync wrappers for convenience
• Streaming Support: Real-time audio streaming for supported engines
• Decoupled Architecture: Engines, player, and writer are independent components
• Optional Dependencies: Core requires only numpy; each engine is installable as an extra

Installation

# Core only (no engines)
uv add speechflow

# Install with specific engine
uv add "speechflow[openai]"

# Install with audio playback
uv add "speechflow[openai,player]"

# Install everything
uv add "speechflow[all]"

Available Extras

Extra	Engine	Type
openai	OpenAI TTS	Cloud
gemini	Google Gemini TTS	Cloud
fishaudio	FishAudio TTS	Cloud
kokoro	Kokoro TTS (includes PyTorch)	Local
stylebert	Style-Bert-VITS2 (includes PyTorch)	Local
player	Audio playback via sounddevice	Utility
all	All of the above	-

Using pip instead of uv

pip install "speechflow[openai]"
pip install "speechflow[openai,player]"
pip install "speechflow[all]"

GPU Support (Kokoro / Style-Bert-VITS2)

Local engines pull PyTorch as a dependency. By default, CPU-only PyTorch is installed. For GPU acceleration, install PyTorch with CUDA before installing speechflow:

# uv
uv add torch torchvision torchaudio --index https://download.pytorch.org/whl/cu121
uv add "speechflow[kokoro]"

# pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install "speechflow[kokoro]"

Replace cu121 with your CUDA version (e.g., cu118, cu124).

Quick Start

Async (Primary API)

import asyncio
from speechflow import OpenAITTSEngine, AudioPlayer, AudioWriter

async def main():
    engine = OpenAITTSEngine(api_key="your-api-key")
    player = AudioPlayer()
    writer = AudioWriter()

    # Generate audio
    audio = await engine.get("Hello, world!")

    # Play audio
    await player.play(audio)

    # Save to file
    await writer.save(audio, "output.wav")

asyncio.run(main())

Sync Wrappers

from speechflow import OpenAITTSEngine, AudioPlayer, AudioWriter

engine = OpenAITTSEngine(api_key="your-api-key")
player = AudioPlayer()
writer = AudioWriter()

audio = engine.get_sync("Hello, world!")
player.play_sync(audio)
writer.save_sync(audio, "output.wav")

Streaming

import asyncio
from speechflow import OpenAITTSEngine, AudioPlayer

async def main():
    engine = OpenAITTSEngine(api_key="your-api-key")
    player = AudioPlayer()

    # Stream and play (returns combined AudioData)
    combined = await player.play_stream(engine.stream("This is a long text that will be streamed..."))

asyncio.run(main())

Streaming notes:

• OpenAI: True streaming with multiple chunks.
• Gemini: Returns complete audio in a single chunk (API limitation).
• FishAudio: True streaming.
• Kokoro / Style-Bert-VITS2: Sentence-by-sentence streaming.

Engine-Specific Features

OpenAI TTS

engine = OpenAITTSEngine(api_key="your-api-key")
audio = await engine.get(
    "Hello",
    voice="alloy",           # ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer
    model="gpt-4o-mini-tts", # tts-1, tts-1-hd
    speed=1.0,
    instructions="Speak in a cheerful tone",
)

# Streaming
async for chunk in engine.stream("Long text..."):
    pass

Google Gemini TTS

engine = GeminiTTSEngine(api_key="your-api-key")
audio = await engine.get(
    "Hello",
    model="gemini-2.5-flash-preview-tts",  # gemini-2.5-pro-preview-tts
    voice="Leda",                           # Puck, Charon, Kore, Fenrir, Aoede, ...
)

FishAudio TTS

engine = FishAudioTTSEngine(api_key="your-api-key")
audio = await engine.get(
    "Hello world",
    model="s1",                  # s1-mini, speech-1.6, speech-1.5, agent-x0
    voice="your-voice-id",
    speed=1.0,                   # Speech speed
    volume=1.0,                  # Volume
)

# Streaming
async for chunk in engine.stream("Streaming text..."):
    pass

Kokoro TTS

# Default: American English
engine = KokoroTTSEngine()
audio = await engine.get(
    "Hello world",
    voice="af_heart",
    speed=1.0,
)

# Japanese (dictionary auto-downloads on first use)
engine = KokoroTTSEngine(lang_code="j")
audio = await engine.get("こんにちは、世界", voice="af_heart")

If Japanese dictionary download fails, run manually: python -m unidic download

Supported languages: American English (a), British English (b), Spanish (e), French (f), Hindi (h), Italian (i), Japanese (j), Brazilian Portuguese (p), Mandarin Chinese (z)

Style-Bert-VITS2

# Pre-trained model (auto-downloads on first use)
engine = StyleBertTTSEngine(model_name="jvnv-F1-jp")
audio = await engine.get(
    "こんにちは、世界",
    style="Happy",       # Neutral, Happy, Sad, Angry, Fear, Surprise, Disgust
    style_weight=5.0,    # Emotion strength (0.0-10.0)
    speed=1.0,
    pitch=0.0,           # Pitch shift in semitones
    speaker_id=0,
)

# Custom model
engine = StyleBertTTSEngine(model_path="/path/to/your/model")

# Sentence-by-sentence streaming
async for chunk in engine.stream("長い文章を文ごとに生成します。"):
    pass

Pre-trained models: jvnv-F1-jp, jvnv-F2-jp (female), jvnv-M1-jp, jvnv-M2-jp (male)

Optimized for Japanese. GPU recommended for best performance.

License

MIT