PHPackages                             b7s/fluentvox - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. b7s/fluentvox

ActiveLibrary[Utility & Helpers](/categories/utility)

b7s/fluentvox
=============

Fluent PHP wrapper for Chatterbox TTS - State-of-the-art text-to-speech with voice cloning

v1.0.21(4mo ago)84839↑29.2%5[1 issues](https://github.com/b7s/fluentvox/issues)MITPHPPHP ^8.3

Since Jan 6Pushed 4mo agoCompare

[ Source](https://github.com/b7s/fluentvox)[ Packagist](https://packagist.org/packages/b7s/fluentvox)[ RSS](/packages/b7s-fluentvox/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (16)Used By (0)

 [![Logo](docs/logo.webp)](docs/logo.webp)FluentVox
=========

[](#fluentvox)

### 🎙️ Unleash state‑of‑the‑art text‑to‑speech and voice cloning in your PHP applications with style

[](#️-unleash-stateoftheart-texttospeech-and-voice-cloning-in-your-php-applications-with-style)

[![PHP Version](https://camo.githubusercontent.com/38027453aeb7eb818641c9de8f82b7624c3558d92634f1946edc715c3ddf8956/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/)[![PHPStan Level 6](https://camo.githubusercontent.com/21c74b536006ba91b1e8b5ee044ed3db15c8595100ff21f24852126e81c04c4f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230362d627269676874677265656e)](https://phpstan.org/)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

This standalone, developer‑friendly library brings the full power of Resemble AI’s Chatterbox TTS into a beautifully fluent PHP API. Effortless to use, lightning‑fast, and built for real‑world production environments, it handles everything—from seamless model management to cross‑platform compatibility on Linux, macOS, and Windows.

Whether you're crafting immersive voice experiences, automating audio generation, or building AI‑powered products, this wrapper gives you a clean, modern, and expressive toolkit that makes advanced TTS feel natural.

✨ Features
----------

[](#-features)

- 🎯 **Fluent API** - Laravel-inspired chainable interface
- 🌍 **Cross-Platform** - Linux, macOS (including Apple Silicon), and Windows support
- 📦 **Automatic Management** - Downloads and manages models automatically
- 🎭 **Voice Cloning** - Clone any voice from a reference audio file
- 🌐 **Multilingual** - Support for 23+ languages
- ⚡ **GPU Acceleration** - CUDA (NVIDIA), MPS (Apple Silicon), or CPU
- 🔒 **Type-Safe** - Full PHP 8.3+ type hints / PHPStan level 6
- 🛠️ **Complete CLI** - Command-line tools for installation and generation
- 🧪 **Tests** - Complete test suite with Pest PHP 4

Easy to use
-----------

[](#easy-to-use)

```
$result = FluentVox::make()
    ->text('Hello, world! This is FluentVox speaking.')
    ->generate();
```

📦 Installation
--------------

[](#-installation)

```
composer require b7s/fluentvox
```

### Install Dependencies

[](#install-dependencies)

After installing the package, install Python dependencies:

```
vendor/bin/fluentvox install
```

This will:

- Verify Python 3.10+ is installed
- Install Chatterbox TTS package
- Detect GPU acceleration (CUDA/MPS)

### Using Python Virtual Environments (venv)

[](#using-python-virtual-environments-venv)

FluentVox **automatically detects** Python virtual environments. It will prioritize:

1. **Active venv** (via `VIRTUAL_ENV` environment variable)
2. **Local venv directories** (`.venv`, `venv`, `venv311`, etc.) in current directory and parent directories
3. **System Python** (fallback)

**Recommended workflow:**

```
# Create a virtual environment (if you don't have one)
python3 -m venv venv

# Activate it (optional, but recommended)
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Install FluentVox dependencies in the venv
vendor/bin/fluentvox install
```

**Manual configuration:**

If FluentVox doesn't detect your venv automatically, specify the Python path in `fluentvox-config.php`:

```
return [
    'python_path' => '/path/to/venv/bin/python',  // Linux/macOS
    // or
    'python_path' => 'C:\\path\\to\\venv\\Scripts\\python.exe',  // Windows
    // ...
];
```

### Check Installation

[](#check-installation)

```
vendor/bin/fluentvox doctor
```

#### If you want to generate audio very quickly, choose:

[](#if-you-want-to-generate-audio-very-quickly-choose)

- Minimum recommended: RTX 3060 12 GB (~6x CPU)
- Ideal: RTX 4060 / 4060 Ti
- Top: RTX 4070+

🚀 Quick Start
-------------

[](#-quick-start)

### Basic Usage

[](#basic-usage)

```
use B7s\FluentVox\FluentVox;

$result = FluentVox::make()
    ->text('Hello, world! This is FluentVox speaking.')
    ->generate();

echo "Audio saved to: " . $result->outputPath;
echo "Duration: " . $result->getFormattedDuration();
```

### Voice Cloning

[](#voice-cloning)

```
$result = FluentVox::make()
    ->text('Hello, I sound just like the reference!')
    ->voiceFrom('/path/to/reference.wav')
    ->generate();
```

### Multilingual

[](#multilingual)

```
use B7s\FluentVox\Enums\Language;

$result = FluentVox::make()
    ->multilingual()
    ->text('Bonjour le monde!')
    ->language(Language::French)
    ->generate();
```

### Expressive Speech

[](#expressive-speech)

```
$result = FluentVox::make()
    ->text('Wow, this is absolutely amazing!')
    ->expressive()
    ->slow()
    ->generate();
```

### Custom Sample Rate

[](#custom-sample-rate)

```
// Generate audio at CD quality (44.1kHz)
$result = FluentVox::make()
    ->text('High quality audio output')
    ->sampleRate(44100)
    ->generate();

// Professional audio (48kHz)
$result = FluentVox::make()
    ->text('Professional quality')
    ->sampleRate(48000)
    ->generate();
```

🛠️ CLI Commands
---------------

[](#️-cli-commands)

### install - Install Dependencies

[](#install---install-dependencies)

```
# Basic installation
vendor/bin/fluentvox install

# Install with PyTorch
vendor/bin/fluentvox install --pytorch

# Upgrade existing packages
vendor/bin/fluentvox install --upgrade
```

### doctor - Diagnose Installation

[](#doctor---diagnose-installation)

```
# Basic diagnosis
vendor/bin/fluentvox doctor

# Download default model if not available
vendor/bin/fluentvox doctor --download-default
```

The `doctor` command checks your installation and shows:

- Platform compatibility
- Python and dependency status
- Model availability
- **Default model detection**: Identifies your configured default model and suggests downloading it if not available

### models - Manage Models

[](#models---manage-models)

```
# List available models
vendor/bin/fluentvox models

# Download a specific model
vendor/bin/fluentvox models download --model=chatterbox

# Download all models
vendor/bin/fluentvox models download --all
```

### generate - Generate Speech

[](#generate---generate-speech)

```
# Basic generation (uses default model from config)
vendor/bin/fluentvox generate "Hello, world!"

# Save to specific file
vendor/bin/fluentvox generate "Hello, world!" -o output.wav

# Specify a different model
vendor/bin/fluentvox generate "Hello!" --model=chatterbox-turbo

# With voice cloning
vendor/bin/fluentvox generate "Hello!" --voice=reference.wav

# Multilingual
vendor/bin/fluentvox generate "Bonjour!" -m chatterbox-multilingual -l fr
```

**Note:** If you don't specify `--model`, the command will use the `default_model` from your `fluentvox-config.php` file.

📖 API Reference
---------------

[](#-api-reference)

### Model Selection

[](#model-selection)

Choose which Chatterbox model to use based on your needs. Each model has different capabilities, performance characteristics, and language support.

```
// Standard English model (500M params)
FluentVox::make()->standard()  // Best for general use with emotion controls

// Turbo model - faster, with paralinguistic tags (350M params)
FluentVox::make()->turbo()  // Fastest, supports [laugh], [cough] tags

// Multilingual model - 23+ languages (500M params)
FluentVox::make()->multilingual()  // For non-English languages
```

### Voice Cloning

[](#voice-cloning-1)

Clone any voice by providing a reference audio sample. The model will mimic the speaker's voice characteristics, tone, and speaking style in the generated speech.

```
// Clone voice from reference audio
->voiceFrom('/path/to/reference.wav')  // Use this person's voice

// Alias
->cloneVoice('/path/to/reference.wav')

// Use default voice
->defaultVoice()  // Use model's built-in voice
```

### Language (Multilingual Model)

[](#language-multilingual-model)

Specify the target language when using the multilingual model. The model will generate speech with native pronunciation and intonation for the selected language.

```
use B7s\FluentVox\Enums\Language;

->language(Language::French)
->language(Language::Japanese)
->language(Language::Portuguese)

// Shortcuts for common languages
->english()
->french()
->spanish()
->german()
->portuguese()
->japanese()
->chinese()
```

**Supported Languages:** Arabic, Danish, German, Greek, English, Spanish, Finnish, French, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese, Russian, Swedish, Swahili, Turkish, Chinese ([see more details](https://github.com/resemble-ai/chatterbox?tab=readme-ov-file#supported-languages))

### Expression Controls

[](#expression-controls)

Control the emotional intensity and expressiveness of the generated speech. Higher values produce more dramatic, animated voices while lower values create calmer, more subdued speech.

```
// Exaggeration (0.25-2.0, neutral=0.5)
->exaggeration(0.7)

// Presets
->neutral()      // 0.5 - Balanced, natural expression
->expressive()   // 0.7 - More animated and emotional
->dramatic()     // 1.0 - Highly expressive, theatrical
->subtle()       // 0.3 - Understated, calm delivery
```

### Pace/CFG Controls

[](#pacecfg-controls)

Adjust the rhythm and speed of speech delivery. CFG (Classifier-Free Guidance) weight controls how closely the model follows the text pacing. Lower values create slower, more deliberate speech while higher values speed up delivery.

```
// CFG weight (0.2-1.0, default=0.5)
->cfgWeight(0.4)
->pace(0.4)  // alias

// Presets
->slow()        // 0.3 - Deliberate, measured pacing
->normalPace()  // 0.5 - Natural speaking speed
->fast()        // 0.7 - Quick, energetic delivery
```

### Randomness Controls

[](#randomness-controls)

Control the variability and creativity in speech generation. Temperature affects how predictable vs. varied the output is. Seeds allow you to reproduce exact results.

```
// Temperature (0.05-5.0, default=0.8)
->temperature(0.6)

// Presets
->deterministic()  // 0.3 - Consistent, predictable output
->creative()       // 1.2 - More varied, spontaneous speech

// Seed for reproducibility (0 = random)
->seed(42)  // Use same seed to get identical results
```

### Audio Processing

[](#audio-processing)

Configure how reference audio is processed for voice cloning. VAD (Voice Activity Detection) can remove silence and background noise from reference clips.

```
// Trim silence from reference audio
->trimSilence()  // Remove silence/noise from voice sample

// Keep silence (default)
->keepSilence()  // Use reference audio as-is
```

### Device Selection

[](#device-selection)

Choose which hardware to use for audio generation. GPU acceleration (CUDA/MPS) is significantly faster than CPU but requires compatible hardware.

```
// Auto-detect best device (default)
->autoDevice()  // Automatically selects CUDA > MPS > CPU

// Force CUDA (NVIDIA GPU)
->cuda()  // Use NVIDIA GPU (Linux/Windows)

// Force MPS (Apple Silicon)
->mps()  // Use Apple Metal (M1/M2/M3 Macs)

// Force CPU
->cpu()  // Use CPU only (slower but always available)
```

### Output Configuration

[](#output-configuration)

Configure where and how the generated audio is saved, with options for timeouts and progress monitoring.

```
// Set output path
->saveTo('/path/to/output.wav')  // Save to specific location
->output('/path/to/output.wav')  // alias

// Set sample rate (Hz)
->sampleRate(44100)  // Resample to 44.1kHz (CD quality)
->sampleRate(48000)  // Resample to 48kHz (professional audio)
->nativeSampleRate()  // Use model's native rate (24kHz, default)

// Set timeout (seconds)
->timeout(600)  // Maximum time to wait for generation

// Enable verbose output
->verbose()  // Show detailed generation logs

// Progress callback
->onProgress(function (string $output, bool $isError) {
    echo $output;  // Monitor generation progress in real-time
})
```

**Sample Rate Notes:**

- Model's native rate is **24kHz** (24000 Hz)
- If you specify a different rate, audio will be automatically resampled
- Common rates: 16000 (telephony), 24000 (native), 44100 (CD), 48000 (professional)
- Higher rates = larger files but potentially better quality
- Resampling adds minimal processing time

### Presets

[](#presets)

Pre-configured combinations of settings optimized for common use cases. These presets adjust expression, pace, and temperature for specific scenarios.

```
// Narration: clear, neutral, consistent
->forNarration()  // Audiobook narration, documentation

// Dialogue: expressive, varied
->forDialogue()  // Character voices, conversations

// Voice agents: fast, clear, low latency
->forVoiceAgent()  // Chatbots, virtual assistants

// Audiobooks: dramatic, varied pacing
->forAudiobook()  // Long-form storytelling
```

### Execution

[](#execution)

Generate the audio file or retrieve raw audio data for further processing.

```
// Generate and save to file
$result = FluentVox::make()
    ->text('Hello!')
    ->generate();  // Returns GenerationResult object

// Generate and get raw audio data
$audioData = FluentVox::make()
    ->text('Hello!')
    ->generateRaw();  // Returns raw WAV bytes as string
```

### Audio Conversion

[](#audio-conversion)

Convert generated audio to different formats using FFmpeg. All conversion methods generate the audio first, then convert it. The format is automatically detected from the file extension.

```
// Universal method - format detected from extension
$result = FluentVox::make()
    ->text('Hello!')
    ->convertTo('/path/to/output.mp3');  // Auto-detects MP3

$result = FluentVox::make()
    ->text('Hello!')
    ->convertTo('/path/to/output.m4a', ['bitrate' => 128]);

// Specific format methods
$result = FluentVox::make()
    ->text('Hello!')
    ->convertToMp3('/path/to/output.mp3', bitrate: 192);

$result = FluentVox::make()
    ->text('Hello!')
    ->convertToM4a('/path/to/output.m4a', bitrate: 128);

$result = FluentVox::make()
    ->text('Hello!')
    ->convertToOgg('/path/to/output.ogg', quality: 5);

$result = FluentVox::make()
    ->text('Hello!')
    ->convertToOpus('/path/to/output.opus', bitrate: 96);

$result = FluentVox::make()
    ->text('Hello!')
    ->convertToFlac('/path/to/output.flac');

// Convert and delete original WAV
$result = FluentVox::make()
    ->text('Hello!')
    ->convertTo('/path/to/output.mp3', deleteOriginal: true);

// Manual conversion of existing file
FluentVox::convertAudio(
    'input.wav',
    'output.mp3',
    'mp3',
    ['bitrate' => 320]
);

// Get audio file information
$info = FluentVox::getAudioInfo('audio.mp3');
// Returns: ['duration', 'sample_rate', 'channels', 'codec', 'bitrate']
```

**Supported Formats:**

- **MP3**: Universal compatibility, good compression (bitrate: 64-320 kbps)
- **M4A/AAC**: Apple devices, slightly better quality than MP3 (bitrate: 64-256 kbps)
- **OGG Vorbis**: Web streaming, open format (quality: 0-10)
- **Opus**: Best compression for voice, modern browsers (bitrate: 32-256 kbps)
- **FLAC**: Lossless compression, archival quality

### Result Object

[](#result-object)

The GenerationResult object contains information about the generated audio and metadata about the generation process.

```
$result = FluentVox::make()->text('Hello!')->generate();

$result->isSuccessful();           // bool - Check if generation succeeded
$result->getPath();                // string - Output file path
$result->getDuration();            // float - Duration in seconds
$result->getFormattedDuration();   // string - "00:02.50" format
$result->sampleRate;               // int - 24000 Hz
$result->text;                     // string - Original input text
$result->error;                    // string|null - Error message if failed
$result->metadata;                 // array - Generation parameters used
$result->toArray();                // array - All data as array
```

### Static Helpers

[](#static-helpers)

Utility methods for system checks, installation, model management, and audio conversion without creating a FluentVox instance.

```
// Check system requirements
$results = FluentVox::checkRequirements();  // Verify Python, PyTorch, etc.

// Install Chatterbox TTS
FluentVox::install(function ($output, $isError) {
    echo $output;  // Monitor installation progress
});

// List available models
$models = FluentVox::listModels();  // Get all models with download status

// Convert existing audio file
FluentVox::convertAudio('input.wav', 'output.mp3', 'mp3', ['bitrate' => 192]);

// Get audio file information
$info = FluentVox::getAudioInfo('audio.mp3');
// Returns: ['duration' => 5.2, 'sample_rate' => 44100, 'channels' => 2, ...]
```

⚙️ Configuration
----------------

[](#️-configuration)

Create a `fluentvox-config.php` file in your project root:

```