> ## 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 엔진에 연결해 텍스트 음성 합성하는 절차를 설명합니다.

## 클라이언트 모드란

클라이언트 모드는 공식 VOICEVOX 엔진에 HTTP 요청을 보내 음성을 생성합니다.

FFI가 필요하지 않으므로, 처음 시도해 보는 입구로 사용하기 쉬운 모드입니다.

<Info>
  아직 도입하지 않았다면 [설치와 설정](/ko/packages/laravel-voicevox/installation)을 먼저 확인하세요.
</Info>

## 사전 준비

<Steps>
  <Step title="공식 엔진 실행">
    ```shell theme={null}
    docker pull voicevox/voicevox_engine:cpu-latest
    docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
    ```
  </Step>

  <Step title="필요하면 연결 대상 URL 설정">
    ```dotenv theme={null}
    VOICEVOX_URL=http://127.0.0.1:50021
    ```
  </Step>
</Steps>

GPU를 사용할 수 있는 환경이라면 GPU 이미지도 이용할 수 있습니다.

## 기본적인 사용법

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

$response = Voicevox::talk('Laravel이 좋다이다', id: 1)
    ->generate(id: 1);

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

## 스타일 ID 지정

`talk()`과 `generate()` 양쪽에 스타일 ID를 전달할 수 있습니다.

* `talk(id:)`: `audio_query`를 만들 때의 스타일
* `generate(id:)`: 음성 합성 시의 스타일

통상은 같은 값을 지정합니다.

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

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

사용 가능한 스피커 목록은 `speakers()`에서 획득할 수 있습니다.

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

$speakers = Voicevox::speakers();
```

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

이 패키지에서는 `generate()` 이전에 `TalkAudioQuery`를 받을 수 있으므로, `tap()`으로 부작용만 끼워 넣는 형태가 깔끔하게 맞아떨어집니다.

```php theme={null}
use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Voicevox;

$response = Voicevox::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);
```

<Tip>
  `tap()`은 쿼리 미세 조정만 하고, 반환값은 그대로 다음 `generate()`에 넘길 수 있습니다. 사고방식은 [tap() 헬퍼와 Tappable 트레이트](/ko/advanced/tap)에서 자세히 정리했습니다.
</Tip>

## 영어의 자동 카타카나 변환

클라이언트 모드에서는 `enable_katakana_english`가 활성화되어 있으므로, 영어를 포함한 텍스트를 자동으로 카타카나 쪽으로 보정할 수 있습니다.

```php theme={null}
$response = Voicevox::talk('I love Laravel', id: 1)
    ->generate(id: 1);
```

무효화하려면 세 번째 인수에 `false`를 전달합니다.

```php theme={null}
$response = Voicevox::talk('I love Laravel', id: 1, enableKatakanaEnglish: false)
    ->generate(id: 1);
```

## 응답 저장

```php theme={null}
$response = Voicevox::talk('테스트', id: 1)->generate(id: 1);

$wav = $response->content();
$path = $response->storeAs('client', 'talk.wav');
$path = $response->storeAs('client', 'talk.wav', disk: 's3');
```

## 다음에 읽어볼 페이지

<Columns cols={2}>
  <Card title="클라이언트 Song" href="/ko/packages/laravel-voicevox/client-song" icon="music">
    노래 합성으로 `Score`와 `Note`를 조립합니다.
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/ko/packages/voicevox-core-php/usage" icon="library">
    FFI를 사용하는 전제가 되면 코어 라이브러리 측 사용법도 확인합니다.
  </Card>
</Columns>


## Related topics

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