네이티브 모드 - 사용자 사전 - VOICEVOX for Laravel

VOICEVOX for Laravel의 네이티브 모드에서 사용자 사전을 이용하여 고유명사나 전문 용어의 읽는 법을 등록·업데이트·임포트하는 방법을 설명합니다.

​

사용자 사전이란

사용자 사전을 사용하면 고유명사나 전문 용어의 읽는 법을 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 (평판)을 시도해 보세요.

​

트러블슈팅

​

단어가 반영되지 않음

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

​

사전 파일 위치를 알 수 없음

$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);
}