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

# Client 模式 - 使用者字典 - VOICEVOX for Laravel

> 說明如何在 VOICEVOX for Laravel 的 Client 模式操作官方引擎的使用者字典,登記專有名詞或專業術語的讀音。

使用使用者字典可將專有名詞或專業術語的讀音登記於官方 VOICEVOX 引擎。在 Client 模式下,Laravel 端不會儲存字典,而是直接使用連線目標官方引擎所管理的使用者字典 API。

## 概觀

Client 模式的使用者字典透過 `Voicevox` Facade 操作。內部會對官方 VOICEVOX 引擎的 `/user_dict`、`/user_dict_word`、`/import_user_dict` 發送 HTTP 請求。

官方引擎的字典資料儲存於各 OS 的使用者區。VOICEVOX 應用(產品版)macOS 的 build 版通常儲存於下列位置。

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

若以 Docker 啟動官方引擎,也會儲存於容器內的使用者區。只要繼續使用同一個容器,即使重啟資料也會維持。但若使用 `docker run --rm` 之類每次建立臨時容器,容器結束時字典會遺失。若要確實持久化字典,請以 Docker volume 掛載容器內的使用者區。

與 Native 模式的 `storage/voicevox/user_dict.json` 為分開管理。Laravel 端的 `config('voicevox.core.user_dict')` 不會用於 Client 模式。

## 事前準備

啟動官方 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
```

連線目標可透過 `VOICEVOX_URL` 變更。

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

## 基本用法

### 新增詞彙

可透過 `Voicevox::addWord()` 登記詞彙。

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

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

// Client 模式會回傳含 "-" 的 UUID
// 例: "a1b2c3d4-0000-0000-0000-000000000000"
```

#### 參數

| 參數              | 型別           | 說明                                                          |
| --------------- | ------------ | ----------------------------------------------------------- |
| `surface`       | string       | 表記(實際詞彙的字串)                                                 |
| `pronunciation` | string       | 讀音(僅片假名)                                                    |
| `accentType`    | int          | 重音型別(0 = 平板,1 以上 = 重音位置)                                    |
| `wordType`      | string\|null | 詞性(`COMMON_NOUN`、`PROPER_NOUN`、`VERB`、`ADJECTIVE`、`SUFFIX`) |
| `priority`      | int\|null    | 優先度                                                         |

### 取得所有詞彙

可取得已登記的所有詞彙。

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

### 更新詞彙

以新增時回傳的 UUID 進行更新。

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

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

### 刪除詞彙

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

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

### 匯入字典

可匯入官方引擎使用者字典格式的陣列。`override: false`(預設)會保留現有詞彙,並追加匯入的詞彙。

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

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

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

// override: true 時取代現有字典
Voicevox::importUserDict($words, override: true);
```

若要匯出字典,可將 `Voicevox::userDict()` 的結果保存為 JSON。

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

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

## 字典登記後的語音合成

登記於使用者字典的詞彙會在官方引擎進行語音合成時自動參照。

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

## 與 Engine API 的對應

`Voicevox` Facade 的各方法對應於官方引擎的 API。

| Laravel                      | 官方引擎 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`             |

## 與 Native 模式的差異

| 項目        | Client 模式                                                      | Native 模式                                   |
| --------- | -------------------------------------------------------------- | ------------------------------------------- |
| 使用方式      | `Voicevox` Facade                                              | `dict()` helper                             |
| 儲存位置      | 官方引擎的使用者區                                                      | Laravel 的 `storage/voicevox/user_dict.json` |
| macOS 範例  | `~/Library/Application Support/voicevox-engine/user_dict.json` | `storage/voicevox/user_dict.json`           |
| 新增時的 UUID | 含 `-`                                                          | 從 Core 出來的無 `-`                             |
| 引擎程序      | 需要                                                             | 不需要(需要 FFI)                                 |

## 注意事項

<Warning>
  `pronunciation` 請以片假名指定。無法使用平假名或漢字。
</Warning>

* 在 Client 模式下更新的是官方引擎端的字典。不會儲存於 Laravel 專案的 `storage`。
* 若使用 `docker run --rm` 每次建立臨時容器,容器結束時字典會遺失。
* 新增時回傳的 UUID 為 `a1b2c3d4-0000-0000-0000-000000000000` 這類含 `-` 的格式。

## 疑難排解

### 詞彙未反映

1. 確認官方 VOICEVOX 引擎是否已啟動。
2. 確認 `VOICEVOX_URL` 指向正確的連線目標。
3. 確認讀音是否為片假名。
4. 確認是否在 Docker 中重新啟動了不同的容器。

### 找不到字典檔案位置

macOS 的 build 版請確認以下位置。

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

Docker 中會儲存於官方引擎的使用者區(容器內)。若需持久化,請將容器內的使用者區以 Docker volume 掛載。


## Related topics

- [Native 模式 - 使用者字典 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-user-dict.md)
- [入門 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/getting-started.md)
- [API 參考 - VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php/api.md)
- [設定參考 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/configuration.md)
- [使用方式 - VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php/usage.md)