pyht

library0.1.14pypypi✓ verified 86d ago

The official Python client for PlayHT's text-to-speech API. Current version 0.1.14, supports Python 3.8+. The library provides async and sync clients, WebSocket streaming, and support for PlayHT 2.0 and HD voices. Release cadence is irregular.

llm-agents ai-ml http-networking communication

pip install pyht

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYHT

pyht

llm-agentspythonv0.1.14

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from pyht import Client

✗ from pyht.client import Client

The top-level import is the correct one; the internal module path may break in future versions.

TTSOptions

✓ from pyht import TTSOptions

✗ from pyht.options import TTSOptions

TTSOptions is re-exported from the top-level module. Importing from submodules is fragile.

Format

✓ from pyht import Format

✗ from pyht.format import Format

Format enum is available at top level.

Initialize a client, create TTS options, and stream audio to a file.

import os from pyht import Client, TTSOptions, Format client = Client( user_id=os.environ.get('PLAYHT_USER_ID', ''), api_key=os.environ.get('PLAYHT_API_KEY', ''), ) options = TTSOptions( voice='s3://voice-cloning-zero-shot/xxxxx', format=Format.FORMAT_MP3, sample_rate=24000, ) with client.tts(text="Hello, world!", options=options) as audio_stream: with open('output.mp3', 'wb') as f: for chunk in audio_stream: f.write(chunk)

Debug

Known issues

breakingThe API key and user ID must be provided via environment variables PLAYHT_API_KEY and PLAYHT_USER_ID, or passed directly. The library does not read .env files automatically.

fix

Set the environment variables or pass them explicitly.

affects: >=0.1.0

deprecatedThe 'voice' parameter in TTSOptions accepts a URI string. The old pattern of using a voice name directly is no longer supported.

fix

Use the full S3 URI from the PlayHT dashboard.

affects: >=0.1.12

gotchaThe client.tts() returns a generator. You must iterate over it to actually process the audio. Calling it without consuming the generator may lead to silent failures.

fix

Use the context manager or explicitly iterate.

affects: >=0.1.0

gotchaWebSocket connections may drop if the token expires. There is no built-in reconnection logic.

fix

Implement custom retry logic or re-create the client periodically.

affects: >=0.1.0

deprecatedThe 'async' variant (AsyncClient) is not yet stable and may have breaking changes.

fix

Stick with synchronous Client for production.

affects: >=0.1.10

Errors

Common errors & fixes

pyht.exceptions.NotAuthenticatedError: Authentication failed

Missing or invalid API key or user ID.

fix

Set PLAYHT_USER_ID and PLAYHT_API_KEY environment variables, or pass them to Client().

ModuleNotFoundError: No module named 'pyht'

The library is not installed or the wrong Python environment is used.

fix

Run 'pip install pyht' in the correct virtual environment.

AttributeError: module 'pyht' has no attribute 'Client'

Older version of pyht that used a different import path.

fix

Upgrade to the latest version: pip install --upgrade pyht

TypeError: 'TTSOptions' object is not callable

Using TTSOptions() incorrectly, e.g., calling it instead of passing options to client.tts().

fix

Call client.tts(text=..., options=options) not client.tts(text=..., options=options()).

Upgrade

Version history

0.1.14latest on PyPI · released Mar 29, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/playht/pyht ↗

packagehttps://pypi.org/project/pyht/ ↗

homepagehttps://play.ht ↗