unrealspeech 0.1.5

A Python package for interacting with the Unreal Speech API.

Unreal Speech API Python Package

Unreal Speech Python SDK allows you to easily integrate the Unreal Speech API into your Python applications for text-to-speech (TTS) synthesis. This SDK provides convenient methods for working with the Unreal Speech API, including generating speech, managing synthesis tasks, and streaming audio.

Table of Contents

• Getting Started
  • Installation
  • Obtaining an API Key
• Usage
  • Initializing the UnrealSpeechAPI
  • Generating Speech
  • Managing Synthesis Tasks
• Examples
• Documentation
• Contributing
• License

Getting Started

Installation

You can install the Unreal Speech API Python package using pip:

pip install unrealspeech

To ensure the package functions correctly, it is necessary to install the following dependencies as well.

pip install playsound pydub simpleaudio

Available endpoints

Endpoint	Description
/stream	Stream audio for short, time-sensitive cases
/speech	Generate speech with options (MP3 format)
/synthesisTasks	Manage synthesis tasks for longer text
/synthesisTasks/TaskId	Check the status of a synthesis task

Common Request Body Schema

Property	Type	Required?	Default Value	Allowed Values
VoiceId	string	Required	N/A	Scarlett, Liv, Dan, Will, Amy
Bitrate	string	Optional	192k	16k, 32k, 48k, 64k, 128k, 192k, 256k, 320k
Speed	float	Optional	0	-1.0 to 1.0
Pitch	float	Optional	1.0	0.5 to 1.5

Parameter Details

• VoiceId:

  • Dan: Young Male
  • Will: Mature Male
  • Scarlett: Young Female
  • Liv: Young Female
  • Amy: Mature Female

• Bitrate: Defaults to 192k. Use lower values for low bandwidth or to reduce the transferred file size. Use higher values for higher fidelity.

• Speed: Defaults to 0. Examples:

  • 0.5: makes the audio 50% faster. (i.e., 60-second audio becomes 42 seconds)
  • -0.5: makes the audio 50% slower. (i.e., 60-second audio becomes 90 seconds.)

• Pitch: Defaults to 1. However, on the landing page, we default male voices to 0.92 as people tend to prefer lower/deeper male voices.

Rate Limit

Plan	Requests per second
Free	1
Basic	2
Pro	8

Obtaining an API Key

Get your API Key To use the Unreal Speech API, you'll need to obtain an API key by signing up for an account on the Unreal Speech website. Once you have an API key, you can use it to initialize the UnrealSpeechAPI class.

Usage

Initializing the UnrealSpeechAPI

First, import the UnrealSpeechAPI class:

from unrealspeech import UnrealSpeechAPI, play, save

Then, initialize the API with your API key:

api_key = 'YOUR_API_KEY'
speech_api = UnrealSpeechAPI(api_key)

Generating Speech

You can generate speech by providing a text string and optional parameters:

text_to_speech = "This is a sample text."
timestamp_type = "sentence"  # Choose from 'sentence' or 'word'
voice_id = "Scarlett"  # Choose the desired voice
bitrate = "192k"
speed = 0 
pitch = 1.0
audio_data = speech_api.speech(text=text_to_speech,voice_id=voice_id, bitrate=bitrate, timestamp_type=timestamp_type, speed=speed, pitch=pitch)

# Play audio
play(audio_data)

Streaming Audio

For short and time-sensitive cases, you can use the /stream endpoint to stream audio:

# Stream audio
text_to_stream = "This is a short text to be synthesized."
voice_id = "Will"
timestamp_type = "sentence"  # Choose from 'sentence' or 'word'
bitrate = "192k"
speed = 0
pitch = 1.0

# Generate audio from text
audio_data = speech_api.stream(
   text=text_to_stream, voice_id=voice_id, bitrate=bitrate, timestamp_type=timestamp_type, speed, pitch)

 # Play audio
play(audio_data)

Managing Synthesis Tasks

You can manage synthesis tasks for longer text using the /synthesisTasks endpoint:

# Create a synthesis task
task_id = speech_api.create_synthesis_task(text="Long content", voice_id="Will", bitrate="320k", timestamp_type="word", speed=0, pitch=1.0)

# Check the task status
audio_data = speech_api.get_synthesis_task_status(task_id)

# Play audio
play(audio_data)

Downloading Audio

You can download audio by simply calling the save function

  from unrealspeech import save

  audio_data = sppech_api.speech('How to download your audio easily')

  # you can use the save function to save the audio
  save(audio_data, "output.mp3")

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.