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

# Installation and setup - VOICEVOX for Laravel

> How to install VOICEVOX for Laravel, including FFI-aware installation, configuration files, .env, and preparing engine resources.

## What to install

VOICEVOX for Laravel varies in the additional packages and local setup required depending on the mode you use.

> [tab] Client only
>
> If you only need to connect to the official VOICEVOX engine over HTTP, `revolution/laravel-voicevox` alone is enough.
>
> ```shell theme={null}
> composer require revolution/laravel-voicevox
> ```

> [tab] Native / engine API
>
> For modes that use FFI, install `revolution/voicevox-core` too.
>
> ```shell theme={null}
> composer require revolution/laravel-voicevox revolution/voicevox-core
> ```

## Requirements

| Item | Value |
| - | - |
| PHP | 8.3+ |
| Laravel | 12+ |
| Required extension | `ext-zip` |
| FFI `ext-ffi` | Required for native mode / engine API |

> [!WARNING]
>
> On most web servers — including Laravel Cloud — FFI is disabled. Try native mode and the engine API on a **local CLI**.

## Setup steps

**1. Install the package**

Install via Composer according to the mode you want. Native mode and the engine API also require [VOICEVOX Core for PHP](https://kawax.biz/en/packages/voicevox-core-php.md).

**2. Publish the config file**

```shell theme={null}
php artisan vendor:publish --tag="voicevox-config"
```

**3. Configure .env**

For client mode only, set `VOICEVOX_URL`. When using FFI, set `VOICEVOX_CORE_PATH`.

**4. Install engine resources if needed**

Additional resources are required to use `/speaker_info` or `/singer_info`.

## `config/voicevox.php`

You can review every setting in the [configuration reference](https://kawax.biz/en/packages/laravel-voicevox/configuration.md).

```php theme={null}
return [
    'client' => [
        'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
        'core_version' => env('VOICEVOX_CLIENT_CORE_VERSION'),
    ],

    'core' => [
        'path' => env('VOICEVOX_CORE_PATH'),
        'dict' => env('VOICEVOX_CORE_DICT_PATH', 'dict/open_jtalk_dic_utf_8-1.11'),
        'models' => env('VOICEVOX_CORE_MODELS_PATH', 'models/vvms'),
        'vvms' => ['0.vvm', '9.vvm', 's0.vvm'],
    ],

    'engine' => [
        'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
        'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
    ],
];
```

## The minimum `.env`

### Client mode only

If you run the official engine on the default `http://127.0.0.1:50021`, no additional configuration is needed.

```dotenv theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

### Native mode / engine API

```dotenv theme={null}
VOICEVOX_CORE_PATH=/path/to/voicevox_core/
```

> [!NOTE]
>
> The contents of `VOICEVOX_CORE_PATH` are prepared following the steps in [VOICEVOX Core for PHP](https://kawax.biz/en/packages/voicevox-core-php.md). Check there for placing the library itself, the OpenJTalk dictionary, and the model files.

## Enabling FFI

It usually works on the CLI out of the box.

To start the Laravel-side engine API locally, enable FFI in `php.ini`.

```ini theme={null}
ffi.enable=true
```

FFI's mechanics and limitations are summarized in [PHP FFI](https://kawax.biz/en/advanced/ffi.md).

## Installing engine resources

To use resource endpoints such as `/speaker_info` and `/singer_info`, install the resource files separately.

```shell theme={null}
php artisan voicevox:install
```

Under an Orchestra Testbench environment, use this command:

```shell theme={null}
vendor/bin/testbench voicevox:install
```

## Mode entry points

> [card] [Client Talk](https://kawax.biz/en/packages/laravel-voicevox/client-talk.md)
>
> Start the official VOICEVOX engine with Docker and synthesize text.

> [card] [Client Song](https://kawax.biz/en/packages/laravel-voicevox/client-song.md)
>
> Use `Score` and `Note` to synthesize singing voices.

> [card] [Native Talk](https://kawax.biz/en/packages/laravel-voicevox/native-talk.md)
>
> Call VOICEVOX CORE directly with FFI.

> [card] [Native Song](https://kawax.biz/en/packages/laravel-voicevox/native-song.md)
>
> Learn where singing voice models and `sync()` fit.

## Reference links

* [VOICEVOX for Laravel overview](https://kawax.biz/en/packages/laravel-voicevox.md)
* [Getting started](https://kawax.biz/en/packages/laravel-voicevox/getting-started.md)
* [Configuration reference](https://kawax.biz/en/packages/laravel-voicevox/configuration.md)
* [VOICEVOX Core for PHP](https://kawax.biz/en/packages/voicevox-core-php.md)
* [VOICEVOX Core for PHP usage](https://kawax.biz/en/packages/voicevox-core-php/usage.md)
* [PHP FFI](https://kawax.biz/en/advanced/ffi.md)


## Related topics

- [VOICEVOX for Laravel](https://kawax.biz/en/packages/laravel-voicevox/index.md)
- [Getting started - VOICEVOX for Laravel](https://kawax.biz/en/packages/laravel-voicevox/getting-started.md)
- [Native mode: Talk (text-to-speech) - VOICEVOX for Laravel](https://kawax.biz/en/packages/laravel-voicevox/native-talk.md)
- [Installation](https://kawax.biz/en/installation.md)
- [Native Mode: Song (Singing Synthesis) - VOICEVOX for Laravel](https://kawax.biz/en/packages/laravel-voicevox/native-song.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.