사용자 사전이란
사용자 사전을 사용하면 고유명사나 전문 용어의 읽는 법을 VOICEVOX에 학습시킬 수 있습니다. 등록한 단어는 음성 합성 시에 적절한 발음으로 낭독됩니다.
Laravel VOICEVOX의 사용자 사전 기능은 VOICEVOX Core의 UserDict를 이용한 네이티브 구현입니다. 사전 데이터는 JSON 형식으로 storage/voicevox/user_dict.json에 영속화됩니다.
공식 VOICEVOX 엔진과는 독립된 스토리지를 사용하므로, Laravel 측에서 등록한 단어는 공식 엔진 측에는 반영되지 않습니다 (반대 방향도 마찬가지입니다).
storage/voicevox/user_dict.json에 저장됩니다. 다른 경로를 사용하고 싶은 경우 config/voicevox.php에서 변경할 수 있습니다.
// config/voicevox.php
return [
'core' => [
'user_dict' => storage_path('voicevox/user_dict.json'),
],
];
기본적인 사용법
단어 추가
dict() 헬퍼의 add()로 단어를 등록합니다.
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: 세 번째 박자
단어 업데이트
use function Revolution\Voicevox\dict;
dict()->update(
wordUuid: '550e8400-e29b-41d4-a716-446655440000',
surface: 'Laravel',
pronunciation: 'ラレベル',
accentType: 1,
);
단어 삭제
use function Revolution\Voicevox\dict;
dict()->delete('550e8400-e29b-41d4-a716-446655440000');
전체 단어 조회
use function Revolution\Voicevox\dict;
$words = dict()->all();
// 또는
$words = dict()->toArray();
사전 임포트
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);
사전 익스포트
use function Revolution\Voicevox\dict;
$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
Engine API를 통한 접근
Laravel VOICEVOX의 엔진 API를 실행하고 있는 경우, HTTP를 통해서도 사용자 사전을 조작할 수 있습니다. 공식 엔진으로 폴백하지 않고 네이티브 사전을 이용합니다.
전체 단어 조회
curl http://localhost:50513/user_dict
단어 추가
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
단어 업데이트
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
단어 삭제
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
사전 임포트
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
-H "Content-Type: application/json" \
-d @other_dict.json
override=true를 지정하면 기존 사전을 모두 삭제한 뒤 임포트합니다.
사전 등록 후의 음성 합성
사용자 사전에 등록한 단어는 음성 합성 시에 자동 참조됩니다.
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');
주의 사항
pronunciation에는 카타카나만 지정하세요. 히라가나나 한자는 사용할 수 없습니다.
- Laravel판의 사용자 사전과 공식 VOICEVOX 엔진의 사용자 사전은 별도로 관리됩니다.
- 단어의 추가·업데이트·삭제는 즉시 JSON 파일에 저장됩니다.
- 액센트 타입을 모르는 경우에는 우선
0 (평판)을 시도해 보세요.
트러블슈팅
단어가 반영되지 않음
- 스토리지 디렉터리의 쓰기 권한을 확인하세요.
storage/voicevox/user_dict.json이 올바르게 생성되어 있는지 확인하세요.- 카타카나 표기가 올바른지 확인하세요.
사전 파일 위치를 알 수 없음
$path = config('voicevox.core.user_dict');
echo $path;
사전을 리셋하고 싶음
rm storage/voicevox/user_dict.json
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
unlink($path);
}
