> ## 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 模式使用預設集功能,儲存與重用語音合成參數。

## 什麼是預設集

使用預設集功能可將常用的語音合成參數組合儲存起來重複使用。

<Info>
  將語速、音高、抑揚等一併管理,可在產生多個語音時保持一致的品質。
</Info>

## 概觀

Laravel VOICEVOX 的預設集功能是使用 VOICEVOX Core 的 Native 實作。預設集資料以 JSON 格式持久化於 `storage/voicevox/presets.json`。

由於使用與官方 VOICEVOX 引擎獨立的儲存,Laravel 端建立的預設集不會反映到官方引擎端(反之亦然)。

## 設定

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

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

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

## 預設集結構

預設集為以下結構。

```php theme={null}
[
    'id' => 1,                 // 預設集 ID(整數,自動編號)
    'name' => 'ゆっくり',       // 預設集名稱
    'speaker_uuid' => 'uuid',  // Speaker UUID(字串)
    'style_id' => 1,           // Style ID(整數)
    'speedScale' => 0.8,       // 語速(0.5 ~ 2.0)
    'pitchScale' => 0.0,       // 音高(-0.15 ~ 0.15)
    'intonationScale' => 1.0,  // 抑揚(0.0 ~ 2.0)
    'volumeScale' => 1.0,      // 音量(0.0 ~ 2.0)
    'prePhonemeLength' => 0.1, // 開頭靜音(0.0 ~ 1.5)
    'postPhonemeLength' => 0.1, // 結尾靜音(0.0 ~ 1.5)
]
```

## 基本用法

### 建立預設集

以 `preset()` helper 的 `add()` 建立預設集。

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

$id = preset()->add([
    'id' => 0, // 指定 0 會自動編號
    'name' => 'ゆっくり丁寧',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.8,
    'pitchScale' => 0.0,
    'intonationScale' => 1.2,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);

// 回傳自動編號的 ID
echo $id; // 例: 1
```

### 取得所有預設集

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

$presets = preset()->all();
```

### 搜尋預設集

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

$preset = preset()->find(1);

if ($preset !== null) {
    echo $preset['name']; // "ゆっくり丁寧"
}
```

### 更新預設集

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

preset()->update([
    'id' => 1,
    'name' => 'ゆっくりはっきり',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.7,
    'pitchScale' => 0.0,
    'intonationScale' => 1.5,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);
```

### 刪除預設集

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

preset()->delete(1);
```

## 使用預設集進行語音合成

使用 `talk()` helper 或 Engine API 的 `/audio_query_from_preset` endpoint。

### `talk()` helper

在 `talk(preset:)` 指定預設集 ID。此時一般的 style ID 會被忽略。

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

$response = talk('使用預設集', preset: 1)->generate(id: 1);
```

<Tip>
  套用預設集時,一般的語音合成流程仍相同。只有預設 `AudioQuery` 的值會被預設集取代。
</Tip>

### 透過 Engine API 存取

若有啟動 Laravel VOICEVOX 的 Engine API,也可透過 HTTP 操作預設集。

#### 取得所有預設集

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

#### 新增預設集

```bash theme={null}
curl -X POST http://localhost:50513/add_preset \
  -H "Content-Type: application/json" \
  -d '{
    "id": 0,
    "name": "ゆっくり丁寧",
    "speaker_uuid": "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff",
    "style_id": 1,
    "speedScale": 0.8,
    "pitchScale": 0.0,
    "intonationScale": 1.2,
    "volumeScale": 1.0,
    "prePhonemeLength": 0.1,
    "postPhonemeLength": 0.1
  }'
```

#### 更新預設集

```bash theme={null}
curl -X POST http://localhost:50513/update_preset \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "ゆっくりはっきり",
    "speaker_uuid": "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff",
    "style_id": 1,
    "speedScale": 0.7,
    "pitchScale": 0.0,
    "intonationScale": 1.5,
    "volumeScale": 1.0,
    "prePhonemeLength": 0.1,
    "postPhonemeLength": 0.1
  }'
```

#### 刪除預設集

```bash theme={null}
curl -X POST http://localhost:50513/delete_preset \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'
```

#### 使用預設集產生 audio query

```bash theme={null}
curl -X POST "http://localhost:50513/audio_query_from_preset?text=你好&preset_id=1"
```

## 參數詳解

* `speedScale`: 0.5 \~ 2.0(語速)
* `pitchScale`: -0.15 \~ 0.15(音高)
* `intonationScale`: 0.0 \~ 2.0(抑揚)
* `volumeScale`: 0.0 \~ 2.0(音量)
* `prePhonemeLength`: 0.0 \~ 1.5(開頭靜音,秒)
* `postPhonemeLength`: 0.0 \~ 1.5(結尾靜音,秒)

## 注意事項

<Warning>
  Laravel 版的預設集與官方 VOICEVOX 引擎的預設集為分開管理。新增、更新、刪除會立即儲存至 JSON 檔案。
</Warning>

* 預設集 ID 指定為 `0` 時,會自動編號未使用的 ID。
* 預設集請同時包含 `speaker_uuid`(UUID 字串)與 `style_id`(整數)。

## 疑難排解

### 預設集未儲存

1. 請確認 storage 目錄的寫入權限
2. 請確認 `storage/voicevox/presets.json` 是否正確建立

### 找不到預設集檔案位置

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

### 想重設預設集

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

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


## Related topics

- [Client 模式 - 預設集 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-presets.md)
- [Native 模式 - 使用者字典 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-user-dict.md)
- [Native 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-talk.md)
- [Native 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-song.md)
- [入門 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/getting-started.md)