Skip to content

Usage

Quick Start

Here's a basic usage example:

from RealtimeTTS import TextToAudioStream, SystemEngine, AzureEngine, ElevenlabsEngine

engine = SystemEngine() # replace with your TTS engine
stream = TextToAudioStream(engine)
stream.feed("Hello world! How are you today?")
stream.play_async()

Feed Text

You can feed individual strings:

stream.feed("Hello, this is a sentence.")

Or you can feed generators and character iterators for real-time streaming:

def write(prompt: str):
    for chunk in openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content" : prompt}],
        stream=True
    ):
        if (text_chunk := chunk["choices"][0]["delta"].get("content")) is not None:
            yield text_chunk

text_stream = write("A three-sentence relaxing speech.")

stream.feed(text_stream)

char_iterator = iter("Streaming this character by character.")
stream.feed(char_iterator)

Playback

Asynchronously:

stream.play_async()
while stream.is_playing():
    time.sleep(0.1)

Synchronously:

stream.play()

Testing the Library

The test subdirectory contains a set of scripts to help you evaluate and understand the capabilities of the RealtimeTTS library.

Note that most of the tests still rely on the "old" OpenAI API (<1.0.0). Usage of the new OpenAI API is demonstrated in openai_1.0_test.py.

  • simple_test.py

    • Description: A "hello world" styled demonstration of the library's simplest usage.

  • complex_test.py

    • Description: A comprehensive demonstration showcasing most of the features provided by the library.

  • coqui_test.py

    • Description: Test of local coqui TTS engine.

  • translator.py

    • Dependencies: Run pip install openai realtimestt.
    • Description: Real-time translations into six different languages.

  • openai_voice_interface.py

    • Dependencies: Run pip install openai realtimestt.
    • Description: Wake word activated and voice based user interface to the OpenAI API.

  • advanced_talk.py

    • Dependencies: Run pip install openai keyboard realtimestt.
    • Description: Choose TTS engine and voice before starting AI conversation.

  • minimalistic_talkbot.py

    • Dependencies: Run pip install openai realtimestt.
    • Description: A basic talkbot in 20 lines of code.

  • simple_llm_test.py

    • Dependencies: Run pip install openai.
    • Description: Simple demonstration of how to integrate the library with large language models (LLMs).

  • test_callbacks.py

    • Dependencies: Run pip install openai.
    • Description: Showcases the callbacks and lets you check the latency times in a real-world application environment.

Pause, Resume & Stop

Pause the audio stream:

stream.pause()

Resume a paused stream:

stream.resume()

Stop the stream immediately:

stream.stop()

Requirements Explained

  • Python Version:
  • Required: Python >= 3.9, < 3.13

  • Reason: The library depends on the GitHub library "TTS" from coqui, which requires Python versions in this range.

  • PyAudio: to create an output audio stream

  • stream2sentence: to split the incoming text stream into sentences

  • pyttsx3: System text-to-speech conversion engine

  • pydub: to convert audio chunk formats

  • azure-cognitiveservices-speech: Azure text-to-speech conversion engine

  • elevenlabs: Elevenlabs text-to-speech conversion engine

  • coqui-TTS: Coqui's XTTS text-to-speech library for high-quality local neural TTS

Shoutout to Idiap Research Institute for maintaining a fork of coqui tts.

  • openai: to interact with OpenAI's TTS API

  • gtts: Google translate text-to-speech conversion