> ## 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 nativo - Diccionario de usuario - VOICEVOX for Laravel

> Explica cómo usar el diccionario de usuario en modo nativo de VOICEVOX for Laravel para registrar, actualizar e importar la lectura de nombres propios y términos técnicos.

## Qué es el diccionario de usuario

Con el diccionario de usuario puedes enseñar a VOICEVOX cómo leer nombres propios y términos técnicos. Las palabras registradas se pronunciarán correctamente al sintetizar el audio.

## Resumen

La funcionalidad de diccionario de usuario de Laravel VOICEVOX es una implementación nativa que usa el UserDict de VOICEVOX Core. Los datos del diccionario se persisten en formato JSON en `storage/voicevox/user_dict.json`.

<Info>
  Como usa un almacenamiento independiente del motor oficial de VOICEVOX, las palabras registradas en Laravel no se reflejan en el motor oficial (y viceversa).
</Info>

## Configuración

Por defecto se guarda en `storage/voicevox/user_dict.json`. Si quieres usar otra ruta, puedes cambiarla en `config/voicevox.php`.

```php theme={null}
// config/voicevox.php

return [
    'core' => [
        'user_dict' => storage_path('voicevox/user_dict.json'),
    ],
];
```

## Uso básico

### Añadir una palabra

Registra palabras con `add()` del helper `dict()`.

```php theme={null}
use function Revolution\Voicevox\dict;

$uuid = dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// Se devuelve un UUID sin "-"
// Ejemplo: "550e8400e29b41d4a716446655440000"
```

#### Parámetros

* `surface` (obligatorio): forma
* `pronunciation` (obligatorio): lectura (solo katakana)
* `accentType` (obligatorio): tipo de acento (`0` = plano, `1` o más = posición del acento)
* `wordType` (opcional): clase gramatical (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`)
* `priority` (opcional): prioridad (por defecto `5`)

#### Tipo de acento

* `0`: acento plano
* `1`: primer mora
* `2`: segundo mora
* `3`: tercer mora

### Actualizar una palabra

```php theme={null}
use function Revolution\Voicevox\dict;

dict()->update(
    wordUuid: '550e8400-e29b-41d4-a716-446655440000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);
```

### Eliminar una palabra

```php theme={null}
use function Revolution\Voicevox\dict;

dict()->delete('550e8400-e29b-41d4-a716-446655440000');
```

### Obtener todas las palabras

```php theme={null}
use function Revolution\Voicevox\dict;

$words = dict()->all();
// o
$words = dict()->toArray();
```

### Importar un diccionario

```php theme={null}
use function Revolution\Voicevox\dict;

$json = file_get_contents('other_user_dict.json');
dict()->import($json, override: false);

// Con override: true se sobrescribe
dict()->import($json, override: true);
```

### Exportar el diccionario

```php theme={null}
use function Revolution\Voicevox\dict;

$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
```

## Acceso vía Engine API

Si tienes arrancada la Engine API de Laravel VOICEVOX, puedes manipular el diccionario de usuario también por HTTP. No hace fallback al motor oficial; usa el diccionario nativo.

### Obtener todas las palabras

```bash theme={null}
curl http://localhost:50513/user_dict
```

### Añadir una palabra

```bash theme={null}
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
```

### Actualizar una palabra

```bash theme={null}
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
```

### Eliminar una palabra

```bash theme={null}
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
```

### Importar un diccionario

```bash theme={null}
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
  -H "Content-Type: application/json" \
  -d @other_dict.json
```

<Tip>
  Si indicas `override=true`, se elimina todo el diccionario existente antes de importar.
</Tip>

## Síntesis de voz tras registrar el diccionario

Las palabras registradas en el diccionario de usuario se consultan automáticamente al sintetizar el audio.

```php theme={null}
use function Revolution\Voicevox\{dict, talk};

dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);
$response->storeAs('native', 'laravel.wav');
```

## Notas importantes

<Warning>
  En `pronunciation` indica solo katakana. No se pueden usar hiragana ni kanji.
</Warning>

* El diccionario de usuario de la versión Laravel y el del motor oficial de VOICEVOX se gestionan por separado.
* Añadir, actualizar y eliminar palabras se guarda inmediatamente en el archivo JSON.
* Si no sabes qué tipo de acento poner, prueba primero con `0` (plano).

## Solución de problemas

### La palabra no se refleja

1. Comprueba los permisos de escritura del directorio de storage.
2. Comprueba que `storage/voicevox/user_dict.json` se ha creado correctamente.
3. Comprueba que la escritura en katakana sea correcta.

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

```php theme={null}
$path = config('voicevox.core.user_dict');
echo $path;
```

### Quiero resetear el diccionario

```bash theme={null}
rm storage/voicevox/user_dict.json
```

```php theme={null}
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
    unlink($path);
}
```


## Related topics

- [Modo cliente - Diccionario de usuario - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-user-dict.md)
- [Modo nativo - Presets - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-presets.md)
- [Modo nativo: Song (síntesis de voz cantada) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-song.md)
- [Modo nativo: Talk (síntesis de voz desde texto) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/native-talk.md)
- [Modo cliente: Song (síntesis de voz cantada) - VOICEVOX for Laravel](/es/packages/laravel-voicevox/client-song.md)