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:

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

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:

~/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;
}