> ## 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의 도입 방법, FFI 유무에 따른 설치, 설정 파일, .env, 엔진 리소스 준비를 설명합니다.

## 무엇을 설치하는가

VOICEVOX for Laravel은 사용하려는 모드에 따라 추가 패키지와 로컬 셋업이 달라집니다.

<Tabs>
  <Tab title="클라이언트만">
    공식 VOICEVOX 엔진에 HTTP로 연결하기만 할 경우, `revolution/laravel-voicevox`만으로 시작할 수 있습니다.

    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```
  </Tab>

  <Tab title="네이티브 / 엔진 API도 사용">
    FFI를 사용하는 모드에서는 `revolution/voicevox-core`도 함께 설치합니다.

    ```shell theme={null}
    composer require revolution/laravel-voicevox revolution/voicevox-core
    ```
  </Tab>
</Tabs>

## 요구 사항

| 항목            | 내용                    |
| ------------- | --------------------- |
| PHP           | 8.3+                  |
| Laravel       | 12+                   |
| 필수 확장         | `ext-zip`             |
| FFI `ext-ffi` | 네이티브 모드 / 엔진 API에서 필요 |

<Warning>
  Laravel Cloud를 포함해 일반적인 웹 서버에서는 FFI가 무효화되어 있습니다. 네이티브 모드와 엔진 API는 **로컬 CLI**에서 시도하세요.
</Warning>

## 셋업 절차

<Steps>
  <Step title="패키지 설치">
    사용하려는 모드에 따라 Composer로 도입합니다. 네이티브 모드와 엔진 API에서는 [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)도 필요합니다.
  </Step>

  <Step title="설정 파일 게시">
    ```shell theme={null}
    php artisan vendor:publish --tag="voicevox-config"
    ```
  </Step>

  <Step title=".env 설정">
    클라이언트 모드만이라면 `VOICEVOX_URL`, FFI를 사용한다면 `VOICEVOX_CORE_PATH`를 설정합니다.
  </Step>

  <Step title="필요하면 엔진 리소스 설치">
    `/speaker_info`나 `/singer_info`를 사용할 경우, 추가 리소스가 필요합니다.
  </Step>
</Steps>

## `config/voicevox.php`

모든 설정 항목은 [설정 레퍼런스](/ko/packages/laravel-voicevox/configuration)에서 확인할 수 있습니다.

```php theme={null}
return [
    'client' => [
        'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
        'core_version' => env('VOICEVOX_CLIENT_CORE_VERSION'),
    ],

    'core' => [
        'path' => env('VOICEVOX_CORE_PATH'),
        'dict' => env('VOICEVOX_CORE_DICT_PATH', 'dict/open_jtalk_dic_utf_8-1.11'),
        'models' => env('VOICEVOX_CORE_MODELS_PATH', 'models/vvms'),
        'vvms' => ['0.vvm', '9.vvm', 's0.vvm'],
    ],

    'engine' => [
        'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
        'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
    ],
];
```

## 최소한으로 필요한 `.env`

### 클라이언트 모드만

기본값 `http://127.0.0.1:50021`에서 공식 엔진을 실행한다면 추가 설정은 불필요합니다.

```dotenv theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

### 네이티브 모드 / 엔진 API

```dotenv theme={null}
VOICEVOX_CORE_PATH=/path/to/voicevox_core/
```

<Info>
  `VOICEVOX_CORE_PATH`의 내용은 [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)의 절차로 준비합니다. 라이브러리 본체, OpenJTalk 사전, 모델 파일의 배치도 그쪽에서 확인하세요.
</Info>

## FFI 활성화

CLI에서는 통상 그대로 사용할 수 있습니다.

로컬에서 Laravel판 엔진 API를 실행하는 경우에는 `php.ini`에서 FFI를 활성화합니다.

```ini theme={null}
ffi.enable=true
```

FFI의 구조와 제약은 [PHP FFI](/ko/advanced/ffi)에 정리되어 있습니다.

## 엔진 리소스 설치

`/speaker_info`나 `/singer_info` 등 리소스 계열 엔드포인트를 사용할 경우에는 별도로 리소스 파일을 도입합니다.

```shell theme={null}
php artisan voicevox:install
```

Orchestra Testbench 환경에서는 다음 명령입니다.

```shell theme={null}
vendor/bin/testbench voicevox:install
```

## 모드별 진입점

<Columns cols={2}>
  <Card title="클라이언트 Talk" href="/ko/packages/laravel-voicevox/client-talk" icon="message-circle">
    공식 VOICEVOX 엔진을 Docker로 실행해 텍스트 음성 합성합니다.
  </Card>

  <Card title="클라이언트 Song" href="/ko/packages/laravel-voicevox/client-song" icon="music">
    `Score`와 `Note`를 사용해 노래 합성합니다.
  </Card>

  <Card title="네이티브 Talk" href="/ko/packages/laravel-voicevox/native-talk" icon="cpu">
    FFI로 VOICEVOX CORE를 직접 호출합니다.
  </Card>

  <Card title="네이티브 Song" href="/ko/packages/laravel-voicevox/native-song" icon="music">
    노래 모델과 `sync()`의 활용처를 확인합니다.
  </Card>
</Columns>

## 참고 링크

* [VOICEVOX for Laravel 개요](/ko/packages/laravel-voicevox)
* [시작하기](/ko/packages/laravel-voicevox/getting-started)
* [설정 레퍼런스](/ko/packages/laravel-voicevox/configuration)
* [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)
* [VOICEVOX Core for PHP 사용법](/ko/packages/voicevox-core-php/usage)
* [PHP FFI](/ko/advanced/ffi)


## Related topics

- [Laravel Cashier (Stripe)](/ko/cashier.md)
- [Laravel에서 MCP 서버 만들기](/ko/advanced/mcp-server.md)
- [설정 레퍼런스 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/configuration.md)
- [시작하기 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/getting-started.md)
- [네이티브 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-talk.md)