클라이언트 모드 - 사용자 사전 - VOICEVOX for Laravel

사용자 사전을 사용하면 고유명사나 전문 용어의 읽는 법을 공식 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로 공식 엔진을 실행하는 경우에도 컨테이너 내의 사용자 영역에 저장됩니다. 컨테이너를 재시작해도 같은 컨테이너를 계속 사용하는 동안에는 데이터가 유지됩니다. 다만 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

Docker에서는 공식 엔진의 사용자 영역(컨테이너 내)에 저장됩니다. 영속화가 필요한 경우, 컨테이너 내의 사용자 영역을 Docker volume에 마운트하세요.

GitHub Copilot

SDK

AI SDK

VOICEVOX

스타터 킷

피드·RSS

미들웨어

클라이언트 모드 - 사용자 사전 - VOICEVOX for Laravel

개요

사전 준비

기본적인 사용법

단어 추가

파라미터

전체 단어 조회

단어 업데이트

단어 삭제

사전 임포트

사전 등록 후의 음성 합성

Engine API와의 대응

네이티브 모드와의 차이

주의 사항

트러블슈팅

단어가 반영되지 않음

사전 파일 위치를 알 수 없음

​개요

​사전 준비

​기본적인 사용법

​단어 추가

​파라미터

​전체 단어 조회

​단어 업데이트

​단어 삭제

​사전 임포트

​사전 등록 후의 음성 합성

​Engine API와의 대응

​네이티브 모드와의 차이

​주의 사항

​트러블슈팅

​단어가 반영되지 않음

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

개요

사전 준비

기본적인 사용법

단어 추가

파라미터

전체 단어 조회

단어 업데이트

단어 삭제

사전 임포트

사전 등록 후의 음성 합성

Engine API와의 대응

네이티브 모드와의 차이

주의 사항

트러블슈팅

단어가 반영되지 않음

사전 파일 위치를 알 수 없음