> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started - VOICEVOX for Laravel

> Learn the package basics, compare the three modes, and run a quick start (client mode) for VOICEVOX for Laravel.

VOICEVOX for Laravel brings VOICEVOX speech synthesis features into Laravel. You can generate natural Japanese voice output from text.

<Tip>
  Start with client mode for the fastest setup. If your environment supports FFI, you can move to native mode or engine API mode later.
</Tip>

## Three usage modes

| Mode            | Runtime                                          | FFI          | Best for                                                   | Guide                                                                                                               |
| --------------- | ------------------------------------------------ | ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Client mode     | HTTP connection to official VOICEVOX engine      | Not required | First trial, Docker environments, environments without FFI | [Client Talk](/en/packages/laravel-voicevox/client-talk) / [Client Song](/en/packages/laravel-voicevox/client-song) |
| Native mode     | Direct VOICEVOX CORE calls through PHP FFI       | Required     | Better performance, offline use, CLI integration           | [Native Talk](/en/packages/laravel-voicevox/native-talk) / [Native Song](/en/packages/laravel-voicevox/native-song) |
| Engine API mode | Laravel serves VOICEVOX-compatible API endpoints | Required     | Publishing as an API server, multi-client integration      | [Engine Talk](/en/packages/laravel-voicevox/engine-talk) / [Engine Song](/en/packages/laravel-voicevox/engine-song) |

## Quick start

These steps cover client mode.

<Steps>
  <Step title="Install package(s)">
    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```

    See [Installation and Configuration](/en/packages/laravel-voicevox/installation) for full setup.
  </Step>

  <Step title="Start the official engine">
    ```shell theme={null}
    docker pull voicevox/voicevox_engine:cpu-latest
    docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
    ```
  </Step>

  <Step title="Try speech synthesis">
    ```php theme={null}
    use Revolution\Voicevox\Voicevox;

    $response = Voicevox::talk('こんにちは、Laravel です。', id: 1)->generate(id: 1);
    $response->storeAs('output.wav');
    ```
  </Step>
</Steps>

## Core features

### Speech synthesis (Talk)

```php theme={null}
use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Voicevox;

$response = Voicevox::talk('こんにちは', id: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
        $talk->audioQuery['pitchScale'] = 0.05;
        $talk->audioQuery['intonationScale'] = 1.5;
        $talk->audioQuery['volumeScale'] = 1.0;
    })
    ->generate(id: 1);
```

### Singing synthesis (Song)

```php theme={null}
use Revolution\Voicevox\Song\Note;
use Revolution\Voicevox\Song\Score;
use Revolution\Voicevox\Voicevox;

$score = Score::make([
    Note::make(length: 15),
    Note::make(length: Note::len(ticks: 480, bpm: 120), lyric: 'ド', key: 60),
    Note::make(length: Note::len(480, 120), lyric: 'レ', key: 62),
    Note::make(length: Note::len(960, 120), lyric: 'ミ', key: 64),
    Note::make(length: 2),
]);

$response = Voicevox::song($score)->generate(id: 3001);
```

### User dictionary and presets

In client mode, use the `Voicevox` facade to manage the user dictionary and presets on the official engine side.

```php theme={null}
use Revolution\Voicevox\Voicevox;

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 3,
);

$presetId = Voicevox::addPreset([
    'id' => 0,
    'name' => 'Slow and clear',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.8,
    'pitchScale' => 0.0,
    'intonationScale' => 1.2,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);
```

### Laravel AI SDK integration

```php theme={null}
use Laravel\Ai\Audio;

$audio = Audio::of('こんにちは、Laravel です。')
    ->voice('ずんだもん')
    ->generate();

$audio->storeAs('output.wav');
```

## Next steps

* [Installation and Configuration](/en/packages/laravel-voicevox/installation)
* [Configuration reference](/en/packages/laravel-voicevox/configuration)
* [Client Talk](/en/packages/laravel-voicevox/client-talk)
* [Client Song](/en/packages/laravel-voicevox/client-song)
* [Client mode - User Dictionary](/en/packages/laravel-voicevox/client-user-dict)
* [Client mode - Presets](/en/packages/laravel-voicevox/client-presets)
* [Native Talk](/en/packages/laravel-voicevox/native-talk)
* [Engine Talk](/en/packages/laravel-voicevox/engine-talk)
* [Native mode - User Dictionary](/en/packages/laravel-voicevox/native-user-dict)
* [Native mode - Presets](/en/packages/laravel-voicevox/native-presets)
* [AI SDK integration](/en/packages/laravel-voicevox/ai-sdk)