> ## 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 包。可直接从 PHP 使用文本朗读（TTS）。

## 概览

[revolution/voicevox-core](https://github.com/invokable/voicevox-core-php) 是一个使用 PHP FFI 封装 [VOICEVOX CORE](https://github.com/VOICEVOX/voicevox_core) 的 C 动态库的 Pure PHP 包。

VOICEVOX 是一个高品质的日语文本朗读（TTS）引擎，通过该包，你可以直接从 PHP 进行语音合成。

<Info>
  若想先了解 PHP FFI 自身的机制与限制，请参见 [PHP FFI](/zh/advanced/ffi)。
</Info>

<Tip>
  若要在 Laravel 应用中使用，也建议一并阅读 [VOICEVOX for Laravel](/zh/packages/laravel-voicevox)，以理清客户端模式与原生模式的差异。
</Tip>

<Warning>
  由于 PHP FFI 在 Web 服务器环境（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) 下载与操作系统和架构匹配的下载器并运行。运行后会在当前目录创建 `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="/zh/packages/voicevox-core-php/usage" icon="play">
    文本朗读/语音合成的基本用法与代码示例。
  </Card>

  <Card title="API 参考" href="/zh/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 Core for PHP](/fr/packages/voicevox-core-php/index.md)