> ## 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 Core for PHP

> PHP FFI를 사용해 VOICEVOX CORE의 C 동적 라이브러리를 래핑한 Pure PHP 패키지. 텍스트 낭독(TTS)을 PHP에서 직접 이용할 수 있습니다.

## 개요

[revolution/voicevox-core](https://github.com/invokable/voicevox-core-php)는 [VOICEVOX CORE](https://github.com/VOICEVOX/voicevox_core)의 C 동적 라이브러리를 PHP FFI로 래핑한 Pure PHP 패키지입니다.

VOICEVOX는 고품질의 일본어 텍스트 낭독(TTS) 엔진으로, 이 패키지를 사용해 PHP에서 직접 음성 합성을 실행할 수 있습니다.

<Info>
  PHP FFI 자체의 구조와 제약을 먼저 정리하고 싶다면 [PHP FFI](/ko/advanced/ffi)를 참조하세요.
</Info>

<Tip>
  Laravel 앱에서 다룰 것이라면 [VOICEVOX for Laravel](/ko/packages/laravel-voicevox)도 함께 읽으면 클라이언트 모드와 네이티브 모드의 차이까지 정리할 수 있습니다.
</Tip>

<Warning>
  PHP FFI는 웹 서버 환경(FPM 등)에서 무효화된 경우가 많으므로(`ffi.enable=false`), 이 패키지는 **로컬 CLI에서의 사용을 전제**로 하고 있습니다.
</Warning>

## 요구 사항

* PHP 8.3+
* `ext-ffi` 확장이 활성화되어 있을 것
* VOICEVOX CORE 0.16+

## 설치

```bash theme={null}
composer require revolution/voicevox-core
```

## 라이브러리 셋업

이 패키지를 사용하려면 VOICEVOX CORE의 동적 라이브러리 (`.so` / `.dylib`), ONNX Runtime 라이브러리, OpenJTalk 사전이 필요합니다.

<Steps>
  <Step title="voicevox_core 다운로드">
    [voicevox\_core releases](https://github.com/VOICEVOX/voicevox_core/releases)에서 OS·아키텍처에 맞는 다운로더를 다운로드하여 실행합니다. 실행하면 현재 디렉터리에 `voicevox_core` 디렉터리가 생성됩니다.

    생성되는 디렉터리 구조:

    ```
    voicevox_core/
    ├── dict/open_jtalk_dic_*/     # OpenJTalk 사전
    ├── c_api/lib/                 # 동적 라이브러리 (.so, .dylib)
    ├── models/vvms/               # 음성 모델 파일 (.vvm)
    └── onnxruntime/               # ONNX Runtime 라이브러리
    ```
  </Step>

  <Step title="영구적인 위치로 이동">
    ```bash theme={null}
    mv voicevox_core ~/.local/voicevox_core
    ```
  </Step>

  <Step title="심볼릭 링크 생성 (권장)">
    라이브러리가 자동으로 발견되도록 심볼릭 링크를 생성합니다.

    <Warning>
      `ln -s`에는 반드시 **절대 경로**를 사용하세요.
    </Warning>

    **macOS:**

    ```bash theme={null}
    # [VOICEVOX_CORE_DIR]을 voicevox_core의 절대 경로로 바꾸세요
    ln -s [VOICEVOX_CORE_DIR]/libvoicevox_core.dylib /usr/local/lib/libvoicevox_core.dylib
    ```

    `/usr/local/lib/`에서 로드할 수 없는 경우 `.zshrc` 등에서 `DYLD_FALLBACK_LIBRARY_PATH`를 설정합니다:

    ```bash theme={null}
    export DYLD_FALLBACK_LIBRARY_PATH="$HOME/lib:/usr/local/lib:/usr/lib"
    ```

    **Linux:**

    ```bash theme={null}
    ln -s [VOICEVOX_CORE_DIR]/libvoicevox_core.so /usr/local/lib/libvoicevox_core.so
    ```
  </Step>
</Steps>

### 대안: 환경 변수로 지정

심볼릭 링크를 생성할 수 없는 경우, `VOICEVOX_CORE_LIB_PATH` 환경 변수에 라이브러리 파일의 전체 경로를 설정합니다:

```bash theme={null}
export VOICEVOX_CORE_LIB_PATH=/path/to/libvoicevox_core.dylib
```

```bash theme={null}
export VOICEVOX_CORE_LIB_PATH="$HOME/.local/voicevox_core/c_api/lib/libvoicevox_core.dylib"
```

<Info>
  macOS에서 `DYLD_FALLBACK_LIBRARY_PATH`를 사용해도 로드할 수 없는 경우 `VOICEVOX_CORE_LIB_PATH`로 설정하세요.
</Info>

## 문서

<Columns cols={2}>
  <Card title="사용법" href="/ko/packages/voicevox-core-php/usage" icon="play">
    텍스트 낭독·음성 합성의 기본 사용법과 코드 샘플.
  </Card>

  <Card title="API 레퍼런스" href="/ko/packages/voicevox-core-php/api" icon="code">
    모든 클래스·메서드·enum의 상세 레퍼런스.
  </Card>
</Columns>

## 참고 링크

* GitHub: [invokable/voicevox-core-php](https://github.com/invokable/voicevox-core-php)
* VOICEVOX CORE: [VOICEVOX/voicevox\_core](https://github.com/VOICEVOX/voicevox_core)


## Related topics

- [VOICEVOX for Laravel](/ko/packages/laravel-voicevox/index.md)
- [엔진 API 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-talk.md)
- [사용법 - VOICEVOX Core for PHP](/ko/packages/voicevox-core-php/usage.md)
- [API 레퍼런스 - VOICEVOX Core for PHP](/ko/packages/voicevox-core-php/api.md)
- [PHP FFI](/ko/advanced/ffi.md)