Mit dem Benutzerwörterbuch können Sie die Aussprache von Eigennamen und Fachbegriffen in der offiziellen VOICEVOX-Engine registrieren. Im Client-Modus wird das Wörterbuch nicht auf Laravel-Seite gespeichert, sondern die Wörterbuch-API der verbundenen offiziellen Engine wird direkt verwendet.
Übersicht
Das Benutzerwörterbuch im Client-Modus wird über die Voicevox-Facade verwaltet. Intern werden HTTP-Requests an die Endpunkte /user_dict, /user_dict_word und /import_user_dict der offiziellen VOICEVOX-Engine gesendet.
Die Wörterbuchdaten der offiziellen Engine werden je nach Betriebssystem im Benutzerbereich gespeichert. In der macOS-Build-Version der VOICEVOX-Anwendung (Produktversion) ist der übliche Speicherort:
~/Library/Application Support/voicevox-engine/user_dict.json
docker run --rm jedes Mal einen temporären Container erstellen, geht das Wörterbuch beim Beenden verloren. Um das Wörterbuch zuverlässig persistent zu speichern, mounten Sie den Benutzerbereich des Containers über ein Docker-Volume.
Es handelt sich um eine separate Verwaltung vom Native-Modus mit storage/voicevox/user_dict.json. config('voicevox.core.user_dict') auf Laravel-Seite wird im Client-Modus nicht verwendet.
Vorbereitung
Starten Sie die offizielle VOICEVOX-Engine.
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
VOICEVOX_URL ändern.
VOICEVOX_URL=http://127.0.0.1:50021
Grundlegende Verwendung
Wort hinzufügen
Sie können mit Voicevox::addWord() ein Wort registrieren.
use Revolution\Voicevox\Voicevox;
$uuid = Voicevox::addWord(
surface: 'Laravel',
pronunciation: 'ララベル',
accentType: 0,
);
// Im Client-Modus wird eine UUID mit "-" zurückgegeben
// Beispiel: "a1b2c3d4-0000-0000-0000-000000000000"
Parameter
| Parameter | Typ | Beschreibung |
|---|
surface | string | Schreibweise (der tatsächliche Wort-String) |
pronunciation | string | Aussprache (nur Katakana) |
accentType | int | Akzenttyp (0 = flach, 1 oder mehr = Akzentposition) |
wordType | string|null | Wortart (COMMON_NOUN, PROPER_NOUN, VERB, ADJECTIVE, SUFFIX) |
priority | int|null | Priorität |
Alle Wörter abrufen
Sie können alle registrierten Wörter abrufen.
use Revolution\Voicevox\Voicevox;
$words = Voicevox::userDict();
/*
[
"a1b2c3d4-0000-0000-0000-000000000000" => [
"surface" => "Laravel",
"pronunciation" => "ララベル",
"accent_type" => 0,
"word_type" => "COMMON_NOUN",
"priority" => 5,
],
...
]
*/
Wort aktualisieren
Geben Sie die beim Hinzufügen zurückgegebene UUID an, um zu aktualisieren.
use Revolution\Voicevox\Voicevox;
Voicevox::updateWord(
wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
surface: 'Laravel',
pronunciation: 'ラレベル',
accentType: 1,
);
Wort löschen
use Revolution\Voicevox\Voicevox;
Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');
Wörterbuch importieren
Sie können Arrays im Benutzerwörterbuchformat der offiziellen Engine importieren. Bei override: false (Standard) bleiben bestehende Wörter erhalten und die importierten werden hinzugefügt.
use Revolution\Voicevox\Voicevox;
$words = json_decode(file_get_contents('other_user_dict.json'), true);
Voicevox::importUserDict($words, override: false);
// Bei override: true wird das bestehende Wörterbuch ersetzt
Voicevox::importUserDict($words, override: true);
Voicevox::userDict() als JSON.
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
file_put_contents('exported_user_dict.json', $json);
Sprachsynthese nach der Wörterbuchregistrierung
Wörter, die im Benutzerwörterbuch registriert sind, werden bei der Sprachsynthese durch die offizielle Engine automatisch berücksichtigt.
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');
Zuordnung zur Engine-API
Die Methoden der Voicevox-Facade entsprechen den APIs der offiziellen Engine.
| Laravel | Offizielle Engine-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 |
Unterschiede zum Native-Modus
| Aspekt | Client-Modus | Native-Modus |
|---|
| Nutzung | Voicevox-Facade | dict()-Helper |
| Speicherort | Benutzerbereich der offiziellen Engine | storage/voicevox/user_dict.json von Laravel |
| Beispiel unter macOS | ~/Library/Application Support/voicevox-engine/user_dict.json | storage/voicevox/user_dict.json |
| UUID beim Hinzufügen | Mit - | Von Core ohne - |
| Engine-Prozess | Erforderlich | Nicht erforderlich (FFI erforderlich) |
Hinweise
Geben Sie pronunciation in Katakana an. Hiragana oder Kanji sind nicht zulässig.
- Im Client-Modus wird das Wörterbuch auf der Seite der offiziellen Engine aktualisiert. Es wird nicht im
storage des Laravel-Projekts gespeichert.
- Bei temporären Containern (z. B.
docker run --rm) geht das Wörterbuch beim Beenden des Containers verloren.
- Die beim Hinzufügen zurückgegebene UUID hat das Format mit Bindestrich wie
a1b2c3d4-0000-0000-0000-000000000000.
Fehlerbehebung
Wörter werden nicht übernommen
- Prüfen Sie, ob die offizielle VOICEVOX-Engine läuft.
- Prüfen Sie, ob
VOICEVOX_URL auf das richtige Ziel zeigt.
- Prüfen Sie, ob die Aussprache in Katakana geschrieben ist.
- Prüfen Sie, ob Sie in Docker nicht einen anderen Container neu gestartet haben.
Der Speicherort der Wörterbuchdatei ist unklar
In der macOS-Build-Version prüfen Sie folgenden Ort.
~/Library/Application Support/voicevox-engine/user_dict.json
Zuletzt geändert am 13. Juli 2026
