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

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

> 說明如何在 VOICEVOX for Laravel 的 Native 模式使用使用者字典,登記、更新與匯入專有名詞或專業術語的讀音。

## 什麼是使用者字典

使用使用者字典可讓 VOICEVOX 記住專有名詞或專業術語的讀音。登記的詞彙會在語音合成時以正確發音朗讀。

## 概觀

Laravel VOICEVOX 的使用者字典功能是使用 VOICEVOX Core 的 UserDict 實作的 Native 實作。字典資料以 JSON 格式持久化於 `storage/voicevox/user_dict.json`。

<Info>
  由於使用與官方 VOICEVOX 引擎獨立的儲存,Laravel 端登記的詞彙不會反映到官方引擎端(反向亦然)。
</Info>

## 設定

預設會儲存於 `storage/voicevox/user_dict.json`。若要使用其他路徑,可於 `config/voicevox.php` 變更。

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

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

## 基本用法

### 新增詞彙

以 `dict()` helper 的 `add()` 登記詞彙。

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

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

// 回傳無 "-" 的 UUID
// 例: "550e8400e29b41d4a716446655440000"
```

#### 參數

* `surface`(必填): 表記
* `pronunciation`(必填): 讀音(僅片假名)
* `accentType`(必填): 重音型別(`0` = 平板,`1` 以上 = 重音位置)
* `wordType`(選填): 詞性(`COMMON_NOUN`、`PROPER_NOUN`、`VERB`、`ADJECTIVE`、`SUFFIX`)
* `priority`(選填): 優先度(預設 `5`)

#### 重音型別

* `0`: 平板重音
* `1`: 第一拍
* `2`: 第二拍
* `3`: 第三拍

### 更新詞彙

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

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

### 刪除詞彙

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

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

### 取得所有詞彙

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

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

### 匯入字典

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

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

// override: true 為覆蓋
dict()->import($json, override: true);
```

### 匯出字典

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

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

## 透過 Engine API 存取

若有啟動 Laravel VOICEVOX 的 Engine API,也可透過 HTTP 操作使用者字典。不會 fallback 至官方引擎,而是使用 Native 字典。

### 取得所有詞彙

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

### 新增詞彙

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

### 更新詞彙

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

### 刪除詞彙

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

### 匯入字典

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

<Tip>
  指定 `override=true` 會先刪除所有現有字典再匯入。
</Tip>

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

登記於使用者字典的詞彙會在語音合成時自動參照。

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

## 注意事項

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

* Laravel 版的使用者字典與官方 VOICEVOX 引擎的使用者字典為分開管理。
* 詞彙的新增、更新、刪除會立即儲存至 JSON 檔案。
* 若不清楚重音型別,建議先嘗試 `0`(平板)。

## 疑難排解

### 詞彙未反映

1. 請確認 storage 目錄的寫入權限
2. 請確認 `storage/voicevox/user_dict.json` 是否正確建立
3. 請確認片假名表記是否正確

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

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

### 想重設字典

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

- [Client 模式 - 使用者字典 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-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)