Play API SDK

pyht is a Python SDK for Play's AI Text-to-Speech API. Play builds conversational voice AI models for realtime use cases. With pyht, you can easily convert text into high-quality audio streams with humanlike voices.

Currently the library supports only streaming and non-streaming text-to-speech. For the full set of functionalities provided by the Play API such as Voice Cloning, see the Play docs

Features

Requirements

Installation

You can install the pyht SDK using pip:

pip install pyht

Usage

You can use the pyht SDK by creating a Client instance and calling its tts method. Here's a simple example:

from pyht import Client
from dotenv import load_dotenv
from pyht.client import TTSOptions
import os
load_dotenv()

client = Client(
    user_id=os.getenv("PLAY_HT_USER_ID"),
    api_key=os.getenv("PLAY_HT_API_KEY"),
)
options = TTSOptions(voice="s3://voice-cloning-zero-shot/775ae416-49bb-4fb6-bd45-740f205d20a1/jennifersaad/manifest.json")
for chunk in client.tts("Hi, I'm Jennifer from Play. How can I help you today?", options):
    # do something with the audio chunk
    print(type(chunk))

It is also possible to stream text instead of submitting it as a string all at once:

for chunk in client.stream_tts_input(some_iterable_text_stream, options):
    # do something with the audio chunk
    print(type(chunk))

An asyncio version of the client is also available:

from pyht import AsyncClient

client = AsyncClient(
    user_id=os.getenv("PLAY_HT_USER_ID"),
    api_key=os.getenv("PLAY_HT_API_KEY"),
)
options = TTSOptions(voice="s3://voice-cloning-zero-shot/775ae416-49bb-4fb6-bd45-740f205d20a1/jennifersaad/manifest.json")
async for chunk in client.tts("Hi, I'm Jennifer from Play. How can I help you today?", options):
    # do something with the audio chunk
    print(type(chunk))

The tts method takes the following arguments:

TTSOptions

The TTSOptions class is used to specify the options for the TTS request. It has the following members, with these supported values:

Command-Line Demo

You can run the provided demo from the command line.

Note: This demo depends on the following packages:

pip install numpy soundfile

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!"

To run with the asyncio client, use the --async flag:

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!" --async

To run with the HTTP API, which uses our latest Play3.0-mini model, use the --http flag:

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!" --http

To run with the WebSockets API, which also uses our latest Play3.0-mini model, use the --ws flag:

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!" --ws

The HTTP and WebSockets APIs can also be used with the async client:

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!" --http --async
python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --text "Hello from Play!" --ws --async

Alternatively, you can run the demo in interactive mode:

python demo/main.py --user $PLAY_HT_USER_ID --key $PLAY_HT_API_KEY --interactive

In interactive mode, you can input text lines to generate and play audio on-the-fly. An empty line will exit the interactive session.

Get an API Key

To get started with the pyht SDK, you'll need your API Secret Key and User ID. Follow these steps to obtain them:

  1. Access the API Page: Navigate to the API Access page.

  2. Generate Your API Secret Key:

    • Click the "Generate Secret Key" button under the "Secret Key" section.
    • Your API Secret Key will be displayed. Ensure you copy it and store it securely.

  3. Locate Your User ID: Find and copy your User ID, which can be found on the same page under the "User ID" section.

Keep your API Secret Key confidential. It's crucial not to share it with anyone or include it in publicly accessible code repositories.