Spécification du fichier .vvproj - VOICEVOX for Laravel

Objectif

Utiliser tel quel le .vvproj de l’éditeur VOICEVOX pour regénérer Talk et Song depuis Laravel.

Structure de haut niveau

.vvproj est un JSON UTF-8. Il conserve Talk et Song dans un même fichier.

{
  "appVersion": "0.25.2",
  "talk": {
    "audioKeys": [],
    "audioItems": {}
  },
  "song": {
    "tpqn": 480,
    "tempos": [],
    "timeSignatures": [],
    "tracks": {},
    "trackOrder": []
  }
}

Clé	Contenu
`appVersion`	Version de l’éditeur au moment de la sauvegarde
`talk`	Données Talk (`audioKeys` + `audioItems`)
`song`	Données Song (tempo, mesure, ensemble de pistes)

Section `talk`

talk.audioKeys est un tableau ordonné ; talk.audioItems est un Record indexé par ID.

{
  "audioKeys": ["audio-item-uuid"],
  "audioItems": {
    "audio-item-uuid": {
      "text": "ずんだもんなのだ",
      "voice": {
        "engineId": "engine-uuid",
        "speakerId": "speaker-uuid",
        "styleId": 3
      },
      "query": {
        "accentPhrases": [],
        "speedScale": 1,
        "pitchScale": 0
      },
      "presetKey": "preset-uuid"
    }
  }
}

TalkAudioItem

Clé	Contenu
`text`	Texte saisi
`voice.engineId`	ID du moteur (correspond à `/engine_manifest`)
`voice.speakerId`	UUID du locuteur
`voice.styleId`	ID de style. Passé tel quel à `/synthesis?speaker={styleId}`
`query`	Équivalent à un `AudioQuery`
`presetKey`	ID de preset dans l’éditeur. Pour les presets côté Laravel, consultez Presets

Si query est déjà stocké dans le .vvproj, on peut passer directement à la synthèse sans réexécuter /audio_query.

`accentPhrases`

Clé	Contenu
`moras`	Tableau de mores (les éléments comme `consonant` peuvent être omis)
`accent`	Position de l’accent (indexée à partir de 1)
`pauseMora`	Peut apparaître pour insérer un silence après une ponctuation
`isInterrogative`	Drapeau d’interrogation

Section `song`

{
  "tpqn": 480,
  "tempos": [{ "position": 0, "bpm": 120 }],
  "timeSignatures": [{ "measureNumber": 1, "beats": 4, "beatType": 4 }],
  "tracks": {
    "track-uuid": {
      "name": "無名トラック",
      "singer": { "engineId": "engine-uuid", "styleId": 3003 },
      "notes": []
    }
  },
  "trackOrder": ["track-uuid"]
}

Clé	Contenu
`tpqn`	Ticks Per Quarter Note. Standard : 480
`tempos`	Table des tempos (`position` en ticks)
`timeSignatures`	Table des signatures rythmiques (`measureNumber` commence à 1)
`tracks`	Record indexé par ID de piste
`trackOrder`	Ordre d’affichage et de lecture. Doit correspondre à l’ensemble des clés de `tracks`

Track

Clé	Contenu
`singer.styleId`	ID finalement passé à `/frame_synthesis?speaker={styleId}`
`notes`	Tableau de notes
`keyRangeAdjustment`	Ajustement de tessiture en demi-tons
`volumeRangeAdjustment`	Ajustement de volume
`pitchEditData` / `volumeEditData`	Données d’édition par frame
`phonemeTimingEditData`	Édition de la temporisation des phonèmes par ID de note
`solo` / `mute`	Utilisés pour déterminer les pistes à lire

Note

Clé	Contenu
`id`	ID de la note (unique)
`position`	Tick de début
`duration`	Longueur en ticks
`noteNumber`	Numéro de note MIDI
`lyric`	Paroles

Conversion tick / seconde / frame

Avec un tempo unique, la conversion est la suivante.

seconds = ticks / tpqn * 60 / bpm
frames = round(seconds * frameRate)

Avec plusieurs tempos, cumulez les segments en parcourant tempos par position croissant.

function ticksToSeconds(int $targetTick, int $tpqn, array $tempos): float
{
    $seconds = 0.0;
    $currentTick = 0;

    foreach ($tempos as $index => $tempo) {
        $nextTick = $tempos[$index + 1]['position'] ?? $targetTick;
        $segmentEnd = min($targetTick, $nextTick);

        if ($segmentEnd <= $currentTick) {
            break;
        }

        $bpm = $tempo['bpm'];
        $seconds += (($segmentEnd - $currentTick) / $tpqn) * (60 / $bpm);
        $currentTick = $segmentEnd;
    }

    return $seconds;
}

Pour l’implémentation de la conversion de ticks vers une longueur en frames via le helper Note::len(), consultez Détails Score et Note.

Flux de génération de la voix Song

Précautions pour l’édition directe

Faites toujours correspondre l’ensemble des clés de tracks et trackOrder
Synchronisez de la même manière talk.audioKeys et talk.audioItems
Respectez position >= 0, duration >= 1 et noteNumber dans 0..127
Habituellement tempos[0].position vaut 0 et timeSignatures[0].measureNumber vaut 1
Conservez si possible les clés inconnues à la réécriture pour ne pas casser la compatibilité avec les versions futures

Exemple de code Laravel

Exemple minimal pour charger un .vvproj et générer Talk et Song.

use Illuminate\Support\Facades\Storage;
use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Song\Note;
use Revolution\Voicevox\Song\Score;
use Revolution\Voicevox\Voicevox;

$project = json_decode(
    Storage::disk('local')->get('voicevox/sample.vvproj'),
    true,
    flags: JSON_THROW_ON_ERROR,
);

// Talk : synthèse directe à partir de la query stockée
foreach ($project['talk']['audioKeys'] as $audioKey) {
    $item = $project['talk']['audioItems'][$audioKey];

    Voicevox::talk($item['text'], id: $item['voice']['styleId'])
        ->tap(fn (TalkAudioQuery $talk) => $talk->audioQuery = array_replace($talk->audioQuery, $item['query']))
        ->generate(id: $item['voice']['styleId'])
        ->storeAs('vvproj/talk', "{$audioKey}.wav");
}

// Song : ici on convertit la `duration` de la première piste en frame_length et on génère
$trackId = $project['song']['trackOrder'][0];
$track = $project['song']['tracks'][$trackId];
$bpm = $project['song']['tempos'][0]['bpm'] ?? 120;

$score = Score::make([
    Note::make(length: 15, lyric: '', key: null),
    ...collect($track['notes'])->map(
        fn (array $note) => Note::make(
            length: Note::len(ticks: $note['duration'], bpm: $bpm),
            lyric: $note['lyric'] ?? 'ら',
            key: $note['noteNumber'],
            id: $note['id'] ?? null,
        ),
    )->all(),
    Note::make(length: 2, lyric: '', key: null),
]);

Voicevox::song($score, teacher: 6000)
    ->generate(id: $track['singer']['styleId'])
    ->storeAs('vvproj/song', "{$trackId}.wav");

​Objectif

​Structure de haut niveau

​Section talk

​TalkAudioItem

​accentPhrases

​Section song

​Track

​Note

​Conversion tick / seconde / frame

​Flux de génération de la voix Song

​Précautions pour l’édition directe

​Exemple de code Laravel