> ## 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 로더. 프로세스 레벨의 싱글톤으로, 1개 프로세스당 1개 인스턴스만 존재합니다.

### 메서드

| 메서드                                            | 설명                                                                                |
| ---------------------------------------------- | --------------------------------------------------------------------------------- |
| `static loadOnce(string $filename = ''): self` | ONNX Runtime을 로드하여 초기화합니다. 두 번째 이후의 호출에서는 인수를 무시하고 기존 인스턴스를 반환합니다.                |
| `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`                    | 음성 모델 ID를 hex 문자열 (16바이트)로 반환합니다. |
| `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`                                               | 일본어 텍스트에서 1단계로 음성을 합성합니다. 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`                                        | 악보와 노래 쿼리에서 프레임별 F0 (기본 주파수)를 JSON의 float 배열로 반환합니다. |
| `createSingFrameVolume(string $scoreJson, string $frameAudioQueryJson, int $styleId): string`                                    | 악보와 노래 쿼리에서 프레임별 볼륨을 JSON의 float 배열로 반환합니다.          |

***

## `VoicevoxCore`

VOICEVOX Core의 글로벌 유틸리티 함수.

### 메서드

| 메서드                                                                             | 설명                                                                 |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `static getVersion(): string`                                                   | VOICEVOX Core의 버전을 SemVer 문자열로 반환합니다.                              |
| `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`                    | 단어를 추가합니다. 단어 UUID를 hex 문자열로 반환합니다. |
| `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 for Laravel](/ko/packages/laravel-voicevox/configuration.md)
- [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php/index.md)
- [Core Versions](/ko/packages/laravel-voicevox/engine-api/other/core-versions.md)
- [설치와 설정 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/installation.md)
- [Singers](/ko/packages/laravel-voicevox/engine-api/other/singers.md)