> ## 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에 학습시킬 수 있습니다. 등록한 단어는 음성 합성 시에 적절한 발음으로 낭독됩니다.

## 개요

Laravel VOICEVOX의 사용자 사전 기능은 VOICEVOX Core의 UserDict를 이용한 네이티브 구현입니다. 사전 데이터는 JSON 형식으로 `storage/voicevox/user_dict.json`에 영속화됩니다.

<Info>
  공식 VOICEVOX 엔진과는 독립된 스토리지를 사용하므로, Laravel 측에서 등록한 단어는 공식 엔진 측에는 반영되지 않습니다 (반대 방향도 마찬가지입니다).
</Info>

## 설정

기본적으로 `storage/voicevox/user_dict.json`에 저장됩니다. 다른 경로를 사용하고 싶은 경우 `config/voicevox.php`에서 변경할 수 있습니다.

```php theme={null}
// config/voicevox.php

return [
    'core' => [
        'user_dict' => storage_path('voicevox/user_dict.json'),
    ],
];
```

## 기본적인 사용법

### 단어 추가

`dict()` 헬퍼의 `add()`로 단어를 등록합니다.

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

$uuid = dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// "-"가 없는 UUID가 반환됩니다
// 예: "550e8400e29b41d4a716446655440000"
```

#### 파라미터

* `surface` (필수): 표기
* `pronunciation` (필수): 읽는 법 (카타카나만)
* `accentType` (필수): 액센트 타입 (`0` = 평판, `1` 이상 = 액센트 위치)
* `wordType` (선택): 품사 (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`)
* `priority` (선택): 우선순위 (기본값 `5`)

#### 액센트 타입

* `0`: 평판 액센트
* `1`: 첫 번째 박자
* `2`: 두 번째 박자
* `3`: 세 번째 박자

### 단어 업데이트

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

dict()->update(
    wordUuid: '550e8400-e29b-41d4-a716-446655440000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);
```

### 단어 삭제

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

dict()->delete('550e8400-e29b-41d4-a716-446655440000');
```

### 전체 단어 조회

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

$words = dict()->all();
// 또는
$words = dict()->toArray();
```

### 사전 임포트

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

$json = file_get_contents('other_user_dict.json');
dict()->import($json, override: false);

// override: true라면 덮어쓰기
dict()->import($json, override: true);
```

### 사전 익스포트

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

$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
```

## Engine API를 통한 접근

Laravel VOICEVOX의 엔진 API를 실행하고 있는 경우, HTTP를 통해서도 사용자 사전을 조작할 수 있습니다. 공식 엔진으로 폴백하지 않고 네이티브 사전을 이용합니다.

### 전체 단어 조회

```bash theme={null}
curl http://localhost:50513/user_dict
```

### 단어 추가

```bash theme={null}
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
```

### 단어 업데이트

```bash theme={null}
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
```

### 단어 삭제

```bash theme={null}
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
```

### 사전 임포트

```bash theme={null}
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
  -H "Content-Type: application/json" \
  -d @other_dict.json
```

<Tip>
  `override=true`를 지정하면 기존 사전을 모두 삭제한 뒤 임포트합니다.
</Tip>

## 사전 등록 후의 음성 합성

사용자 사전에 등록한 단어는 음성 합성 시에 자동 참조됩니다.

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

dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = talk('Laravel로 개발하는 것은 즐겁습니다', id: 1)->generate(id: 1);
$response->storeAs('native', 'laravel.wav');
```

## 주의 사항

<Warning>
  `pronunciation`에는 카타카나만 지정하세요. 히라가나나 한자는 사용할 수 없습니다.
</Warning>

* Laravel판의 사용자 사전과 공식 VOICEVOX 엔진의 사용자 사전은 별도로 관리됩니다.
* 단어의 추가·업데이트·삭제는 즉시 JSON 파일에 저장됩니다.
* 액센트 타입을 모르는 경우에는 우선 `0` (평판)을 시도해 보세요.

## 트러블슈팅

### 단어가 반영되지 않음

1. 스토리지 디렉터리의 쓰기 권한을 확인하세요.
2. `storage/voicevox/user_dict.json`이 올바르게 생성되어 있는지 확인하세요.
3. 카타카나 표기가 올바른지 확인하세요.

### 사전 파일 위치를 알 수 없음

```php theme={null}
$path = config('voicevox.core.user_dict');
echo $path;
```

### 사전을 리셋하고 싶음

```bash theme={null}
rm storage/voicevox/user_dict.json
```

```php theme={null}
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
    unlink($path);
}
```


## Related topics

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