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
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
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);
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
