> ## 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 - Diccionario de usuario - VOICEVOX for Laravel > Explica cómo manipular el diccionario de usuario del motor oficial en modo cliente de VOICEVOX for Laravel y registrar la lectura de nombres propios y términos técnicos. 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: ```text theme={null} ~/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. ```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 ``` ## Uso básico ### Añadir una palabra Puedes registrar palabras con `Voicevox::addWord()`. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} use Revolution\Voicevox\Voicevox; Voicevox::updateWord( wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000', surface: 'Laravel', pronunciation: 'ラレベル', accentType: 1, ); ``` ### Eliminar una palabra ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} $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. ```php theme={null} 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 1. Comprueba que el motor oficial de VOICEVOX esté arrancado. 2. Comprueba que `VOICEVOX_URL` apunte al destino correcto. 3. Comprueba que la lectura esté en katakana. 4. 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: ```text theme={null} ~/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. ## Related topics - [Modo nativo - Diccionario de usuario - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-user-dict.md) - [Modo cliente - Presets - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-presets.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)