> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Clientmodus - gebruikerswoordenboek - VOICEVOX for Laravel

> Leer hoe je in de clientmodus van VOICEVOX for Laravel het gebruikerswoordenboek van de officiële engine beheert en de uitspraak van eigennamen en vaktermen registreert.

Met het gebruikerswoordenboek kun je de uitspraak van eigennamen en vaktermen registreren in de officiële VOICEVOX-engine. In de clientmodus wordt het woordenboek niet aan de Laravel-kant opgeslagen; je gebruikt rechtstreeks de gebruikerswoordenboek-API die door de gekoppelde officiële engine wordt beheerd.

## Overzicht

Het gebruikerswoordenboek in de clientmodus beheer je via de `Voicevox`-facade. Intern worden HTTP-requests verstuurd naar `/user_dict`, `/user_dict_word` en `/import_user_dict` van de officiële VOICEVOX-engine.

De woordenboekdata van de officiële engine wordt per OS opgeslagen in het gebruikersgebied. Bij de macOS-buildversie van de VOICEVOX-app (productversie) wordt die doorgaans hier opgeslagen.

```text theme={null}
~/Library/Application Support/voicevox-engine/user_dict.json
```

Ook als je de officiële engine in Docker draait, wordt de data opgeslagen in het gebruikersgebied binnen de container. Zolang je dezelfde container blijft gebruiken, blijft de data behouden na een herstart. Maar als je telkens een tijdelijke container aanmaakt, zoals met `docker run --rm`, gaat het woordenboek verloren zodra de container stopt. Wil je het woordenboek betrouwbaar persistent maken, mount dan het gebruikersgebied in de container via een Docker volume.

Dit staat los van `storage/voicevox/user_dict.json` van de native modus. De Laravel-instelling `config('voicevox.core.user_dict')` wordt in de clientmodus niet gebruikt.

## Voorbereiding

Start de officiële VOICEVOX-engine.

```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
```

Je kunt de bestemming wijzigen met `VOICEVOX_URL`.

```env theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

## Basisgebruik

### Woorden toevoegen

Met `Voicevox::addWord()` kun je een woord registreren.

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

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

// In de clientmodus wordt een UUID mét "-" teruggegeven
// Bijvoorbeeld: "a1b2c3d4-0000-0000-0000-000000000000"
```

#### Parameters

| Parameter       | Type         | Beschrijving                                                             |
| --------------- | ------------ | ------------------------------------------------------------------------ |
| `surface`       | string       | Schrijfwijze (de daadwerkelijke tekenreeks van het woord)                |
| `pronunciation` | string       | Uitspraak (alleen katakana)                                              |
| `accentType`    | int          | Accenttype (0 = vlak, 1 of hoger = accentpositie)                        |
| `wordType`      | string\|null | Woordsoort (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`) |
| `priority`      | int\|null    | Prioriteit                                                               |

### Alle woorden ophalen

Je kunt alle geregistreerde woorden ophalen.

```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,
    ],
    ...
]
*/
```

### Woorden bijwerken

Werk een woord bij door de UUID op te geven die bij het toevoegen is teruggegeven.

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

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

### Woorden verwijderen

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

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

### Een woordenboek importeren

Je kunt een array in het gebruikerswoordenboekformaat van de officiële engine importeren. Met `override: false` (de standaard) blijven bestaande woorden behouden en worden de geïmporteerde woorden toegevoegd.

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

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

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

// Met override: true wordt het bestaande woordenboek vervangen
Voicevox::importUserDict($words, override: true);
```

Wil je het woordenboek exporteren, sla dan het resultaat van `Voicevox::userDict()` op als JSON.

```php theme={null}
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

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

## Spraaksynthese na registratie in het woordenboek

Woorden die je in het gebruikerswoordenboek hebt geregistreerd, worden automatisch gebruikt wanneer de officiële engine spraak synthetiseert.

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

## Mapping met de Engine API

Elke methode van de `Voicevox`-facade komt overeen met een API van de officiële engine.

| Laravel                      | Officiële engine-API                 |
| ---------------------------- | ------------------------------------ |
| `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`             |

## Verschillen met de native modus

| Onderdeel          | Clientmodus                                                    | Native modus                                  |
| ------------------ | -------------------------------------------------------------- | --------------------------------------------- |
| Gebruik            | `Voicevox`-facade                                              | `dict()`-helper                               |
| Opslaglocatie      | Gebruikersgebied van de officiële engine                       | `storage/voicevox/user_dict.json` van Laravel |
| Voorbeeld op macOS | `~/Library/Application Support/voicevox-engine/user_dict.json` | `storage/voicevox/user_dict.json`             |
| UUID bij toevoegen | Met `-`                                                        | Vanuit de Core zonder `-`                     |
| Engineproces       | Vereist                                                        | Niet nodig (FFI vereist)                      |

## Aandachtspunten

<Warning>
  Geef `pronunciation` op in katakana. Hiragana en kanji zijn niet toegestaan.
</Warning>

* In de clientmodus wordt het woordenboek aan de kant van de officiële engine bijgewerkt. Er wordt niets opgeslagen in de `storage` van je Laravel-project.
* Als je telkens een tijdelijke container aanmaakt, zoals met `docker run --rm`, gaat het woordenboek verloren wanneer de container stopt.
* De UUID die bij het toevoegen wordt teruggegeven heeft het formaat met koppeltekens, zoals `a1b2c3d4-0000-0000-0000-000000000000`.

## Problemen oplossen

### Woorden worden niet toegepast

1. Controleer of de officiële VOICEVOX-engine draait.
2. Controleer of `VOICEVOX_URL` naar de juiste bestemming verwijst.
3. Controleer of de uitspraak in katakana staat.
4. Controleer of je in Docker niet per ongeluk een andere container opnieuw hebt gestart.

### De locatie van het woordenboekbestand is onbekend

Controleer bij de macOS-buildversie de volgende locatie.

```text theme={null}
~/Library/Application Support/voicevox-engine/user_dict.json
```

In Docker wordt het opgeslagen in het gebruikersgebied van de officiële engine (binnen de container). Als persistentie nodig is, mount dan het gebruikersgebied in de container op een Docker volume.


## Related topics

- [Native modus - gebruikerswoordenboek - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/native-user-dict.md)
- [Clientmodus - presets - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/client-presets.md)
- [Clientmodus: song (zangsynthese) - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/client-song.md)
- [Clientmodus: talk (tekst-naar-spraak) - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/client-talk.md)
- [Aan de slag - VOICEVOX for Laravel](/nl/packages/laravel-voicevox/getting-started.md)