사용자 사전을 사용하면 고유명사나 전문 용어의 읽는 법을 공식 VOICEVOX 엔진에 등록할 수 있습니다. 클라이언트 모드에서는 Laravel 측에 사전을 저장하지 않고, 연결 대상인 공식 엔진이 관리하는 사용자 사전 API를 그대로 이용합니다.
클라이언트 모드의 사용자 사전은 Voicevox 파사드에서 조작합니다. 내부에서는 공식 VOICEVOX 엔진의 /user_dict, /user_dict_word, /import_user_dict에 HTTP 요청을 보냅니다.
공식 엔진의 사전 데이터는 OS별 사용자 영역에 저장됩니다. VOICEVOX 앱(제품판) macOS 빌드에서는 통상 다음 위치에 저장됩니다.
~/Library/Application Support/voicevox-engine/user_dict.json
docker run --rm처럼 임시 컨테이너를 매번 새로 만드는 경우에는 컨테이너 종료 시에 사전이 사라집니다. 사전을 확실히 영속화하려면 Docker volume로 컨테이너 내의 사용자 영역을 마운트하세요.
네이티브 모드의 storage/voicevox/user_dict.json과는 별도로 관리됩니다. Laravel 측의 config('voicevox.core.user_dict')는 클라이언트 모드에서는 사용되지 않습니다.
사전 준비
공식 VOICEVOX 엔진을 실행합니다.
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
VOICEVOX_URL에서 변경할 수 있습니다.
VOICEVOX_URL=http://127.0.0.1:50021
기본적인 사용법
단어 추가
Voicevox::addWord()로 단어를 등록할 수 있습니다.
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 | 우선순위 |
전체 단어 조회
등록된 모든 단어를 조회할 수 있습니다.
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를 지정해 업데이트합니다.
use Revolution\Voicevox\Voicevox;
Voicevox::updateWord(
wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
surface: 'Laravel',
pronunciation: 'ラレベル',
accentType: 1,
);
단어 삭제
use Revolution\Voicevox\Voicevox;
Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');
사전 임포트
공식 엔진의 사용자 사전 형식 배열을 임포트할 수 있습니다. override: false (기본값)이라면 기존 단어는 유지되고 임포트된 단어가 추가됩니다.
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으로 저장합니다.
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
file_put_contents('exported_user_dict.json', $json);
사전 등록 후의 음성 합성
사용자 사전에 등록한 단어는 공식 엔진에서 음성 합성할 때 자동으로 참조됩니다.
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 같은 하이픈 있는 형식입니다.
트러블슈팅
단어가 반영되지 않음
- 공식 VOICEVOX 엔진이 실행되고 있는지 확인하세요.
VOICEVOX_URL이 올바른 연결 대상을 가리키고 있는지 확인하세요.- 읽는 법이 카타카나로 되어 있는지 확인하세요.
- Docker에서 다른 컨테이너를 다시 시작하고 있지 않은지 확인하세요.
사전 파일 위치를 알 수 없음
macOS 빌드판에서는 다음 위치를 확인하세요.
~/Library/Application Support/voicevox-engine/user_dict.json
