Sokhanvar

A Python library for Persian text-to-speech with YAML configuration and an optional Gradio playground.

The included backend uses Pocket TTS Farsi v2. Other Persian TTS models can integrate through backend adapters.

Installation

Requires Python 3.12, 3.13, or 3.14.

uv add "sokhanvar[pocket]"

Or with pip:

pip install "sokhanvar[pocket]"

For development from this repository:

uv sync --extra pocket --extra playground

The pocket extra installs the speech runtime. The playground extra installs Gradio and is optional.

Usage

Save as sokhanvar.yaml:

backend: pocket_tts_farsi
model: mehdi-hf/pocket-tts-farsi-v2
language: fa
reference_audio: reference.wav
output_dir: outputs

Place your reference recording beside the YAML file, then generate speech:

from sokhanvar import Sokhanvar

speaker = Sokhanvar.from_yaml("sokhanvar.yaml")
result = speaker.synthesize("امروز هوا خوب است.", "speech.wav")

The result contains the WAV path, JSON metadata path, and generation metadata. Relative paths resolve beside the YAML file. Pocket Farsi uses up to five seconds of reference audio and downloads model weights on first use.

See the full configuration for pronunciation, pause, and sampling settings.

For CLI synthesis:

uv run sokhanvar synthesize \
  --config sokhanvar.yaml --text "امروز هوا خوب است." --output speech.wav

Playground

uv add "sokhanvar[pocket,playground]"
uv run sokhanvar playground --config sokhanvar.yaml

Open localhost:7860 to compare A/B pronunciation and pauses. The playground exports YAML settings, edited phrase plans, and a ZIP containing the reference recording for use in another project.

License

The library uses Apache 2.0. Pocket TTS Farsi v2 weights use CC BY-NC 4.0. The Persian pronunciation model has separate license terms.