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

# Instalación y configuración - VOICEVOX for Laravel

> Explica cómo instalar VOICEVOX for Laravel, según se use FFI o no, el archivo de configuración, .env y la preparación de recursos del motor.

## Qué instalar

En VOICEVOX for Laravel, los paquetes adicionales y la configuración local cambian según el modo que quieras usar.

<Tabs>
  <Tab title="Solo cliente">
    Si solo te vas a conectar por HTTP al motor oficial de VOICEVOX, basta con `revolution/laravel-voicevox`.

    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```
  </Tab>

  <Tab title="Usar también nativo / Engine API">
    En los modos que usan FFI también instala `revolution/voicevox-core`.

    ```shell theme={null}
    composer require revolution/laravel-voicevox revolution/voicevox-core
    ```
  </Tab>
</Tabs>

## Requisitos

| Elemento              | Contenido                             |
| --------------------- | ------------------------------------- |
| PHP                   | 8.3+                                  |
| Laravel               | 12+                                   |
| Extensión obligatoria | `ext-zip`                             |
| FFI `ext-ffi`         | Requerido en modo nativo / Engine API |

<Warning>
  En servidores web comunes, incluido Laravel Cloud, FFI está deshabilitado. Prueba el modo nativo y la Engine API en un **CLI local**.
</Warning>

## Pasos de configuración

<Steps>
  <Step title="Instala el paquete">
    Instálalo con Composer según el modo que quieras usar. En modo nativo y Engine API también necesitas [VOICEVOX Core for PHP](/es/packages/voicevox-core-php).
  </Step>

  <Step title="Publica el archivo de configuración">
    ```shell theme={null}
    php artisan vendor:publish --tag="voicevox-config"
    ```
  </Step>

  <Step title="Configura .env">
    Solo para modo cliente, configura `VOICEVOX_URL`; si usas FFI, configura `VOICEVOX_CORE_PATH`.
  </Step>

  <Step title="Si es necesario, instala los recursos del motor">
    Para usar `/speaker_info` o `/singer_info` se requieren recursos adicionales.
  </Step>
</Steps>

## `config/voicevox.php`

Puedes ver todas las opciones en la [referencia de configuración](/es/packages/laravel-voicevox/configuration).

```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'),
    ],
];
```

## `.env` mínimo necesario

### Solo modo cliente

Si arrancas el motor oficial en el `http://127.0.0.1:50021` por defecto, no necesitas más configuración.

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

### Modo nativo / Engine API

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

<Info>
  El contenido de `VOICEVOX_CORE_PATH` se prepara con los pasos de [VOICEVOX Core for PHP](/es/packages/voicevox-core-php). La ubicación de la biblioteca, del diccionario OpenJTalk y de los archivos de modelo también se explica allí.
</Info>

## Habilitar FFI

En CLI suele funcionar tal cual.

Si vas a arrancar la API del motor versión Laravel en local, habilita FFI en `php.ini`.

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

Los detalles y limitaciones de FFI están recogidos en [PHP FFI](/es/advanced/ffi).

## Instalación de recursos del motor

Para usar endpoints de recursos como `/speaker_info` o `/singer_info` debes instalar los archivos de recursos por separado.

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

En entornos con Orchestra Testbench, el comando es:

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

## Entradas por modo

<Columns cols={2}>
  <Card title="Cliente Talk" href="/es/packages/laravel-voicevox/client-talk" icon="message-circle">
    Arranca el motor oficial de VOICEVOX en Docker y sintetiza voz desde texto.
  </Card>

  <Card title="Cliente Song" href="/es/packages/laravel-voicevox/client-song" icon="music">
    Sintetiza voz cantada usando `Score` y `Note`.
  </Card>

  <Card title="Nativo Talk" href="/es/packages/laravel-voicevox/native-talk" icon="cpu">
    Llama directamente a VOICEVOX CORE vía FFI.
  </Card>

  <Card title="Nativo Song" href="/es/packages/laravel-voicevox/native-song" icon="music">
    Revisa el modelo de voz cantada y cuándo usar `sync()`.
  </Card>
</Columns>

## Enlaces de referencia

* [Resumen de VOICEVOX for Laravel](/es/packages/laravel-voicevox)
* [Empezar](/es/packages/laravel-voicevox/getting-started)
* [Referencia de configuración](/es/packages/laravel-voicevox/configuration)
* [VOICEVOX Core for PHP](/es/packages/voicevox-core-php)
* [Uso de VOICEVOX Core for PHP](/es/packages/voicevox-core-php/usage)
* [PHP FFI](/es/advanced/ffi)


## Related topics

- [Referencia de configuración - VOICEVOX for Laravel](/es/packages/laravel-voicevox/configuration.md)
- [Instalación](/es/installation.md)
- [VOICEVOX for Laravel](/es/packages/laravel-voicevox/index.md)
- [Configuración](/es/configuration.md)
- [Empezar - VOICEVOX for Laravel](/es/packages/laravel-voicevox/getting-started.md)