L'audio dans Cave est conçu pour être très simple : vous importez un fichier audio, le prévisualisez dans l'éditeur, et le jouez depuis votre jeu lorsqu'un événement se produit.

Dans cette leçon, vous apprendrez :

Comment fonctionnent les assets audio dans l'Asset Browser.
Comment prévisualiser un fichier audio.
Comment exporter ou remplacer un audio au format .ogg.
Comment jouer un audio depuis Python.
Ce que signifient le volume et la hauteur (pitch).
À quoi sert le handle audio retourné.
Comment l'onglet Audio Monitor aide à déboguer l'audio.

Vous n'avez pas besoin d'une configuration complexe pour commencer. Si vous pouvez importer un son et le jouer lorsqu'un bouton est pressé, une porte s'ouvre, un objet est ramassé, ou une action de personnage se produit, vous comprenez déjà le workflow principal.

Importer de l'audio

Cave peut importer des fichiers audio dans le projet en tant qu'assets audio. Comme vous l'avez vu dans la section Importing Assets, Cave supporte les fichiers audio .ogg.

Une fois l'audio importé, il apparaît dans l'Asset Browser comme le reste du contenu de votre projet. De là, vous pouvez l'utiliser dans les scripts, les callbacks UI, les Logic Bricks, les événements Timeline, ou tout autre système nécessitant de jouer un son.

Par exemple, votre projet peut contenir des assets audio comme :

Button Click
Door Open
Pickup Coin
Footstep
Forest Ambience

Des noms lisibles sont très utiles ici, car les audios sont souvent référencés par leur nom dans Python.

Prévisualiser les assets audio

Après avoir importé un fichier audio, vous pouvez le prévisualiser directement dans Cave.

Il y a deux manières simples de faire cela :

Double-cliquez sur l'asset audio dans l'Asset Browser pour lancer rapidement une prévisualisation.
Cliquez une fois à gauche pour le sélectionner et afficher ses propriétés, où vous pouvez utiliser les contrôles de prévisualisation pour le jouer.

La vue des propriétés est utile car elle vous donne plus de contrôle lors de la prévisualisation. Par exemple, vous pouvez tester comment le son réagit à différentes valeurs de pitch avant de l'utiliser dans le jeu.

Cela est particulièrement utile pour les effets comme les pas, impacts, clics UI, et sons de créatures. Un petit changement de pitch peut rendre des sons répétés moins identiques.

Exporter ou remplacer un audio

Les assets audio peuvent aussi être exportés au format .ogg. C'est pratique quand vous souhaitez éditer l'audio dans un outil externe, par exemple.

Vous pouvez aussi remplacer l'asset audio par un autre fichier .ogg. Cela est pratique lorsque la logique référence déjà un nom d'asset, mais que vous voulez changer le son réel.

Par exemple, votre jeu utilise peut-être déjà un asset nommé Door Open. Si vous remplacez l'audio dans cet asset, les scripts qui jouent Door Open continueront de fonctionner sans avoir besoin d'être renommés.

Jouer de l'audio avec un Audio Component

Parfois, vous souhaitez jouer un son simple en boucle pour un ambient, une musique de menu principal, etc. Dans ce cas, le composant audio suffit :

Il joue en boucle l'audio que vous lui spécifiez, et permet de contrôler le volume, la hauteur (pitch), si le son est en 3D, et la distance maximale. Notez qu'il n'offre pas plus d'options, comme le nombre de boucles. Si vous avez besoin de plus de personnalisation, il faut jouer l'audio via le code.

Jouer de l'audio depuis Python

La manière la plus simple de jouer un asset audio depuis Python est avec cave.playSound().

cave.playSound("Button Click")

Cela joue l'asset audio nommé Button Click.

Vous pouvez aussi passer une valeur de volume :

cave.playSound("Door Open", volume=0.8)

Le volume par défaut est 1.0, ce qui signifie volume normal. Des valeurs plus basses rendent le son plus faible.

Par exemple :

Volume	Signification
`2.0`	Volume très fort.
`1.0`	Volume normal.
`0.5`	Volume moitié.
`0.0`	Silencieux.

La plupart du temps, vous commencerez à 1.0 et ajusterez ensuite.

Volume et hauteur (Pitch)

Volume contrôle l'intensité sonore.
Pitch contrôle la hauteur du son. Il modifie aussi la vitesse de lecture : un pitch plus élevé joue le son plus vite et plus aigu, un pitch plus bas joue plus lentement et plus grave.

La valeur par défaut pour volume et pitch est 1.0.

Par exemple :

Valeur	Effet sur le volume	Effet sur le pitch
`1.0`	Volume normal.	Pitch normal.
`0.5`	Moins fort.	Plus bas et plus lent.
`1.5`	Plus fort si utilisé pour le volume.	Plus haut et plus rapide.

Quand vous utilisez cave.playSound(), le volume est passé directement au démarrage du son. Le pitch est généralement modifié à travers le handle audio retourné par la fonction.

Le handle audio

Lorsque vous appelez cave.playSound(), Cave retourne un handle audio.

Ce handle représente l'instance de son actuellement jouée.

sound = cave.playSound("Footstep Stone", volume=0.8)
sound.pitch = 1.0

Vous pouvez utiliser ce handle pour contrôler le son après son démarrage.

Par exemple :

sound = cave.playSound("Cave Ambience", volume=0.6, loop=True)

# Vous pouvez aussi utiliser les getters et setters :
sound.setPitch(0.9)
sound.setVolume(0.4)

Ce handle peut servir à :

Changer le volume.
Changer le pitch.
Mettre le son en pause.
Reprendre le son.
Arrêter le son.
Vérifier la progression.
Faire venir le son d'une entité 3D.

Par exemple, si un son de porte doit venir de l'entité porte :

sound = cave.playSound("Door Open", volume=1.0)
sound.setSource3D(self.entity, maxDistance=20)

Vous n'avez pas besoin de ce handle pour chaque son. Si vous voulez juste jouer un clic rapide de bouton, ceci suffit :

cave.playSound("Button Click")

Utilisez le handle quand vous avez besoin de plus de contrôle.

Il est même possible de randomiser un peu les pas, donnant plus de variété sans nécessiter plus de sons :

sd = cave.playSound("Footstep Stone")

# Définir la source 3D comme l'entité qui joue le son :
sd.setSource3D(entity, 20)

# Randomiser pitch et volume :
sd.pitch  = cave.random.uniform(0.5, 1.5)
sd.volume = cave.random.uniform(0.1, 0.3)

Le code ci-dessus est très similaire à celui que vous trouverez dans le callback d'animation Walk and Run du Proto Character par défaut, lors de la création d'un nouveau projet Cave.

L'onglet Audio Monitor

Cave inclut aussi un onglet Audio Monitor pour déboguer l'audio pendant que votre jeu tourne.

Vous pouvez l'ouvrir depuis le menu Tabs en haut à gauche dans l'éditeur.

L'Audio Monitor affiche des informations sur les audios joués, y compris la progression de la lecture. Vous pouvez développer les entrées pour inspecter plus de détails, ce qui est très utile quand un projet commence à avoir beaucoup de sons en même temps.

Par exemple, l'Audio Monitor peut vous aider à répondre à des questions telles que :

Ce son est-il effectivement joué ?
Le même son est-il joué trop souvent ?
Une ambiance en boucle est-elle toujours active ?
À quel point de lecture en est le son ?

Vous n’aurez probablement pas besoin de l'Audio Monitor constamment dans un prototype simple, mais il devient très utile pour déboguer des scènes plus complexes.

Ce que vous devez retenir

L'audio dans Cave est simple : importez un fichier audio, prévisualisez-le dans l'Asset Browser, et jouez-le depuis Python avec cave.playSound().

Utilisez le volume pour contrôler l'intensité sonore, le pitch pour contrôler la hauteur du son, et gardez le handle retourné quand vous devez contrôler le son après son démarrage.

Quand l'audio devient difficile à suivre, ouvrez l'onglet Audio Monitor depuis le menu Tabs et inspectez ce qui est joué.

Cave : Guide de démarrage