Specifica del file .vvproj - VOICEVOX for Laravel

Specifica pratica per caricare il JSON .vvproj dell’editor VOICEVOX e generare talk e song in Laravel.

​

Obiettivo

Sfruttare direttamente i file .vvproj dell’editor VOICEVOX per rigenerare talk e song in Laravel.

​

Struttura di primo livello

.vvproj è JSON in UTF-8. Talk e song sono salvati nello stesso file.

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

Chiave	Contenuto
appVersion	Versione dell’editor al momento del salvataggio
talk	Dati per il talk (audioKeys + audioItems)
song	Dati per il song (tempo, tempo in chiave, tracce)

​

Sezione talk

talk.audioKeys è un array ordinato, talk.audioItems è un Record con l’ID come chiave.

{
  "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

Chiave	Contenuto
text	Testo di input
voice.engineId	ID engine (corrisponde a /engine_manifest)
voice.speakerId	UUID del parlante
voice.styleId	ID stile. Da passare così com’è a /synthesis?speaker={styleId}
query	Equivalente ad AudioQuery
presetKey	ID preset dell’editor. Per i preset lato Laravel consulta Preset

Se .vvproj contiene già query, puoi passare direttamente alla sintesi senza rieseguire /audio_query.

​

accentPhrases

Chiave	Contenuto
moras	Array di mora (le consonant possono essere omesse)
accent	Posizione dell’accento (partendo da 1)
pauseMora	Può comparire quando si inseriscono silenzi in corrispondenza di punteggiatura ecc.
isInterrogative	Flag di interrogativa

​

Sezione 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"]
}

Chiave	Contenuto
tpqn	Ticks Per Quarter Note. Il valore standard è 480
tempos	Mappa dei tempi (position in tick)
timeSignatures	Mappa dei tempi in chiave (measureNumber parte da 1)
tracks	Record con l’ID della traccia come chiave
trackOrder	Ordine di visualizzazione/riproduzione. Deve coincidere con l’insieme delle chiavi di tracks

​

Track

Chiave	Contenuto
singer.styleId	ID da passare infine a /frame_synthesis?speaker={styleId}
notes	Array di note
keyRangeAdjustment	Aggiustamento della tonalità in semitoni
volumeRangeAdjustment	Aggiustamento del volume
pitchEditData / volumeEditData	Dati di modifica a livello di frame
phonemeTimingEditData	Modifiche di timing dei fonemi per ciascun Note ID
solo / mute	Utilizzati per determinare le tracce oggetto di riproduzione

​

Note

Chiave	Contenuto
id	ID della nota (univoco)
position	Tick di inizio nota
duration	Durata della nota in tick
noteNumber	Numero di nota MIDI
lyric	Testo

​

Conversione tra tick, secondi e frame

Con tempo unico si converte così:

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

Con cambi di tempo, somma i segmenti scorrendo tempos in ordine crescente di position.

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

Per l’implementazione della conversione da tick a lunghezza di frame con l’helper Note::len(), consulta Dettagli di Score e Note.

​

Flusso di generazione audio per il song

​

Attenzioni nella modifica diretta

• L’insieme delle chiavi di tracks deve sempre coincidere con trackOrder
• Analogamente sincronizza talk.audioKeys e talk.audioItems
• Mantieni position >= 0, duration >= 1 e noteNumber in 0..127
• Di solito tempos[0].position è 0 e timeSignatures[0].measureNumber è 1
• Se possibile, conserva le chiavi sconosciute nel risalvataggio per non rompere la compatibilità con versioni future

​

Esempio in codice Laravel

Esempio minimo per caricare un .vvproj e generare talk e 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: sintetizza usando direttamente la query salvata
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: qui convertiamo la duration della prima traccia in frame_length e generiamo
$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");