AllTalk Client

A Rust client library for the AllTalk Text-to-Speech (TTS) API. This library provides a convenient way to interact with AllTalk's TTS services from Rust applications.

Features

• 🎙️ Text-to-Speech Generation: Convert text to speech using various voice models
• 🔄 Model Management: Switch between different TTS models (API TTS, API Local, XTTSv2 Local, XTTSv2 FT)
• 🎚️ Advanced Settings: Control DeepSpeed, Low VRAM mode, and other performance settings
• 🌐 Multi-language Support: Support for 17 languages including English, Spanish, French, German, and more
• 👥 Voice Management: List available voices and preview voice samples
• 🎭 Narrator Support: Separate character and narrator voice generation
• 📁 File Download: Download generated audio files directly
• 🔍 Health Checks: Check if the TTS service is ready
• ⚡ Async/Await: Fully asynchronous API using tokio

Installation

Add this to your Cargo.toml:

[dependencies]
alltalk = "0.1.0"

Quick Start

use alltalk::{AllTalkClient, TTSModelOptions, Language};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client from environment variable ALLTALK_URL
    let client = AllTalkClient::from_environment()?;
    
    // Check if service is ready
    if !client.is_ready().await? {
        println!("AllTalk service is not ready");
        return Ok(());
    }
    
    // Generate speech
    let options = TTSModelOptions {
        text_input: "Hello, world! This is a test.".to_string(),
        character_voice_gen: "female_01.wav".to_string(),
        language: Language::English,
        output_file_name: "hello_world".to_string(),
        ..Default::default()
    };
    
    let response = client.generate_tts(&options).await?;
    println!("Generated audio: {}", response.output_file_url);
    
    // Download the generated audio file
    client.download_file(&response.output_file_url, "./hello_world.wav").await?;
    
    Ok(())
}

Configuration

Environment Variables

• ALLTALK_URL: The base URL of your AllTalk server (e.g., http://127.0.0.1:7851)

Client Creation

use alltalk::AllTalkClient;
use url::Url;

// From environment variable
let client = AllTalkClient::from_environment()?;

// From explicit URL
let url = Url::parse("http://127.0.0.1:7851")?;
let client = AllTalkClient::from_url(url)?;

API Reference

Core Methods

Health Check

// Check if the TTS service is ready
let is_ready = client.is_ready().await?;

Voice Management

// Get list of available voices
let voices = client.get_voices().await?;

// Preview a voice with sample text
let preview_url = client.preview_voice("female_01.wav").await?;

Settings and Configuration

// Get current settings
let settings = client.get_current_settings().await?;

// Switch TTS model
client.switch_model("XTTSv2 Local").await?;

// Toggle DeepSpeed
client.switch_deepspeed(true).await?;

// Toggle Low VRAM mode
client.switch_low_vram_setting(true).await?;

Text-to-Speech Generation

Basic Generation

use alltalk::{TTSModelOptions, Language, TextFiltering};

let options = TTSModelOptions {
    text_input: "Your text here".to_string(),
    character_voice_gen: "voice_file.wav".to_string(),
    language: Language::English,
    text_filtering: TextFiltering::Standard,
    output_file_name: "output".to_string(),
    output_file_timestamp: true,
    autoplay: false,
    autoplay_volume: 0.8,
    ..Default::default()
};

let response = client.generate_tts(&options).await?;

Advanced Generation with Narrator

let options = TTSModelOptions {
    text_input: "*This is narrator text* \"This is character speech\"".to_string(),
    character_voice_gen: "character_voice.wav".to_string(),
    narrator_enabled: true,
    narrator_voice_gen: "narrator_voice.wav".to_string(),
    text_not_inside: TextNotInside::Character,
    language: Language::English,
    ..Default::default()
};

let response = client.generate_tts(&options).await?;

File Download

// Download generated audio file
client.download_file(&response.output_file_url, "./my_audio.wav").await?;

Supported Languages

Language	Code
Arabic	ar
Chinese (Simplified)	zh-cn
Czech	cs
Dutch	nl
English	en
French	fr
German	de
Hindi	hi
Hungarian	hu
Italian	it
Japanese	ja
Korean	ko
Polish	pl
Portuguese	pt
Russian	ru
Spanish	es
Turkish	tr

Text Filtering Options

• None: No filtering, raw text passed to TTS engine
• Standard: Basic filtering for human-readable text
• HTML: Handles HTML entities and content

TTS Models

The client supports switching between different TTS models:

• API TTS: Cloud-based TTS service
• API Local: Local API-based TTS
• XTTSv2 Local: Local XTTSv2 model
• XTTSv2 FT: Fine-tuned XTTSv2 model (requires trained model in /models/trainedmodel/)

Error Handling

The library uses the AllTalkError enum for error handling:

use alltalk::AllTalkError;

match client.generate_tts(&options).await {
    Ok(response) => println!("Success: {}", response.output_file_url),
    Err(AllTalkError::ResponseError(msg)) => eprintln!("API Error: {}", msg),
    Err(AllTalkError::ReqwestError(e)) => eprintln!("Network Error: {}", e),
    Err(AllTalkError::JsonParserError { json, target }) => {
        eprintln!("JSON Parse Error: Failed to parse {} into {}", json, target);
    },
    Err(e) => eprintln!("Other Error: {}", e),
}

Examples

Complete Example with Voice Preview

use alltalk::{AllTalkClient, TTSModelOptions, Language, TextFiltering};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AllTalkClient::from_environment()?;
    
    // Check service status
    println!("Checking if AllTalk is ready...");
    if !client.is_ready().await? {
        eprintln!("AllTalk service is not ready");
        return Ok(());
    }
    
    // List available voices
    let voices = client.get_voices().await?;
    println!("Available voices: {:?}", voices);
    
    // Preview a voice
    if let Some(voice) = voices.first() {
        let preview_url = client.preview_voice(voice).await?;
        println!("Preview URL: {}", preview_url);
    }
    
    // Get current settings
    let settings = client.get_current_settings().await?;
    println!("Current model: {}", settings.current_model_loaded);
    
    // Generate TTS
    let options = TTSModelOptions {
        text_input: "Hello! This is a demonstration of the AllTalk TTS service.".to_string(),
        character_voice_gen: voices.first().unwrap_or(&"default.wav".to_string()).clone(),
        language: Language::English,
        text_filtering: TextFiltering::Standard,
        output_file_name: "demo".to_string(),
        output_file_timestamp: true,
        autoplay: false,
        autoplay_volume: 0.8,
        ..Default::default()
    };
    
    let response = client.generate_tts(&options).await?;
    println!("Generated TTS: {}", response.output_file_url);
    
    // Download the file
    client.download_file(&response.output_file_url, "./demo.wav").await?;
    println!("Downloaded audio file to ./demo.wav");
    
    Ok(())
}

Dependencies

• reqwest: HTTP client for API requests
• tokio: Async runtime
• serde: JSON serialization/deserialization
• url: URL parsing and manipulation
• anyhow: Error handling utilities
• thiserror: Custom error types

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• AllTalk TTS - The main AllTalk Text-to-Speech project

Author

Alberto Paro alberto.paro@gmail.com