alltalk 0.1.0

# AllTalk Client

A Rust client library for the [AllTalk Text-to-Speech (TTS) API](https://github.com/erew123/alltalk_tts). 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`:

```toml
[dependencies]
alltalk = "0.1.0"
```

## Quick Start

```rust
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

```rust
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
```rust
// Check if the TTS service is ready
let is_ready = client.is_ready().await?;
```

#### Voice Management
```rust
// 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
```rust
// 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
```rust
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
```rust
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
```rust
// 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:

```rust
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

```rust
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](LICENSE) file for details.

## Contributing

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

## Related Projects

- [AllTalk TTS](https://github.com/erew123/alltalk_tts) - The main AllTalk Text-to-Speech project

## Author

Alberto Paro <alberto.paro@gmail.com>