> ## 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의 기본 개념, 3가지 모드 비교, 빠른 시작(클라이언트 모드), 주요 기능을 정리합니다.

VOICEVOX for Laravel은 Laravel에서 VOICEVOX의 음성 합성 기능을 사용하기 위한 패키지입니다. 텍스트에서 일본어 음성을 생성할 수 있습니다.

<Tip>
  우선 클라이언트 모드부터 시작하면 셋업이 최단입니다. FFI를 사용할 수 있는 환경이라면 나중에 네이티브 모드나 엔진 API 모드로 단계적으로 이전할 수 있습니다.
</Tip>

## 3가지 이용 모드

| 모드        | 실행 방식                         | FFI | 적합한 용도                             | 가이드                                                                                                                 |
| --------- | ----------------------------- | --- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 클라이언트 모드  | 공식 VOICEVOX 엔진에 HTTP 연결       | 불필요 | 우선 시도, Docker 환경, FFI를 사용할 수 없는 환경 | [Client Talk](/ko/packages/laravel-voicevox/client-talk) / [Client Song](/ko/packages/laravel-voicevox/client-song) |
| 네이티브 모드   | VOICEVOX CORE를 PHP FFI로 직접 호출 | 필요  | 고속화, 오프라인 실행, CLI 도구 통합            | [Native Talk](/ko/packages/laravel-voicevox/native-talk) / [Native Song](/ko/packages/laravel-voicevox/native-song) |
| 엔진 API 모드 | Laravel이 VOICEVOX 호환 API를 제공  | 필요  | API 서버 공개, 여러 클라이언트 연동             | [Engine Talk](/ko/packages/laravel-voicevox/engine-talk) / [Engine Song](/ko/packages/laravel-voicevox/engine-song) |

## 빠른 시작

클라이언트 모드 절차입니다.

<Steps>
  <Step title="패키지 설치">
    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```

    자세한 내용은 [설치와 설정](/ko/packages/laravel-voicevox/installation)을 확인하세요.
  </Step>

  <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="음성 합성 시도">
    ```php theme={null}
    use Revolution\Voicevox\Voicevox;

    $response = Voicevox::talk('안녕하세요, Laravel입니다.', id: 1)->generate(id: 1);
    $response->storeAs('output.wav');
    ```
  </Step>
</Steps>

## 주요 기능

### 음성 합성 (Talk)

```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);
```

### 노래 합성 (Song)

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

$score = Score::make([
    Note::make(length: 15),
    Note::make(length: Note::len(ticks: 480, bpm: 120), lyric: 'ド', key: 60),
    Note::make(length: Note::len(480, 120), lyric: 'レ', key: 62),
    Note::make(length: Note::len(960, 120), lyric: 'ミ', key: 64),
    Note::make(length: 2),
]);

$response = Voicevox::song($score)->generate(id: 3001);
```

### 사용자 사전과 프리셋

클라이언트 모드에서는 `Voicevox` 파사드를 사용해 공식 엔진 측의 사용자 사전이나 프리셋을 조작합니다.

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

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 3,
);

$presetId = Voicevox::addPreset([
    'id' => 0,
    'name' => 'ゆっくり丁寧',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.8,
    'pitchScale' => 0.0,
    'intonationScale' => 1.2,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);
```

### Laravel AI SDK 연동

```php theme={null}
use Laravel\Ai\Audio;

$audio = Audio::of('안녕하세요, Laravel입니다.')
    ->voice('ずんだもん')
    ->generate();

$audio->storeAs('output.wav');
```

## 다음 단계

* [설치와 설정](/ko/packages/laravel-voicevox/installation)
* [설정 레퍼런스](/ko/packages/laravel-voicevox/configuration)
* [Client Talk](/ko/packages/laravel-voicevox/client-talk)
* [Client Song](/ko/packages/laravel-voicevox/client-song)
* [클라이언트 모드 - 사용자 사전](/ko/packages/laravel-voicevox/client-user-dict)
* [클라이언트 모드 - 프리셋](/ko/packages/laravel-voicevox/client-presets)
* [Native Talk](/ko/packages/laravel-voicevox/native-talk)
* [Engine Talk](/ko/packages/laravel-voicevox/engine-talk)
* [네이티브 모드 - 사용자 사전](/ko/packages/laravel-voicevox/native-user-dict)
* [네이티브 모드 - 프리셋](/ko/packages/laravel-voicevox/native-presets)
* [AI SDK 연동](/ko/packages/laravel-voicevox/ai-sdk)


## Related topics

- [Laravel을 시작하기 전에 필요한 지식](/ko/true-tutorial.md)
- [시작하기 - GitHub Copilot SDK for Laravel](/ko/packages/laravel-copilot-sdk/getting-started.md)
- [Laravel Prompts](/ko/prompts.md)
- [GitHub Copilot SDK for Laravel](/ko/packages/laravel-copilot-sdk/index.md)
- [Laravel Scout](/ko/scout.md)