Modo cliente - Presets - VOICEVOX for Laravel

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:

~/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.

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.

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.

[
    '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.

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

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

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

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.

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().

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.

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

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

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

En modo cliente se actualiza el presets.yaml del motor oficial. No se guarda en el storage del proyecto Laravel.

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

Comprueba que el motor oficial de VOICEVOX esté arrancado.
Comprueba que VOICEVOX_URL apunte al destino correcto.
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:

~/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.

use Revolution\Voicevox\Voicevox;

$speakers = Voicevox::speakers();

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

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

Modo cliente - Presets - VOICEVOX for Laravel

Resumen

Preparación

Estructura del preset

Uso básico

Crear un preset

Obtener todos los presets

Actualizar un preset

Eliminar un preset

Síntesis de voz con presets

talkFromPreset()

audioQueryFromPreset()

Ajustes adicionales con tap()

Correspondencia con la Engine API

Diferencias con el modo nativo

Ejemplos prácticos

Para narración

Para habla rápida

Detalle de parámetros

Notas importantes

Solución de problemas

No se pueden obtener los presets

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

No conozco el speaker_uuid

​Resumen

​Preparación

​Estructura del preset

​Uso básico

​Crear un preset

​Obtener todos los presets

​Actualizar un preset

​Eliminar un preset

​Síntesis de voz con presets

​talkFromPreset()

​audioQueryFromPreset()

​Ajustes adicionales con tap()

​Correspondencia con la Engine API

​Diferencias con el modo nativo

​Ejemplos prácticos

​Para narración

​Para habla rápida

​Detalle de parámetros

​Notas importantes

​Solución de problemas

​No se pueden obtener los presets

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

​No conozco el speaker_uuid

Resumen

Preparación

Estructura del preset

Uso básico

Crear un preset

Obtener todos los presets

Actualizar un preset

Eliminar un preset

Síntesis de voz con presets

talkFromPreset()

audioQueryFromPreset()

Ajustes adicionales con tap()

Correspondencia con la Engine API

Diferencias con el modo nativo

Ejemplos prácticos

Para narración

Para habla rápida

Detalle de parámetros

Notas importantes

Solución de problemas

No se pueden obtener los presets

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

No conozco el speaker_uuid