Wwise 2023.1 constitue la plus importante mise à jour de l'API de création Wwise (WAAPI) depuis l'introduction de l'API en 2017. Si vous n'avez pas déjà vu la liste des Nouveautés de Wwise 2023.1, je vous invite à y jeter un coup d'œil. La liste des changements concernant WAAPI est plutôt longue. Dans cet article, nous allons regarder de plus près certains des changements que nous avons faits.

Mais qu'est-ce que WAAPI ?

WAAPI est utilisé pour communiquer avec l'application Wwise Authoring à partir d'une application externe, comme un script Python ou un programme C++. Si vous voulez en savoir plus, veuillez consulter cette page : https://www.audiokinetic.com/en/library/edge/?source=sdk&id=waapi.html.

Les tâches courantes que vous pouvez effectuer avec WAAPI sont les suivantes :

• Importer des fichiers audio
• Créer des structures d'objets
• Générer des SoundBanks
• Interroger un projet (avec WAQL)
• et bien plus encore !

En fait, vous avez peut-être déjà utilisé WAAPI sans le savoir. WAAPI est utilisé en arrière-plan dans les situations suivantes :

• Transfert de REAPER à Wwise :
• Audiokinetic ReaWwise (https://github.com/audiokinetic/ReaWwise) 
• LKC GRIM SYNC (https://www.lkctools.com/grimsync) 
• Intégrations dans les moteurs de jeu :
• Intégration Wwise dans Unreal
• Intégration Wwise dans Unity
• Gestion des fichiers audio :
• Basehead - Intégration Wwise (https://baseheadinc.com/)
• Soundly - Intégration Wwise (https://getsoundly.com/) 
• Soundminer - Intégration Wwise (https://store.soundminer.com/)

En outre, l'intégration de WAAPI dans un pipeline de développement de jeux est un bon moyen d'automatiser certaines tâches et d'améliorer la qualité des données dans votre flux de travail quotidien.

Nos objectifs pour cette version

Avec chaque version de Wwise, nous essayons de trouver un équilibre entre les commentaires des utilisateurs et notre propre feuille de route. Pour cette version spécifique, l'un des principaux commentaires des usagers concernait l'utilisation de WAAPI dans un environnement comprenant un logiciel de contrôle de versions. La deuxième chose, qui était aussi en concordance avec notre feuille de route, était d'augmenter les fonctions couvertes par WAAPI par une refonte de certains de nos modèles de données, incluant les objets de musique interactive. Nous reviendrons sur les objets musicaux plus tard dans cet article, mais commençons par le contrôle de versions !

Support du logiciel de contrôle de versions

Lorsque nous avons initialement développé WAAPI en 2017, il y avait quelques éléments que nous avons dû couper afin de livrer notre produit minimum viable (MVP). L'un de ces éléments était la prise en charge du contrôle de versions. Maintenant que WAAPI s'est intégré à tant de pipelines de nos utilisateurs, nous devions combler cette lacune.

Voici la liste des points que nous souhaitions aborder :

• Blocage des pop-ups lors de l'importation de fichiers audio. Un exemple simple est que lorsque vous utilisez ReaWwise, vous obtenez des pop-ups concernant le contrôle de versions dans Wwise chaque fois que vous effectuez un rendu à partir de REAPER, ce qui bloque l'interface de REAPER, et entraîne une mauvaise expérience utilisateur.
• Création, suppression, déplacement et renommage d'une Work Unit. Tout ce qui implique des opérations sur le système de fichiers doit être enregistré dans le contrôle de versions. De nombreuses fonctions WAAPI peuvent créer des Work Units.
• Contrôle de versions depuis la ligne de commande. Le contrôle de versions au complet n'était pas disponible lorsque vous utilisiez WwiseConsole.exe.
• Gestion des fichiers audio. Il n'était pas possible d'automatiser la réorganisation des fichiers audio du dossier Originals. Le File Manager était la seule façon de déplacer ou de renommer des fichiers audio sans endommager le projet. Dans le cas de projets de grande envergure, l'organisation automatisée des ressources est très importante.

Pour atteindre ces objectifs, nous avons dû revoir le fonctionnement des plugins de contrôle de versions. L'objectif principal était que toutes nos API soient silencieuses et entièrement compatibles avec le contrôle de versions.

Stratégie de test

Avant de commencer à travailler, nous avons dû réfléchir à une stratégie de test. Tester le contrôle de versions est toujours une tâche très fastidieuse qui ne doit pas être négligée. L'ampleur de nos modifications était telle que nous aurions pu facilement briser quelque chose sans nous en rendre compte. La bonne nouvelle, c'est que les fonctionnalités que nous avons ajoutées nous permettent d'automatiser les tests, ce qui n'était pas possible auparavant.

Pour nous, il était donc naturel de prendre en charge Perforce dans notre cadre de test automatisé. Et puisque toutes nos fonctions WAAPI étaient déjà couvertes par le cadre de test, nous avions juste à effectuer la même approche avec les nouvelles fonctions de contrôle de versions, afin d'être sûrs de nos changements.

Interface utilisateur

Tout d'abord, nous devions contrôler l'interface utilisateur créée par les plugins du logiciel de contrôle de versions. Ce sont les principaux obstacles à l'automatisation. Il y avait deux types de fenêtres pop-up : 

• Les fenêtres contextuelles personnalisées, comme la boîte de dialogue de Check Out (image ci-dessous)
• La fenêtre de log du logiciel de contrôle de versions

Chaque fois que nous retirions une boîte de dialogue, nous devions fournir une option équivalente dans les fonctions WAAPI pour qu'elles effectuent automatiquement un Check Out ou un Mark for Add sur les fichiers. En fin de compte, un total de 10 fonctions WAAPI différentes supportent désormais les opérations automatique de contrôle de versions :

• ak.wwise.console.project.open
• ak.wwise.ui.project.open
• ak.wwise.core.audio.import
• ak.wwise.core.audio.importTabDelimited
• ak.wwise.core.object.copy
• ak.wwise.core.object.create
• ak.wwise.core.object.delete
• ak.wwise.core.object.move
• ak.wwise.core.object.set
• ak.wwise.core.project.save

Ajouter le support du contrôle de versions à toutes ces APIs n'a pas été une tâche facile. Il y avait tellement de chemins de code à modifier au cœur de Wwise Authoring. Au moins, nous avions déjà une bonne couverture de l'automatisation des tests, mais c'était une bonne occasion d'élargir cette couverture lors de la manipulation des Work Units.

Deuxièmement, nous devions trouver un remplacement pour les fenêtres de dialogue du log. Pour cela, nous avons redirigé tous les messages de contrôle de versions vers notre fenêtre Logs, pour laquelle nous avons créé un nouvel onglet (Source Control) :

La bonne nouvelle est que le log centralisé était déjà exposé dans WAAPI. Nous avons simplement ajouté un nouveau canal à l'API.

Pousser l'automatisation jusqu'à ses limites

Ainsi, cela permettait de couvrir la plupart des opérations indirectes concernant le contrôle de versions. Par exemple, la création d'un objet Work Unit avec ak.wwise.core.object.set déclencherait l'opération Add sur le fichier WWU associé. Mais qu'en est-il des opérations de contrôle de versions effectuées directement sur un fichier WAV, telles que renommer ou déplacer un fichier WAV ? Nous n'avions pas de moyen direct de tester le cœur du logiciel de contrôle de versions ; jusqu'à présent, nous ne pouvions le tester que par le biais d'opérations non liées au contrôle de versions.

Nous avons donc décidé d'ajouter l'API complète de contrôle de versions à WAAPI. Les fonctions suivantes, qui correspondent directement aux fonctionnalités de contrôle de versions, ont été ajoutées :

• ak.wwise.core.sourceControl.add
• ak.wwise.core.sourceControl.checkOut
• ak.wwise.core.sourceControl.commit
• ak.wwise.core.sourceControl.delete
• ak.wwise.core.sourceControl.getSourceFiles
• ak.wwise.core.sourceControl.getStatus
• ak.wwise.core.sourceControl.move
• ak.wwise.core.sourceControl.revert
• ak.wwise.core.sourceControl.setProvider

Et pour aller encore plus loin, nous avons ajouté le support pour le contrôle de versions directement dans la WwiseConsole en utilisant waapi-server, generate-soundbank, et tab-delimited-import. Grâce à ces éléments, nous avons pu pousser l'automatisation plus loin et isoler réellement la fonctionnalité.

Élargir la couverture de WAAPI

Parlons un peu plus de notre objectif d'élargir la couverture de WAAPI. Au cours des deux dernières années, nous avons remanié de plus en plus de modèles de données dans Wwise pour les rendre génériques et accessibles à travers les fonctions WAAPI existantes. Pour cette version, nous avons mis l'accent sur l'Interactive Music Hierarchy. Par exemple, il n'était auparavant pas possible de configurer certains objets musicaux dans WAAPI. Voici la liste de ce que nous avons exposé dans la version 2023.1 en ce qui concerne les objets musicaux :

• Associations et Argument dans les Music Switch Containers
• Playlist Root dans les Music Sequence Containers
• Trigger et Segment Reference dans les Music Stingers
• Transition Root dans les objets musicaux

En plus des éléments musicaux énumérés ci-dessus, nous avons également exposé :

• Entries dans les Dialog Events
• Markers dans les fichiers audio sources
• Playlist dans les Random/Sequence Containers

Exemple de musique interactive

Entrons maintenant un peu dans le code. Nous allons créer une structure de musique interactive jouable avec un Music Switch Container, des Music Playlist Containers, des Music Segments, des Music Tracks, des Music Cues, et des Music Transitions. Si vous souhaitez avoir le code de côté, vous pouvez télécharger l'exemple complet sur GitHub :

https://gist.github.com/ak-brodrigue/b98d12e67167eb0e00291cd9c2c02164

L'exemple utilise ak.wwise.core.object.set pour créer toute la structure musicale en un seul appel WAAPI. Notez que nous importons également des fichiers audio pendant la création de la structure. Cela n'était pas possible dans les versions précédentes de Wwise.

Commençons par le concept de la définition d'un objet. Lorsque vous appelez ak.wwise.core.object.set, vous transmettez des définitions d'objets à la fonction. La définition d'objet minimale est constituée des champs suivants :

• type : type de l'objet tel que trouvé dans https://www.audiokinetic.com/en/library/edge/?source=SDK&id=wobjects_index.html. 
• name : nom de l'objet. (Ce nom peut être vide pour certains types d'objets).

Ensuite, la définition de l'objet peut éventuellement inclure les champs suivants :

• children : définit un tableau contenant d'autres définitions d'objets. 
• import : définit les fichiers audio à importer dans l'objet. (NOUVEAU dans la version 2023.1)
• les valeurs de propriété, de référence ou de liste, comme le Volume ou l'OutputBus, sont préfixées par @.

Pour rendre les choses un peu plus faciles, j'ai écrit une fonction utilitaire générique en Python qui s'occupe de générer le code JSON nécessaire correspondant aux définitions d'objets transmises à ak.wwise.core.object.set. Vous n'avez pas besoin de comprendre cette fonction pour l'utiliser. Il y a ci-dessous des exemples qui l'utilisent.

def Object(type, name, *children, **properties):

    # Définition de base
    definition = {
        "type" : type,
        "name" : name
    }

    # Prend n'importe quel mot-clé en argument et le convertit en propriété
    for key, value in properties.items():
        definition['@'+key] = value

    # Les enfants peuvent être d'autres définitions ou des instructions d'importation de fichiers
    if len(children) > 0 and isinstance(children[0], str):
        # Lorsque nous trouvons une chaîne de caractères comme premier argument, nous le considérons comme un chemin de fichier
        definition["import"] = {}
        definition["import"]["files"] = []
        for file in children:
            definition["import"]["files"].append({
                    "audioFile" : file,
                })
    else:
        # Sinon, nous considérons un tableau comprenant des définitions d'enfants
        definition["children"] = children
   
    return definition

Notez également que cela tire parti du système d'arguments de Python, où les deux premiers arguments sont fixes, tandis que les autres arguments sont automatiquement convertis en définitions d'importation d'enfants ou de fichiers audio. Enfin, la fonction utilise également des arguments en mots-clés pour définir des propriétés.

Introduisons une fonction spécialisée pour créer un Music Segment, qui utilise la fonction ci-dessus :

def MusicSegment(name, *children, **properties):
    #  Crée la définition d'un Music Segment
    return Object("MusicSegment", name, *children, **properties)

Nous pourrions maintenant utiliser cette fonction pour créer la définition d'un Music Segment comme suit :

MusicSegment("Segment1",  
    R"C:\MyAudio.wav",
    Volume = -3)

Ou encore, si nous voulons également avoir plusieurs Music Tracks, nous pouvons utiliser :

MusicSegment("Segment1", 
    MusicTrack("TrackA", 
        R"C:\TrackA.wav",
        Volume = -2
        ),
    MusicTrack("TrackB",
        R"C:\TrackB.wav",
        Volume = -2
        )  
    )

La création d'un Music Playlist Container n'est pas très différente. Cependant, cette fois-ci, nous devons spécifier la playlist elle-même. Dans l'exemple ci-dessous, nous définissons le PlaylistRoot sur le Container, qui est une arborescence d'éléments de Playlist. Nous définissons également les paramètres LoopCount et Segment sur les différents éléments de la Music Playlist :

MusicPlaylistContainer(
    R"MPL1",
    MusicSegment("Segment1", R"C:\Segment1.wav"),
    MusicSegment("Segment2", R"C:\Segment2.wav"), 
    PlaylistRoot = 
        MusicPlaylistItem(
            MusicPlaylistItem( Segment = root + "\MSC\MPL1\Segment1"),
            MusicPlaylistItem( Segment = root + "\MSC\MPL1\Segment2"),
            LoopCount = 0 
            )
    )

Enfin, pour créer le Music Switch Container, nous devons associer les Switches à des objets enfants. Cela se fait par le biais des deux premiers arguments de la fonction MusicSwitchContainer. Je vous encourage à jeter un coup d'œil à l'implémentation, qui prend en charge les détails de l'association des Switches avec les objets enfants.

MusicSwitchContainer(root + R"\MSC",
    # Les Switch Groups auxquels le Music Container est associé
    [
        R"\Switches\Default Work Unit\SWG_1", 
        R"\Switches\Default Work Unit\SWG_2"
    ],
    # Les entrées d'association
    {
        R"SW_1_1.SW_2_1": R"MPL1",
        R"SW_1_2.SW_2_1": R"MPL1",
        R"*.SW_2_2": R"MPL2",
    },
  # Les objets enfants
    MusicPlaylistContainer("MPL1", ...),
    MusicPlaylistContainer("MPL2", ...),

Enfin, toutes ces définitions sont transmises à ak.wwise.core.object.set dans WAAPI. L'arborescence complète de définitions dicte comment créer la structure musicale.

Et ensuite ?

Les nouvelles fonctionnalités WAAPI de Wwise 2023.1 sont là pour être explorées. Nous aimerions savoir ce que vous en pensez, et nous espérons qu'elles vous seront utiles. Qu'allez-vous concevoir avec tout cela ? Nous sommes toujours intéressés à savoir ce que les gens font avec notre produit.

Y a-t-il autre chose que vous aimeriez voir dans WAAPI à l'avenir ? N'hésitez pas à nous en faire part dans la section Q&A avec la catégorie Commentaires sur la Bêta.

Si vous souhaitez apprendre WAAPI mais que vous ne savez pas par où commencer, vous pouvez consulter les liens suivants :

• Premiers pas avec WAAPI (https://www.audiokinetic.com/en/library/edge/?source=SDK&id=waapi_gettingstarted.html) - Vue d'ensemble et exemples pour les différents langages de programmation pris en charge.
• Référence WAAPI (https://www.audiokinetic.com/library/edge/?source=SDK&id=waapi_functions_index.html) - Apprenez les détails de chaque fonction WAAPI.
• ak.wwise.core.object.set (https://www.audiokinetic.com/library/edge/?source=SDK&id=ak_wwise_core_object_set.html) - Apprenez-en plus sur ak.wwise.core.object.set.
• Importer des fichiers audio et créer des structures (https://www.audiokinetic.com/library/edge/?source=SDK&id=waapi_import.html) - Apprenez comment créer des structures Wwise.
• Référence des objets Wwise (https://www.audiokinetic.com/library/edge/?source=SDK&id=wobjects_index.html) - Apprenez à connaître les objets de Wwise et leurs propriétés.