> ## 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의 네이티브 모드에서 VOICEVOX CORE를 PHP FFI로 직접 호출해 텍스트 음성 합성하는 방법을 설명합니다.

## 네이티브 모드란

네이티브 모드는 [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)를 통해 VOICEVOX CORE를 PHP FFI로 직접 호출합니다.

공식 엔진을 실행하지 않아도 합성할 수 있지만, FFI와 로컬 라이브러리 셋업이 필요합니다.

<Warning>
  네이티브 모드는 웹 서버용이 아닙니다. 로컬 CLI에서 이용하세요. FFI의 제약은 [PHP FFI](/ko/advanced/ffi)에서도 설명하고 있습니다.
</Warning>

## 사전 준비

1. [설치와 설정](/ko/packages/laravel-voicevox/installation)을 완료했을 것
2. [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)의 셋업을 완료했을 것
3. `.env`에 `VOICEVOX_CORE_PATH`를 설정했을 것

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

## 기본적인 사용법

네이티브 모드에서는 `talk()` 헬퍼를 사용합니다.

```php theme={null}
use function Revolution\Voicevox\talk;

$response = talk('네이티브판인 것이다', id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'talk.wav');
```

## 스타일 ID 지정

`id`에는 로드된 `.vvm`에 포함된 스타일 ID를 지정합니다.

```php theme={null}
use function Revolution\Voicevox\talk;

$response = talk('ずんだもんなのだ', id: 1)
    ->generate(id: 1);
```

`config/voicevox.php`의 `core.vvms`에 포함된 모델만 사용할 수 있습니다.

## `tap()`으로 Audio Query 조정

네이티브 모드에서도 `tap()`의 사용법은 같습니다. 단, `TalkAudioQuery`는 클라이언트 모드와는 다른 클래스입니다.

```php theme={null}
use Revolution\Voicevox\Talk\TalkAudioQuery;
use function Revolution\Voicevox\talk;

$response = talk('빠르게 말하는 것이다', id: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
        $talk->audioQuery['pitchScale'] = 0.05;
        $talk->audioQuery['intonationScale'] = 1.5;
        $talk->audioQuery['volumeScale'] = 1.0;
    })
    ->generate(id: 1);
```

<Info>
  `tap()` 패턴 자체는 [tap() 헬퍼와 Tappable 트레이트](/ko/advanced/tap)에 정리되어 있습니다. VOICEVOX for Laravel은 그 실전 예시입니다.
</Info>

## AquesTalk 풍 표기의 카나 사용

네이티브 모드에는 `enable_katakana_english`가 없기 때문에, 영어가 섞인 입력을 그대로 읽는 용도에는 적합하지 않습니다.

대신 AquesTalk 풍 표기의 카나를 직접 전달하는 `kana()`를 사용할 수 있습니다.

```php theme={null}
use function Revolution\Voicevox\kana;

$response = kana("ネイティブ'バンナ/ノダ'", id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'kana.wav');
```

## 클라이언트 모드와의 차이

| 항목            | 클라이언트 Talk         | 네이티브 Talk |
| ------------- | ------------------ | --------- |
| 엔진 실행         | 필요                 | 불필요       |
| FFI           | 불필요                | 필요        |
| 영어 자동 카타카나 변환 | 있음                 | 없음        |
| API 진입점       | `Voicevox::talk()` | `talk()`  |

## 다음에 읽어볼 페이지

<Columns cols={2}>
  <Card title="네이티브 Song" href="/ko/packages/laravel-voicevox/native-song" icon="music">
    노래 모델을 FFI를 통해 다룹니다.
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/ko/packages/voicevox-core-php" icon="library">
    순수한 PHP 래퍼 측의 셋업과 제약을 확인합니다.
  </Card>
</Columns>


## Related topics

- [네이티브 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-song.md)
- [엔진 API 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-talk.md)
- [클라이언트 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-talk.md)
- [네이티브 모드 - 프리셋 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-presets.md)
- [네이티브 모드 - 사용자 사전 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-user-dict.md)