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

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