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

# API 參考 - VOICEVOX Core for PHP

> VOICEVOX Core for PHP 所有類別、方法與 enum 的參考文件。

## `Onnxruntime`

ONNX Runtime 載入器。屬於行程層級的單例，每個行程僅存在一個實例。

### 方法

| 方法                                             | 說明                                                                     |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| `static loadOnce(string $filename = ''): self` | 載入並初始化 ONNX Runtime。第 2 次以後的呼叫會忽略引數，回傳既有的實例。                           |
| `static get(): ?self`                          | 回傳既有的實例。若尚未初始化則回傳 `null`。                                              |
| `supportedDevices(): string`                   | 以 JSON 字串回傳可用的裝置資訊。                                                    |
| `static libVersionedFilename(): string`        | 回傳含版本號的 ONNX Runtime 函式庫檔名（例如：`libvoicevox_onnxruntime.1.17.3.dylib`）。 |
| `static libUnversionedFilename(): string`      | 回傳不含版本號的 ONNX Runtime 函式庫檔名。                                           |

### 常數

| 常數            | 說明                              |
| ------------- | ------------------------------- |
| `LIB_NAME`    | 函式庫基底名稱（`voicevox_onnxruntime`） |
| `LIB_VERSION` | 建議的 ONNX Runtime 版本             |

***

## `OpenJtalk`

使用 OpenJTalk 的文字解析器。

### 方法

| 方法                                      | 說明                        |
| --------------------------------------- | ------------------------- |
| `__construct(string $openJtalkDictDir)` | 以 OpenJTalk 字典目錄的路徑進行初始化。 |
| `analyze(string $text): string`         | 解析日文文字，回傳重音短語陣列的 JSON。    |
| `useUserDict(UserDict $userDict): void` | 套用使用者字典。字典變更後需再次呼叫。       |

***

## `VoiceModelFile`

聲音模型檔案（`.vvm` 檔案）。

### 方法

| 方法                                | 說明                         |
| --------------------------------- | -------------------------- |
| `static open(string $path): self` | 開啟 `.vvm` 檔案。              |
| `id(): string`                    | 以 hex 字串（16 位元組）回傳聲音模型 ID。 |
| `createMetasJson(): string`       | 以 JSON 字串回傳話者中繼資料。         |
| `close(): void`                   | 關閉檔案並釋放資源。                 |

***

## `Synthesizer`

文字轉語音的主要類別。

### 方法

| 方法                                                                                                                               | 說明                                        |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `__construct(Onnxruntime $onnxruntime, OpenJtalk $openJtalk, AccelerationMode $accelerationMode = Auto, int $cpuNumThreads = 0)` | 初始化合成器。                                   |
| `onnxruntime(): Onnxruntime`                                                                                                     | 回傳此合成器持有的 `Onnxruntime` 實例。               |
| `isGpuMode(): bool`                                                                                                              | 回傳 GPU 模式是否啟用。                            |
| `metas(): string`                                                                                                                | 以 JSON 字串回傳已載入話者的中繼資料。                    |
| `loadVoiceModel(VoiceModelFile $model): void`                                                                                    | 載入聲音模型。                                   |
| `unloadVoiceModel(string $voiceModelId): void`                                                                                   | 卸載以 hex ID 指定的聲音模型。                       |
| `isLoadedVoiceModel(string $voiceModelId): bool`                                                                                 | 確認聲音模型是否已載入。                              |
| `createAudioQuery(string $text, int $styleId): string`                                                                           | 從日文文字產生 AudioQuery JSON。                  |
| `createAudioQueryFromKana(string $kana, int $styleId): string`                                                                   | 從 AquesTalk 風格的假名記法產生 AudioQuery JSON。    |
| `createAccentPhrases(string $text, int $styleId): string`                                                                        | 從日文文字產生重音短語陣列 JSON。                       |
| `createAccentPhrasesFromKana(string $kana, int $styleId): string`                                                                | 從假名記法產生重音短語陣列 JSON。                       |
| `replaceMoraData(string $accentPhrasesJson, int $styleId): string`                                                               | 回傳已更新音節音高與音素長度的新重音短語。                     |
| `replacePhonemeLength(string $accentPhrasesJson, int $styleId): string`                                                          | 回傳已更新音素長度的新重音短語。                          |
| `replaceMoraPitch(string $accentPhrasesJson, int $styleId): string`                                                              | 回傳已更新音節音高的新重音短語。                          |
| `synthesis(string $audioQueryJson, int $styleId, bool $enableInterrogativeUpspeak = true): string`                               | 從 AudioQuery JSON 合成語音。回傳 WAV 二進位。        |
| `tts(string $text, int $styleId, bool $enableInterrogativeUpspeak = true): string`                                               | 從日文文字一步合成語音。回傳 WAV 二進位。                   |
| `ttsFromKana(string $kana, int $styleId, bool $enableInterrogativeUpspeak = true): string`                                       | 從假名記法合成語音。回傳 WAV 二進位。                     |
| `createSingFrameAudioQuery(string $scoreJson, int $styleId): string`                                                             | 從樂譜 JSON 產生歌唱合成查詢 JSON。                   |
| `frameSynthesis(string $frameAudioQueryJson, int $styleId): string`                                                              | 從影格音訊查詢合成歌唱聲音。回傳 WAV 二進位。                 |
| `createSingFrameF0(string $scoreJson, string $frameAudioQueryJson, int $styleId): string`                                        | 從樂譜與歌唱查詢，以 JSON 的 float 陣列回傳每個影格的 F0（基頻）。 |
| `createSingFrameVolume(string $scoreJson, string $frameAudioQueryJson, int $styleId): string`                                    | 從樂譜與歌唱查詢，以 JSON 的 float 陣列回傳每個影格的音量。      |

***

## `VoicevoxCore`

VOICEVOX Core 的全域工具函式。

### 方法

| 方法                                                                              | 說明                                                     |
| ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `static getVersion(): string`                                                   | 以 SemVer 字串回傳 VOICEVOX Core 的版本。                       |
| `static audioQueryCreateFromAccentPhrases(string $accentPhrasesJson): string`   | 從重音短語陣列 JSON 產生 AudioQuery JSON。                       |
| `static audioQueryValidate(string $audioQueryJson): void`                       | 驗證 `AudioQuery` JSON。若不合法會擲出 `VoicevoxException`。      |
| `static accentPhraseValidate(string $accentPhraseJson): void`                   | 驗證 `AccentPhrase` JSON。若不合法會擲出 `VoicevoxException`。    |
| `static moraValidate(string $moraJson): void`                                   | 驗證 `Mora` JSON。若不合法會擲出 `VoicevoxException`。            |
| `static scoreValidate(string $scoreJson): void`                                 | 驗證 `Score` JSON。若不合法會擲出 `VoicevoxException`。           |
| `static noteValidate(string $noteJson): void`                                   | 驗證 `Note` JSON。若不合法會擲出 `VoicevoxException`。            |
| `static frameAudioQueryValidate(string $frameAudioQueryJson): void`             | 驗證 `FrameAudioQuery` JSON。若不合法會擲出 `VoicevoxException`。 |
| `static framePhonemeValidate(string $framePhonemeJson): void`                   | 驗證 `FramePhoneme` JSON。若不合法會擲出 `VoicevoxException`。    |
| `static ensureCompatible(string $scoreJson, string $frameAudioQueryJson): void` | 確認樂譜與歌唱音訊合成查詢的組合是否有效。若不合法會擲出 `VoicevoxException`。      |

***

## `UserDict`

用來註冊自訂單字發音的使用者字典。

### 方法

| 方法                                                                                                                                                        | 說明                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `__construct()`                                                                                                                                           | 建立空的使用者字典。              |
| `load(string $path): void`                                                                                                                                | 從檔案讀取使用者字典。             |
| `save(string $path): void`                                                                                                                                | 將使用者字典存檔。               |
| `addWord(string $surface, string $pronunciation, int $accentType, UserDictWordType $wordType = CommonNoun, int $priority = 5): string`                    | 新增單字。以 hex 字串回傳單字 UUID。 |
| `updateWord(string $wordUuid, string $surface, string $pronunciation, int $accentType, UserDictWordType $wordType = CommonNoun, int $priority = 5): void` | 更新以 UUID 指定的既有單字。       |
| `removeWord(string $wordUuid): void`                                                                                                                      | 刪除以 UUID 指定的單字。         |
| `importDict(UserDict $other): void`                                                                                                                       | 從其他的 `UserDict` 匯入單字。   |
| `toJson(): string`                                                                                                                                        | 以 JSON 字串回傳所有單字。        |

***

## Enum: `AccelerationMode`

合成器的硬體加速模式。

| Case   | 值   | 說明           |
| ------ | --- | ------------ |
| `Auto` | `0` | 自動選擇可用的最佳模式。 |
| `Cpu`  | `1` | 強制使用 CPU 模式。 |
| `Gpu`  | `2` | 強制使用 GPU 模式。 |

***

## Enum: `UserDictWordType`

使用者字典項目的詞性。

| Case         | 值   | 說明   |
| ------------ | --- | ---- |
| `ProperNoun` | `0` | 專有名詞 |
| `CommonNoun` | `1` | 一般名詞 |
| `Verb`       | `2` | 動詞   |
| `Adjective`  | `3` | 形容詞  |
| `Suffix`     | `4` | 接尾詞  |

***

## `VoicevoxException`

當 VOICEVOX Core 的 C API 呼叫回傳錯誤碼時擲出。例外訊息會包含來自函式庫的錯誤說明。


## Related topics

- [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php/index.md)
- [使用方式 - VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php/usage.md)
- [PHP FFI](/zh-TW/advanced/ffi.md)
- [設定參考 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/configuration.md)
- [VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/index.md)