> ## 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 측에 사전을 저장하지 않고, 연결 대상인 공식 엔진이 관리하는 사용자 사전 API를 그대로 이용합니다. ## 개요 클라이언트 모드의 사용자 사전은 `Voicevox` 파사드에서 조작합니다. 내부에서는 공식 VOICEVOX 엔진의 `/user_dict`, `/user_dict_word`, `/import_user_dict`에 HTTP 요청을 보냅니다. 공식 엔진의 사전 데이터는 OS별 사용자 영역에 저장됩니다. VOICEVOX 앱(제품판) macOS 빌드에서는 통상 다음 위치에 저장됩니다. ```text theme={null} ~/Library/Application Support/voicevox-engine/user_dict.json ``` Docker로 공식 엔진을 실행하는 경우에도 컨테이너 내의 사용자 영역에 저장됩니다. 컨테이너를 재시작해도 같은 컨테이너를 계속 사용하는 동안에는 데이터가 유지됩니다. 다만 `docker run --rm`처럼 임시 컨테이너를 매번 새로 만드는 경우에는 컨테이너 종료 시에 사전이 사라집니다. 사전을 확실히 영속화하려면 Docker volume로 컨테이너 내의 사용자 영역을 마운트하세요. 네이티브 모드의 `storage/voicevox/user_dict.json`과는 별도로 관리됩니다. Laravel 측의 `config('voicevox.core.user_dict')`는 클라이언트 모드에서는 사용되지 않습니다. ## 사전 준비 공식 VOICEVOX 엔진을 실행합니다. ```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 ``` 연결 대상은 `VOICEVOX_URL`에서 변경할 수 있습니다. ```env theme={null} VOICEVOX_URL=http://127.0.0.1:50021 ``` ## 기본적인 사용법 ### 단어 추가 `Voicevox::addWord()`로 단어를 등록할 수 있습니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $uuid = Voicevox::addWord( surface: 'Laravel', pronunciation: 'ララベル', accentType: 0, ); // 클라이언트 모드에서는 "-"가 있는 UUID가 반환됩니다 // 예: "a1b2c3d4-0000-0000-0000-000000000000" ``` #### 파라미터 | 파라미터 | 타입 | 설명 | | --------------- | ------------ | ---------------------------------------------------------------- | | `surface` | string | 표기 (실제 단어의 문자열) | | `pronunciation` | string | 읽는 법 (카타카나만) | | `accentType` | int | 액센트 타입 (0 = 평판, 1 이상 = 액센트 위치) | | `wordType` | string\|null | 품사 (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`) | | `priority` | int\|null | 우선순위 | ### 전체 단어 조회 등록된 모든 단어를 조회할 수 있습니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $words = Voicevox::userDict(); /* [ "a1b2c3d4-0000-0000-0000-000000000000" => [ "surface" => "Laravel", "pronunciation" => "ララベル", "accent_type" => 0, "word_type" => "COMMON_NOUN", "priority" => 5, ], ... ] */ ``` ### 단어 업데이트 추가 시 반환된 UUID를 지정해 업데이트합니다. ```php theme={null} use Revolution\Voicevox\Voicevox; Voicevox::updateWord( wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000', surface: 'Laravel', pronunciation: 'ラレベル', accentType: 1, ); ``` ### 단어 삭제 ```php theme={null} use Revolution\Voicevox\Voicevox; Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000'); ``` ### 사전 임포트 공식 엔진의 사용자 사전 형식 배열을 임포트할 수 있습니다. `override: false` (기본값)이라면 기존 단어는 유지되고 임포트된 단어가 추가됩니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $words = json_decode(file_get_contents('other_user_dict.json'), true); Voicevox::importUserDict($words, override: false); // override: true라면 기존 사전을 대체 Voicevox::importUserDict($words, override: true); ``` 사전을 익스포트하려면 `Voicevox::userDict()`의 결과를 JSON으로 저장합니다. ```php theme={null} $json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE); file_put_contents('exported_user_dict.json', $json); ``` ## 사전 등록 후의 음성 합성 사용자 사전에 등록한 단어는 공식 엔진에서 음성 합성할 때 자동으로 참조됩니다. ```php theme={null} use Revolution\Voicevox\Voicevox; Voicevox::addWord( surface: 'Laravel', pronunciation: 'ララベル', accentType: 0, ); $response = Voicevox::talk('Laravel로 개발하는 것은 즐겁습니다', id: 1)->generate(id: 1); $response->storeAs('client', 'laravel.wav'); ``` ## Engine API와의 대응 `Voicevox` 파사드의 각 메서드는 공식 엔진의 API에 대응합니다. | Laravel | 공식 엔진 API | | ---------------------------- | ------------------------------------ | | `Voicevox::userDict()` | `GET /user_dict` | | `Voicevox::addWord()` | `POST /user_dict_word` | | `Voicevox::updateWord()` | `PUT /user_dict_word/{word_uuid}` | | `Voicevox::deleteWord()` | `DELETE /user_dict_word/{word_uuid}` | | `Voicevox::importUserDict()` | `POST /import_user_dict` | ## 네이티브 모드와의 차이 | 항목 | 클라이언트 모드 | 네이티브 모드 | | ---------- | -------------------------------------------------------------- | ------------------------------------------ | | 이용 방법 | `Voicevox` 파사드 | `dict()` 헬퍼 | | 저장 위치 | 공식 엔진의 사용자 영역 | Laravel의 `storage/voicevox/user_dict.json` | | macOS의 예 | `~/Library/Application Support/voicevox-engine/user_dict.json` | `storage/voicevox/user_dict.json` | | 추가 시의 UUID | `-` 있음 | Core에서는 `-` 없음 | | 엔진 프로세스 | 필요 | 불필요 (FFI 필요) | ## 주의 사항 `pronunciation`은 카타카나로 지정하세요. 히라가나나 한자는 사용할 수 없습니다. * 클라이언트 모드에서는 공식 엔진 측의 사전이 업데이트됩니다. Laravel 프로젝트의 `storage`에는 저장되지 않습니다. * `docker run --rm` 등 임시 컨테이너를 매번 새로 만드는 경우, 컨테이너 종료 시에 사전이 사라집니다. * 추가 시 반환되는 UUID는 `a1b2c3d4-0000-0000-0000-000000000000` 같은 하이픈 있는 형식입니다. ## 트러블슈팅 ### 단어가 반영되지 않음 1. 공식 VOICEVOX 엔진이 실행되고 있는지 확인하세요. 2. `VOICEVOX_URL`이 올바른 연결 대상을 가리키고 있는지 확인하세요. 3. 읽는 법이 카타카나로 되어 있는지 확인하세요. 4. Docker에서 다른 컨테이너를 다시 시작하고 있지 않은지 확인하세요. ### 사전 파일 위치를 알 수 없음 macOS 빌드판에서는 다음 위치를 확인하세요. ```text theme={null} ~/Library/Application Support/voicevox-engine/user_dict.json ``` Docker에서는 공식 엔진의 사용자 영역(컨테이너 내)에 저장됩니다. 영속화가 필요한 경우, 컨테이너 내의 사용자 영역을 Docker volume에 마운트하세요. ## Related topics - [클라이언트 모드 - 프리셋 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-presets.md) - [클라이언트 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-talk.md) - [클라이언트 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-song.md) - [엔진 API 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-talk.md) - [네이티브 모드 - 사용자 사전 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-user-dict.md)