Audio Agent

The AudioAgent provides text-to-speech (TTS) capabilities using AI models through Prism PHP. Convert any text into natural-sounding speech with multiple voice options and audio formats.

Quick Start

Generate speech from text with just a few lines of code:

use Vizra\VizraADK\Agents\AudioAgent;

// Simple TTS generation
$audio = AudioAgent::run('Welcome to our application')->go();

// Save the audio
$audio->storeAs('welcome.mp3');

// Get the URL
$url = $audio->url();

Voice Selection

Choose from six distinct AI voices, each with their own character:

// Using the voice() method
$audio = AudioAgent::run('Hello world')
    ->voice('nova')
    ->go();

// Using voice preset methods
$audio = AudioAgent::run('Hello world')
    ->shimmer()
    ->go();

Available Voices

Voice	Description
`alloy`	Balanced, neutral voice (default)
`echo`	Warm, conversational tone
`fable`	Expressive, storytelling style
`onyx`	Deep, authoritative voice
`nova`	Friendly, energetic delivery
`shimmer`	Clear, professional sound

Each voice has a shortcut method: alloy(), echo(), fable(), onyx(), nova(), shimmer().

Audio Formats

Select your preferred output format based on your use case:

$audio = AudioAgent::run('Your order has been confirmed')
    ->format('wav')
    ->go();

Supported Formats

Format	Use Case
`mp3`	Web playback, general use (default)
`wav`	High quality, editing workflows
`opus`	Streaming, low latency
`aac`	iOS/Safari compatibility
`flac`	Lossless archival

Speech Speed

Adjust the speaking rate between 0.25x and 4.0x:

// Slower for accessibility
$audio = AudioAgent::run('Important instructions')
    ->speed(0.8)
    ->go();

// Faster for summaries
$audio = AudioAgent::run('Quick recap of today')
    ->speed(1.5)
    ->go();

Model Selection

Override the default model for different quality/speed tradeoffs:

// Use HD model for higher quality
$audio = AudioAgent::run('Premium narration content')
    ->using('openai', 'tts-1-hd')
    ->go();

// Use mini model for faster generation
$audio = AudioAgent::run('Quick notification')
    ->using('openai', 'gpt-4o-mini-tts')
    ->go();

Available Models

Model	Description
`tts-1`	Standard quality, faster generation (default)
`tts-1-hd`	Higher quality, slower generation
`gpt-4o-mini-tts`	Latest model with enhanced capabilities

Storage

Auto-store with Custom Filename

$audio = AudioAgent::run('Welcome message')
    ->voice('nova')
    ->storeAs('welcome.mp3')
    ->go();

echo $audio->url();  // Returns the stored file URL
echo $audio->path(); // Returns the storage path

Auto-store with Generated Filename

$audio = AudioAgent::run('Dynamic content')
    ->store()
    ->go();

// File stored with ULID filename like: vizra-adk/generated/audio/01HXY...mp3

Store to Specific Disk

$audio = AudioAgent::run('Private audio')
    ->storeAs('private/message.mp3', 's3')
    ->go();

Manual Storage

$audio = AudioAgent::run('Hello world')->go();

// Store with custom filename
$audio->storeAs('greetings/hello.mp3');

// Or auto-generate filename
$audio->store();

Working with AudioResponse

The AudioResponse object provides methods to access and manipulate the generated audio:

$audio = AudioAgent::run('Sample text')
    ->nova()
    ->format('mp3')
    ->go();

// Access audio data
$audio->data();      // Raw binary audio data
$audio->base64();    // Base64-encoded audio
$audio->toDataUri(); // Data URI for embedding (data:audio/mpeg;base64,...)

// Metadata
$audio->text();      // Original input text
$audio->voice();     // Voice used (e.g., 'nova')
$audio->format();    // Format (e.g., 'mp3')
$audio->mimeType();  // MIME type (e.g., 'audio/mpeg')
$audio->metadata();  // Full metadata array

// Storage status
$audio->isStored();  // Check if audio was stored
$audio->url();       // Get URL (stored or data URI)
$audio->path();      // Get storage path
$audio->disk();      // Get storage disk used

Embedding in HTML

$audio = AudioAgent::run('Play this message')->go();

// Using data URI (no storage needed)
$html = '<audio controls src="' . $audio->toDataUri() . '"></audio>';

// Using stored URL
$audio->store();
$html = '<audio controls src="' . $audio->url() . '"></audio>';

Async/Queued Generation

For long-running generations or batch processing, use Laravel queues:

// Basic async generation
AudioAgent::run('Long article content here...')
    ->onQueue('media')
    ->go();

// With callback after completion
AudioAgent::run('Order confirmation for order #12345')
    ->shimmer()
    ->format('mp3')
    ->onQueue('media')
    ->then(function ($audio) {
        $audio->storeAs('confirmations/order-12345.mp3');

        // Send notification, update database, etc.
        Notification::send($user, new AudioReadyNotification($audio->url()));
    })
    ->go();

Queue Options

AudioAgent::run('Background audio task')
    ->onQueue('media')        // Specify queue name
    ->delay(60)               // Delay in seconds
    ->tries(5)                // Retry attempts
    ->timeout(180)            // Timeout in seconds
    ->then(fn($audio) => $audio->store())
    ->go();

Async Return Value

When using async mode, go() returns job information instead of the audio:

$result = AudioAgent::run('Async generation')
    ->onQueue('media')
    ->go();

// $result contains:
// [
//     'job_dispatched' => true,
//     'job_id' => 'uuid-string',
//     'queue' => 'media',
//     'agent' => 'audio_agent',
//     'prompt' => 'Async generation',
// ]

User Context

Associate audio generation with a user for tracking and personalization:

AudioAgent::run('Personal greeting')
    ->forUser($user)
    ->withSession('session-123')
    ->go();

Sub-agent Delegation

Allow your LLM agents to generate audio by delegating to the AudioAgent:

use Vizra\VizraADK\Agents\BaseLlmAgent;
use Vizra\VizraADK\Tools\DelegateToMediaAgentTool;

class AssistantAgent extends BaseLlmAgent
{
    protected string $name = 'assistant';

    protected string $instructions = <<<'PROMPT'
        You are a helpful assistant. When the user asks you to
        read something aloud or create audio, use the generate_audio
        tool to convert text to speech.
    PROMPT;

    protected array $tools = [
        DelegateToMediaAgentTool::class,
    ];

    protected array $mediaAgents = [
        \Vizra\VizraADK\Agents\AudioAgent::class,
    ];
}

Or create the tool directly:

use Vizra\VizraADK\Tools\DelegateToMediaAgentTool;

class NarratorAgent extends BaseLlmAgent
{
    protected function tools(): array
    {
        return [
            DelegateToMediaAgentTool::forAudio(),
        ];
    }
}

When the LLM calls the generate_audio tool, it can specify:

text (required): The text to convert to speech
voice (optional): Voice selection
format (optional): Output format

Configuration

Environment Variables

# Provider and model
VIZRA_ADK_AUDIO_PROVIDER=openai
VIZRA_ADK_AUDIO_MODEL=tts-1

# Defaults
VIZRA_ADK_AUDIO_VOICE=alloy
VIZRA_ADK_AUDIO_FORMAT=mp3
VIZRA_ADK_AUDIO_SPEED=1.0

Config File

In config/vizra-adk.php:

'media' => [
    'audio' => [
        'provider' => env('VIZRA_ADK_AUDIO_PROVIDER', 'openai'),
        'model' => env('VIZRA_ADK_AUDIO_MODEL', 'tts-1'),
        'default_voice' => env('VIZRA_ADK_AUDIO_VOICE', 'alloy'),
        'default_format' => env('VIZRA_ADK_AUDIO_FORMAT', 'mp3'),
        'default_speed' => env('VIZRA_ADK_AUDIO_SPEED', 1.0),
    ],

    'storage' => [
        'disk' => env('VIZRA_ADK_MEDIA_DISK', 'public'),
        'path' => env('VIZRA_ADK_MEDIA_PATH', 'vizra-adk/generated'),
    ],
],

Complete Example

Here’s a comprehensive example showing common patterns:

use Vizra\VizraADK\Agents\AudioAgent;

class PodcastService
{
    public function generateIntro(string $episodeTitle): string
    {
        $text = "Welcome to today's episode: {$episodeTitle}";

        $audio = AudioAgent::run($text)
            ->using('openai', 'tts-1-hd')
            ->nova()
            ->format('mp3')
            ->speed(1.0)
            ->storeAs("podcasts/intros/{$this->slug($episodeTitle)}.mp3")
            ->go();

        return $audio->url();
    }

    public function generateChapterAudio(array $chapters): void
    {
        foreach ($chapters as $index => $chapter) {
            AudioAgent::run($chapter['content'])
                ->onyx()
                ->format('mp3')
                ->onQueue('podcast-generation')
                ->then(function ($audio) use ($chapter) {
                    $audio->storeAs("chapters/{$chapter['id']}.mp3");

                    Chapter::find($chapter['id'])->update([
                        'audio_url' => $audio->url(),
                        'audio_generated_at' => now(),
                    ]);
                })
                ->go();
        }
    }
}

Error Handling

try {
    $audio = AudioAgent::run('Generate this audio')
        ->nova()
        ->go();

    $audio->store();

} catch (\Exception $e) {
    Log::error('Audio generation failed', [
        'error' => $e->getMessage(),
    ]);
}

API Reference

AudioAgent Methods

Method	Description
`run(string $text)`	Static method to start fluent chain
`execute($input, $context)`	Direct execution with context
`toToolDefinition()`	Get tool schema for sub-agent use
`executeFromToolCall($args, $context)`	Execute from LLM tool call

MediaAgentExecutor Methods (Fluent Chain)

Method	Description
`voice(string $voice)`	Set voice
`format(string $format)`	Set output format
`speed(float $speed)`	Set speech speed (0.25-4.0)
`alloy()`, `echo()`, etc.	Voice presets
`using(string $provider, string $model)`	Override provider/model
`forUser(Model $user)`	Set user context
`withSession(string $id)`	Set session ID
`withContext(array $context)`	Add context data
`store(?string $path, ?string $disk)`	Auto-store with path
`storeAs(string $filename, ?string $disk)`	Auto-store with filename
`onQueue(string $queue)`	Enable async on queue
`delay(int $seconds)`	Delay queue execution
`tries(int $count)`	Set retry attempts
`timeout(int $seconds)`	Set timeout
`then(Closure $callback)`	Callback after completion
`go()`	Execute and return result

AudioResponse Methods

Method	Returns	Description
`data()`	`string`	Raw binary audio
`base64()`	`string`	Base64-encoded audio
`toDataUri()`	`string`	Data URI for embedding
`text()`	`string`	Original input text
`voice()`	`string`	Voice used
`format()`	`string`	Audio format
`mimeType()`	`string`	MIME type
`metadata()`	`array`	Full metadata
`store(?string $disk)`	`static`	Store with auto filename
`storeAs(string $filename, ?string $disk)`	`static`	Store with custom filename
`url()`	`?string`	Get URL
`path()`	`?string`	Get storage path
`disk()`	`?string`	Get storage disk
`isStored()`	`bool`	Check if stored
`raw()`	`mixed`	Get raw Prism response
`toArray()`	`array`	Convert to array
`toJson()`	`string`	Convert to JSON

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

API Reference

Quick Start

Voice Selection

Available Voices

Audio Formats

Supported Formats

Speech Speed

Model Selection

Available Models

Storage

Auto-store with Custom Filename

Auto-store with Generated Filename

Store to Specific Disk

Manual Storage

Working with AudioResponse

Embedding in HTML

Async/Queued Generation

Queue Options

Async Return Value

User Context

Sub-agent Delegation

Configuration

Environment Variables

Config File

Complete Example

Error Handling

API Reference

AudioAgent Methods

MediaAgentExecutor Methods (Fluent Chain)

AudioResponse Methods

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

API Reference

​Quick Start

​Voice Selection

​Available Voices

​Audio Formats

​Supported Formats

​Speech Speed

​Model Selection

​Available Models

​Storage

​Auto-store with Custom Filename

​Auto-store with Generated Filename

​Store to Specific Disk

​Manual Storage

​Working with AudioResponse

​Embedding in HTML

​Async/Queued Generation

​Queue Options

​Async Return Value

​User Context

​Sub-agent Delegation

​Configuration

​Environment Variables

​Config File

​Complete Example

​Error Handling

​API Reference

​AudioAgent Methods

​MediaAgentExecutor Methods (Fluent Chain)

​AudioResponse Methods

Quick Start

Voice Selection

Available Voices

Audio Formats

Supported Formats

Speech Speed

Model Selection

Available Models

Storage

Auto-store with Custom Filename

Auto-store with Generated Filename

Store to Specific Disk

Manual Storage

Working with AudioResponse

Embedding in HTML

Async/Queued Generation

Queue Options

Async Return Value

User Context

Sub-agent Delegation

Configuration

Environment Variables

Config File

Complete Example

Error Handling

API Reference

AudioAgent Methods

MediaAgentExecutor Methods (Fluent Chain)

AudioResponse Methods