Aller au contenu

Intégration Wwise (LibrettoWwise)

LibrettoWwise est une extension optionnelle, publiée séparément de Libretto. Elle route l'audio d'un dialogue — à la fois les aperçus TTS temporaires et la voix enregistrée finale — à travers Audiokinetic Wwise au lieu des assets USoundBase natifs d'Unreal.

Elle est livrée à part du plugin Libretto principal, à dessein : la plupart des projets n'utilisent pas Wwise, et l'intégration introduit une dépendance forte au plugin Audiokinetic Wwise. Si votre projet utilise Wwise pour l'audio et que vous avez besoin de LibrettoWwise, contactez-nous sur Discord — il n'est pas disponible directement sur Fab.

Prérequis — le plugin Audiokinetic Wwise

LibrettoWwise nécessite que le plugin Audiokinetic Wwise pour Unreal soit installé et activé dans votre projet, et qu'un projet Wwise soit connecté via WAAPI (la Wwise Authoring API). Installez Wwise et configurez-le dans votre projet comme documenté par Audiokinetic avant d'activer LibrettoWwise. L'import des voix et l'interrogation des durées de son au moment de la génération requièrent tous deux que Wwise soit lancé et connecté.

Noms de classes

LibrettoWwise est publié comme son propre plugin. Ses deux classes concrètes sont ULBRWwiseAudioAsset (sous-classe de ULBRAudioAsset) et ULBRWwiseTrackGenerator (sous-classe de ULBRAudioTrackGenerator) ; ses réglages vivent dans ULBRWwiseSettings (catégorie Libretto – Wwise). Ces noms sont vérifiés contre le source LibrettoWwise.

Comment cela s'articule avec Libretto

Libretto abstrait « d'où vient l'audio » derrière deux points d'extension, si bien qu'un backend audio peut être remplacé sans toucher au reste du pipeline :

  • L'asset audio. La classe de base abstraite ULBRAudioAsset masque la classe audio concrète au générateur. Le backend par défaut utilise des assets USoundBase d'Unreal ; LibrettoWwise fournit à la place une sous-classe adossée à Wwise. La classe de base anticipe explicitement des backends alternatifs tels que Wwise ou FMod.
  • Le générateur de piste audio. La classe de base ULBRAudioTrackGenerator produit la piste audio dans chaque asset Sequencer généré. LibrettoWwise fournit une sous-classe consciente de Wwise qui pose les bons événements Wwise sur la piste.

Activer l'extension revient donc essentiellement à pointer les réglages de Libretto vers les deux classes Wwise.

Activer LibrettoWwise (une fois par projet)

Obtenir LibrettoWwise

LibrettoWwise n'est pas disponible sur Fab. Contactez-nous sur Discord pour l'obtenir.

  1. Ajoutez le plugin LibrettoWwise à votre projet (aux côtés du plugin Libretto principal) et activez-le, en même temps que le plugin Audiokinetic Wwise dont il dépend.

  2. Connectez Unreal à Wwise. Votre projet Wwise ouvert, Unreal affiche un panneau Wwise Browser ; l'indicateur en bas vous dit si Unreal est connecté à l'application Wwise. Pour qu'il se connecte automatiquement au démarrage, cochez Auto Connect to WAAPI dans les project settings.

  3. Définissez la classe d'asset audio. Dans Project Settings ▸ Libretto, réglez AudioAssetClass sur l'asset audio Wwise (ULBRWwiseAudioAsset). Cela remplace l'asset par défaut basé sur USoundBase.

  4. Remplacez le générateur de piste audio. Dans Project Settings ▸ Libretto – Sequence Generator, remplacez le LBRAudioTrackGenerator par défaut dans la liste des générateurs par le générateur de piste Wwise (ULBRWwiseTrackGenerator).

  5. Configurez les racines Wwise. Une catégorie de réglages Libretto – Wwise contient les chemins utilisés lors de l'import dans le projet Wwise et lors de la création des événements de lecture :

    Réglage Rôle
    Text to Speech Wwise Root Chemin racine sous lequel les fichiers audio TTS sont importés dans Wwise.
    Voice Wwise Root Chemin racine sous lequel les fichiers de voix enregistrée finale sont importés dans Wwise.
    Text to Speech Events Wwise Root Chemin sous lequel les événements de lecture des voix TTS sont créés.
    Voice Events Wwise Root Chemin sous lequel les événements de lecture des voix finales sont créés.
    Import Language La langue déclarée à Wwise au moment de l'import.

Une fois ces réglages en place, la génération produit de façon transparente des assets Wwise et des pistes audio adossées à Wwise à la place de celles natives d'Unreal. Les flux TTS et enregistrement restent par ailleurs inchangés.

Comment fonctionne l'import de voix dans Wwise

Cette section explique les mécaniques pour quiconque étend ou débogue le système. L'asset audio Wwise concret (ULBRWwiseAudioAsset) est une sous-classe de ULBRAudioAsset et est câblé directement dans la génération via les générateurs Text-to-Speech. Wwise doit être lancé et connecté pour que tout cela fonctionne.

Le point d'entrée est la fonction d'import de la classe de base — ImportWavFile — qui prend le chemin d'un fichier .wav plus un flag ELBRAudioType indiquant s'il doit être traité comme une source de voix finale ou une source TTS temporaire. (Le format n'est pas codé en dur sur WAV, d'autres formats devraient donc fonctionner aussi.)

La sous-classe Wwise pilote WAAPI comme suit :

  1. Elle appelle ak.wwise.core.audio.import pour importer le fichier en tant qu'objet Sound Voice, sous un répertoire dérivé du chemin relatif du dialogue — la même disposition relative que celle utilisée lors de la génération des assets Sequencer. Le fichier original, le Sound Voice et l'événement de lecture atterrissent tous sous ce même chemin relatif.

  2. Nommage. Le fichier original conserve son nom. Le Sound Voice est nommé par ULBRCoreUtils::GetTtsAssetGeneratedName (pour les sources TTS) ou ULBRCoreUtils::GetVoiceAssetGeneratedName (pour les voix finales) — la convention VX_DialogueName_ID. L'événement de lecture généré est le nom du Sound Voice suffixé de _Play.

  3. Elle appelle ak.wwise.core.project.save puis ak.wwise.core.soundbank.generate (plateforme Windows uniquement) pour persister le projet et rafraîchir les données de SoundBank.

  4. Enfin, les assets Unreal équivalents sont créés en suivant la même convention de nommage, afin que le contenu Sequencer généré puisse les référencer.

Les événements _Play

Chaque voix importée reçoit un événement <VX_DialogueName_ID>_Play correspondant. Ce sont eux que le générateur de piste Wwise place sur la piste audio, et ce sont eux qui jouent la ligne à l'exécution.

Connexion requise à la génération

Parce que l'import et les requêtes de durée passent tous deux par WAAPI, générer (ou régénérer) un dialogue avec le backend Wwise requiert que l'application Wwise soit ouverte et connectée. Si la génération signale de l'audio manquant ou des lignes de longueur nulle, vérifiez d'abord la connexion du Wwise Browser.