Generate Expressive Speech from Text
Generate emotion-controlled text-to-speech audio in a LlamaIndex agent via Typecast.ai.
Why it matters
Transform text into natural-sounding speech with controllable emotions and advanced audio customization. Integrate seamlessly with AI agents for dynamic content creation.
Outcomes
What it gets done
Convert text to speech with emotional nuance
List and filter available AI voice models
Customize pitch, tempo, and volume
Generate reproducible audio outputs using seeds
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/li-tool-tools-typecast | bash Overview
Typecast.ai Tool
A LlamaIndex tool for Typecast.ai text-to-speech, with emotion, pitch, and tempo control, voice discovery, and reproducible output via seed. Use when an agent needs to generate actual spoken audio with a chosen emotion and voice, not real-time streaming speech.
What it does
The Typecast.ai Tool lets a LlamaIndex agent create audio files from text using Typecast.ai's text-to-speech engine, with control over emotion, pitch, and tempo. TypecastToolSpec exposes three functions: text_to_speech converts text into speech with emotion, pitch, and tempo control, and supports reproducible results via a seed parameter; get_voices lists all available Typecast voices; and get_voice returns details for a specific voice by its ID.
The underlying service supports multiple voice models (ssfm-v21, ssfm-v30), 27+ languages including English, Korean, Spanish, Japanese, and Chinese, and emotional expression (happy, sad, angry, normal, whisper, and more) with adjustable intensity. Output can be customized for volume, pitch, tempo, and format (WAV or MP3). The V2 API also supports filtering available voices by model, gender, age, or use case, and get_voice returns per-model emotion lists alongside gender and age metadata for a given voice.
When to use - and when NOT to
Use it when a LlamaIndex agent needs to produce actual audio output from text - for example generating a spoken response with a specific emotional tone, or picking a particular voice for a use case like an audiobook. Use the seed parameter specifically when you need the same text and voice to reproduce identical audio across runs, such as for testing or caching. Use get_voices/get_voice to discover or inspect available voices before committing to one in text_to_speech. Do not use it for use cases needing real-time, low-latency streaming speech - the tool generates audio files rather than a live audio stream.
Capabilities
text_to_speech generates an audio file from text with emotion, pitch, tempo, and optional seed control for reproducibility. get_voices lists and filters available voices by model, gender, age, or use case. get_voice retrieves details - including per-model emotion support - for a specific voice by ID.
How to install
from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
speech_tool = TypecastToolSpec(api_key="your-key")
agent = FunctionAgent(
tools=speech_tool.to_tool_list(),
llm=OpenAI(model="gpt-4o-mini"),
)
Requires a Typecast.ai API key.
Who it's for
Developers building LlamaIndex agents that need to generate expressive, emotion-controlled speech audio from text, with a choice of voices across many languages.
Source README
Typecast.ai Tool
This tool allows Agents to use Typecast.ai text-to-speech to create audio files from text with emotion control. To see more and get started, visit https://typecast.ai/
Usage
This tool has a more extensive example usage documented in a Jupyter notebook here
from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
speech_tool = TypecastToolSpec(api_key="your-key")
agent = FunctionAgent(
tools=speech_tool.to_tool_list(),
llm=OpenAI(model="gpt-4o-mini"),
)
print(
await agent.run(
'Create speech from the text "Hello world!" with a happy emotion and output the file to "speech.wav"'
)
)
text_to_speech: Convert text to speech with emotion, pitch, tempo control, and reproducible resultsget_voices: List all available Typecast voicesget_voice: Get details of a specific voice by ID
This tool is designed to be used as a Tool in an Agent.
Features
- Multiple Voice Models: Support for various AI voice models (ssfm-v21, ssfm-v30)
- Multi-language Support: 27+ languages including English, Korean, Spanish, Japanese, Chinese, and more
- Emotion Control: Adjust emotional expression (happy, sad, angry, normal, whisper, etc.) with intensity control
- Audio Customization: Control volume, pitch, tempo, and output format (WAV/MP3)
- Reproducible Results: Use seed parameter for consistent audio generation
- Voice Discovery: List and search available voices by model, gender, age, or use case (V2 API)
Advanced Usage
Using Seed for Reproducible Results
from llama_index.tools.typecast import TypecastToolSpec
speech_tool = TypecastToolSpec(api_key="your-key")
### Generate the same audio multiple times with the same seed
result = speech_tool.text_to_speech(
text="Hello world!",
voice_id="tc_62a8975e695ad26f7fb514d1",
output_path="speech.wav",
seed=42, # Same seed = same audio
)
Getting Voice Details (V2 API)
### Get specific voice information
voice = speech_tool.get_voice("tc_62a8975e695ad26f7fb514d1")
print(f"Voice: {voice['voice_name']}")
print(f"Gender: {voice['gender']}, Age: {voice['age']}")
print(f"Use cases: {voice['use_cases']}")
### Models now include emotions per model version
for model in voice["models"]:
print(f"Model {model['version']}: emotions = {model['emotions']}")
Filtering Voices (V2 API)
### Filter by model, gender, age, and use case
voices = speech_tool.get_voices(
model="ssfm-v30", gender="female", age="young_adult", use_case="Audiobook"
)
for voice in voices:
print(f"{voice['voice_name']} ({voice['voice_id']})")
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.