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

# Modo cliente - Presets - VOICEVOX for Laravel

> Explica cómo manipular los presets del motor oficial en modo cliente de VOICEVOX for Laravel y reutilizar los parámetros de síntesis de voz.

Con la funcionalidad de presets puedes guardar combinaciones habituales de parámetros de síntesis de voz en el motor oficial de VOICEVOX y reutilizarlas. En modo cliente, los presets no se guardan en Laravel; se usa la API de presets que gestiona el motor oficial al que te conectas.

## Resumen

Los presets del modo cliente se manejan desde la facade `Voicevox`. Internamente envía peticiones HTTP a `/presets`, `/add_preset`, `/update_preset`, `/delete_preset` y `/audio_query_from_preset` del motor oficial de VOICEVOX.

Los presets del motor oficial se guardan como `presets.yaml` en el área de usuario según el sistema operativo. En la build de macOS de la app de VOICEVOX (versión de producto) se guarda normalmente en:

```text theme={null}
~/Library/Application Support/voicevox-engine/presets.yaml
```

Cuando ejecutas el motor oficial con Docker también se guarda en el área de usuario dentro del contenedor. Los datos se mantienen mientras sigas usando el mismo contenedor, aunque reinicies. Sin embargo, si creas contenedores efímeros cada vez con `docker run --rm`, los presets se pierden al finalizar el contenedor. Si necesitas persistencia garantizada, monta el área de usuario del contenedor con un volumen Docker.

Se gestionan por separado del `storage/voicevox/presets.json` del modo nativo. El `config('voicevox.core.presets')` de Laravel no se usa en modo cliente.

## Preparación

Arranca el motor oficial de VOICEVOX.

```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
```

Puedes cambiar el destino de conexión con `VOICEVOX_URL`.

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

## Estructura del preset

El preset que se envía y recibe en modo cliente es un array que se ajusta al esquema de la API del motor oficial.

```php theme={null}
[
    'id' => 1,                // ID del preset (entero)
    'name' => 'ゆっくり',      // Nombre del preset
    'speaker_uuid' => 'uuid', // UUID del speaker (string)
    'style_id' => 1,          // ID de estilo (entero)
    'speedScale' => 0.8,      // Velocidad
    'pitchScale' => 0.0,      // Tono
    'intonationScale' => 1.0, // Entonación
    'volumeScale' => 1.0,     // Volumen
    'prePhonemeLength' => 0.1, // Silencio inicial
    'postPhonemeLength' => 0.1, // Silencio final
]
```

## Uso básico

### Crear un preset

Puedes crear presets con `Voicevox::addPreset()`. En el motor oficial, si indicas `0` como `id`, se asigna un ID libre.

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

$id = Voicevox::addPreset([
    'id' => 0,
    'name' => 'ゆっくり丁寧',
    '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,
]);

echo $id; // Ejemplo: 1
```

### Obtener todos los presets

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

$presets = Voicevox::presets();

/*
[
    [
        "id" => 1,
        "name" => "ゆっくり丁寧",
        "speaker_uuid" => "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff",
        "style_id" => 1,
        "speedScale" => 0.8,
        ...
    ],
    ...
]
*/
```

### Actualizar un preset

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

$id = Voicevox::updatePreset([
    'id' => 1,
    'name' => 'ゆっくりはっきり',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.7,
    'pitchScale' => 0.0,
    'intonationScale' => 1.5,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);
```

### Eliminar un preset

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

Voicevox::deletePreset(1);
```

## Síntesis de voz con presets

### talkFromPreset()

`Voicevox::talkFromPreset()` usa `/audio_query_from_preset` del motor oficial para crear un `TalkAudioQuery` con el preset ya aplicado.

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

$response = Voicevox::talkFromPreset('プリセットを使うのだ', presetId: 1)
    ->generate(id: 1);

$response->storeAs('client', 'preset-talk.wav');
```

### audioQueryFromPreset()

Si solo necesitas el array de audio query previo a la síntesis, usa `audioQueryFromPreset()`.

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

$audioQuery = Voicevox::audioQueryFromPreset(
    text: 'プリセットのクエリだけ作るのだ',
    presetId: 1,
);

$audioQuery['speedScale'] = 1.1;
```

### Ajustes adicionales con tap()

El `TalkAudioQuery` creado desde un preset se puede ajustar con `tap()` igual que con el `Voicevox::talk()` habitual.

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

$response = Voicevox::talkFromPreset('少し速く読むのだ', presetId: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
    })
    ->generate(id: 1);
```

## Correspondencia con la Engine API

Cada método de la facade `Voicevox` corresponde a una API del motor oficial.

| Laravel                            | API del motor oficial                               |
| ---------------------------------- | --------------------------------------------------- |
| `Voicevox::presets()`              | `GET /presets`                                      |
| `Voicevox::addPreset()`            | `POST /add_preset`                                  |
| `Voicevox::updatePreset()`         | `POST /update_preset`                               |
| `Voicevox::deletePreset()`         | `POST /delete_preset`                               |
| `Voicevox::audioQueryFromPreset()` | `POST /audio_query_from_preset`                     |
| `Voicevox::talkFromPreset()`       | `POST /audio_query_from_preset` + `POST /synthesis` |

## Diferencias con el modo nativo

| Elemento                  | Modo cliente                                                 | Modo nativo                      |
| ------------------------- | ------------------------------------------------------------ | -------------------------------- |
| Forma de uso              | Facade `Voicevox`                                            | Helpers `preset()` / `talk()`    |
| Formato de guardado       | `presets.yaml` del motor oficial                             | `presets.json` de Laravel        |
| Ejemplo en macOS          | `~/Library/Application Support/voicevox-engine/presets.yaml` | `storage/voicevox/presets.json`  |
| Generación de audio query | `/audio_query_from_preset` del motor oficial                 | Implementación nativa en Laravel |
| Proceso del motor         | Necesario                                                    | No necesario (se requiere FFI)   |

## Ejemplos prácticos

### Para narración

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

Voicevox::addPreset([
    'id' => 0,
    'name' => 'ナレーション',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 1.0,
    'pitchScale' => -0.05,
    'intonationScale' => 0.8,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.15,
    'postPhonemeLength' => 0.15,
]);
```

### Para habla rápida

```php theme={null}
Voicevox::addPreset([
    'id' => 0,
    'name' => '早口',
    'speaker_uuid' => '388f246b-8c41-4ac1-8e2d-5d79f3ff56d9',
    'style_id' => 3,
    'speedScale' => 1.5,
    'pitchScale' => 0.05,
    'intonationScale' => 1.3,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.05,
    'postPhonemeLength' => 0.05,
]);
```

## Detalle de parámetros

* `speedScale`: 0.5 a 2.0 (velocidad)
* `pitchScale`: -0.15 a 0.15 (tono)
* `intonationScale`: 0.0 a 2.0 (entonación)
* `volumeScale`: 0.0 a 2.0 (volumen)
* `prePhonemeLength`: 0.0 a 1.5 (silencio inicial, en segundos)
* `postPhonemeLength`: 0.0 a 1.5 (silencio final, en segundos)

## Notas importantes

<Warning>
  En modo cliente se actualiza el `presets.yaml` del motor oficial. No se guarda en el `storage` del proyecto Laravel.
</Warning>

* Si creas contenedores efímeros cada vez con `docker run --rm`, los presets se pierden al finalizar el contenedor.
* Incluye tanto `speaker_uuid` como `style_id`.
* Cuando llames a `generate(id:)` con una query creada por `talkFromPreset()`, normalmente indica el mismo ID que el `style_id` del preset.

## Solución de problemas

### No se pueden obtener los presets

1. Comprueba que el motor oficial de VOICEVOX esté arrancado.
2. Comprueba que `VOICEVOX_URL` apunte al destino correcto.
3. Comprueba si has vuelto a arrancar un contenedor distinto de Docker.

### No sé dónde está el archivo de presets

En la build de macOS, comprueba esta ruta:

```text theme={null}
~/Library/Application Support/voicevox-engine/presets.yaml
```

En Docker se guarda en el área de usuario del motor oficial (dentro del contenedor). Si necesitas persistencia, monta el área de usuario del contenedor en un volumen Docker.

### No conozco el speaker\_uuid

Puedes obtener el UUID desde la lista de speakers.

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

$speakers = Voicevox::speakers();

foreach ($speakers as $speaker) {
    echo $speaker['name'].': '.$speaker['speaker_uuid'].PHP_EOL;
}
```


## Related topics

- [Modo nativo - Presets - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-presets.md)
- [Modo cliente - Diccionario de usuario - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-user-dict.md)
- [Modo cliente: Song (síntesis de voz cantada) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-song.md)
- [Modo cliente: Talk (síntesis de voz desde texto) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-talk.md)
- [Modo nativo: Song (síntesis de voz cantada) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-song.md)