Modo cliente - Diccionario de usuario - VOICEVOX for Laravel

Con el diccionario de usuario puedes registrar la lectura de nombres propios y términos técnicos en el motor oficial de VOICEVOX. En modo cliente, el diccionario no se guarda en Laravel; se utiliza tal cual la API de diccionario de usuario que gestiona el motor oficial al que te conectas.

Resumen

El diccionario de usuario del modo cliente se manipula desde la facade Voicevox. Internamente envía peticiones HTTP a /user_dict, /user_dict_word e /import_user_dict del motor oficial de VOICEVOX. Los datos del diccionario del motor oficial se guardan 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 habitualmente en:

~/Library/Application Support/voicevox-engine/user_dict.json

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, el diccionario se pierde al finalizar el contenedor. Si necesitas persistencia garantizada, monta el área de usuario del contenedor con un volumen Docker. Se gestiona por separado del storage/voicevox/user_dict.json del modo nativo. El config('voicevox.core.user_dict') 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

Uso básico

Añadir una palabra

Puedes registrar palabras con Voicevox::addWord().

use Revolution\Voicevox\Voicevox;

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// En modo cliente se devuelve un UUID con "-"
// Ejemplo: "a1b2c3d4-0000-0000-0000-000000000000"

Parámetros

Parámetro	Tipo	Descripción
`surface`	string	Forma (la cadena real de la palabra)
`pronunciation`	string	Lectura (solo katakana)
`accentType`	int	Tipo de acento (0 = plano, 1 o más = posición del acento)
`wordType`	string\|null	Clase gramatical (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`)
`priority`	int\|null	Prioridad

Obtener todas las palabras

Puedes obtener todas las palabras registradas.

use Revolution\Voicevox\Voicevox;

$words = Voicevox::userDict();

/*
[
    "a1b2c3d4-0000-0000-0000-000000000000" => [
        "surface" => "Laravel",
        "pronunciation" => "ララベル",
        "accent_type" => 0,
        "word_type" => "COMMON_NOUN",
        "priority" => 5,
    ],
    ...
]
*/

Actualizar una palabra

Actualiza indicando el UUID devuelto al añadir.

use Revolution\Voicevox\Voicevox;

Voicevox::updateWord(
    wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);

Eliminar una palabra

use Revolution\Voicevox\Voicevox;

Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');

Importar un diccionario

Puedes importar un array con el formato de diccionario de usuario del motor oficial. Con override: false (por defecto) se mantienen las palabras existentes y se añaden las importadas.

use Revolution\Voicevox\Voicevox;

$words = json_decode(file_get_contents('other_user_dict.json'), true);

Voicevox::importUserDict($words, override: false);

// Con override: true se reemplaza el diccionario existente
Voicevox::importUserDict($words, override: true);

Si quieres exportar el diccionario, guarda el resultado de Voicevox::userDict() como JSON.

$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

file_put_contents('exported_user_dict.json', $json);

Síntesis de voz tras registrar el diccionario

Las palabras registradas en el diccionario de usuario se consultan automáticamente al sintetizar voz con el motor oficial.

use Revolution\Voicevox\Voicevox;

Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = Voicevox::talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);

$response->storeAs('client', 'laravel.wav');

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::userDict()`	`GET /user_dict`
`Voicevox::addWord()`	`POST /user_dict_word`
`Voicevox::updateWord()`	`PUT /user_dict_word/{word_uuid}`
`Voicevox::deleteWord()`	`DELETE /user_dict_word/{word_uuid}`
`Voicevox::importUserDict()`	`POST /import_user_dict`

Diferencias con el modo nativo

Elemento	Modo cliente	Modo nativo
Forma de uso	Facade `Voicevox`	Helper `dict()`
Ubicación de guardado	Área de usuario del motor oficial	`storage/voicevox/user_dict.json` de Laravel
Ejemplo en macOS	`~/Library/Application Support/voicevox-engine/user_dict.json`	`storage/voicevox/user_dict.json`
UUID al añadir	Con `-`	Sin `-` desde Core
Proceso del motor	Necesario	No necesario (se requiere FFI)

Notas importantes

Indica pronunciation en katakana. No se pueden usar hiragana ni kanji.

En modo cliente se actualiza el diccionario del motor oficial. No se guarda en el storage del proyecto Laravel.
Si creas contenedores efímeros cada vez con docker run --rm, el diccionario se pierde al finalizar el contenedor.
El UUID que se devuelve al añadir tiene el formato con guiones, como a1b2c3d4-0000-0000-0000-000000000000.

Solución de problemas

La palabra no se refleja

Comprueba que el motor oficial de VOICEVOX esté arrancado.
Comprueba que VOICEVOX_URL apunte al destino correcto.
Comprueba que la lectura esté en katakana.
Comprueba si has vuelto a arrancar un contenedor distinto de Docker.

No sé dónde está el archivo del diccionario

En la build de macOS, comprueba esta ruta:

~/Library/Application Support/voicevox-engine/user_dict.json

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.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

Modo cliente - Diccionario de usuario - VOICEVOX for Laravel

Resumen

Preparación

Uso básico

Añadir una palabra

Parámetros

Obtener todas las palabras

Actualizar una palabra

Eliminar una palabra

Importar un diccionario

Síntesis de voz tras registrar el diccionario

Correspondencia con la Engine API

Diferencias con el modo nativo

Notas importantes

Solución de problemas

La palabra no se refleja

No sé dónde está el archivo del diccionario

​Resumen

​Preparación

​Uso básico

​Añadir una palabra

​Parámetros

​Obtener todas las palabras

​Actualizar una palabra

​Eliminar una palabra

​Importar un diccionario

​Síntesis de voz tras registrar el diccionario

​Correspondencia con la Engine API

​Diferencias con el modo nativo

​Notas importantes

​Solución de problemas

​La palabra no se refleja

​No sé dónde está el archivo del diccionario

Resumen

Preparación

Uso básico

Añadir una palabra

Parámetros

Obtener todas las palabras

Actualizar una palabra

Eliminar una palabra

Importar un diccionario

Síntesis de voz tras registrar el diccionario

Correspondencia con la Engine API

Diferencias con el modo nativo

Notas importantes

Solución de problemas

La palabra no se refleja

No sé dónde está el archivo del diccionario