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

# 原生模式 - 预设 - VOICEVOX for Laravel

> 介绍在 VOICEVOX for Laravel 的原生模式下使用预设功能，保存并复用语音合成参数的方法。

## 什么是预设

使用预设功能，你可以将常用的语音合成参数组合保存并复用。

<Info>
  将语速、音高、抑扬等一并管理，即使生成多段语音也更容易保持品质一致。
</Info>

## 概览

Laravel VOICEVOX 的预设功能是基于 VOICEVOX Core 的原生实现。预设数据以 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',  // 说话人 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 或引擎 API 的 `/audio_query_from_preset` 端点。

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

### 通过引擎 API 访问

如果已启动 Laravel VOICEVOX 的引擎 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. 请确认存储目录具有写入权限
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

- [客户端模式 - 预设 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-presets.md)
- [原生模式 - 用户词典 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-user-dict.md)
- [原生模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-song.md)
- [原生模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-talk.md)
- [开始使用 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/getting-started.md)