Si vous avez déjà tenté d’ajouter de la musique ou des effets sonores pour vos jeux en Twine réalisés sous Harlowe, vous savez que ce n’est pas forcément une mince affaire. Si vous êtes un utilisateur averti de JavaScript, vous pouvez bien évidemment créer vos propres fonctions pour gérer cela, mais si ce n’est pas le cas, un certain ChapelR a créé une bibliothèque spécialement pour vous ! Il s’agit de la « Harlowe Audio Lib », dont la documentation est accessible ici (en anglais uniquement). Si lire tout cela vous effraie, pas d’inquiétude : ce tutoriel vous permettra d’apprendre à utiliser ses fonctionnalités de base sans difficultés.

Installation

Pour commencer, il va falloir installer la bibliothèque dans votre jeu. Pour cela, rendez vous sur la page GitHub du projet. Cliquez sur harlowe-audio.min.js et copiez l’intégralité du code, puis collez-le dans la feuille de JavaScript de votre histoire. Ensuite, copiez le contenu de harlowe-audio.min.css et collez-le dans la feuille de style de votre histoire. Et voilà, l’installation est terminée.

Pour les utilisateurs de Tweego ou de Twee2, la méthode est différente, je vous laisse vous référer à la documentation officielle.

Pour tester votre jeu avec les musiques, vous aurez besoin de le mettre en ligne, ou de lancer un serveur HTTP local. Je vous renvoie à ce tutoriel sur notre site, où on vous expliquait comment faire dans le cadre d’un autre outil, Vorple. En effet, quand vous utilisez la fonction test de Twine, il ne prend pas en compte les divers fichiers sons et images que vous joignez à votre jeu, ce qui est fort dommage.

Configuration

Vous pouvez maintenant configurer les options de la bibliothèque pour votre jeu. Pour cela, retournez sur la feuille de JavaScript, et cherchez les premières lignes de la bibliothèque, qui suivent un var options et qui sont mises en forme.

L’option preload ajoute un écran de chargement, le temps que le navigateur du joueur charge toutes les musiques nécessaires avant que le jeu ne commence. J’ai tendance à le désactiver pour les périodes de test : pour cela, il suffit de remplacer true par false.

Les trois lignes situées après controls permettent d’activer ou désactiver le panneau de contrôle par défaut, et de le configurer. Si vous ne voulez pas vous embêter à créer votre propre panneau, je vous conseille de le laisser ; sinon, remplacez le true par false sur la première ligne.

Le panneau permettant de contrôler le son pendant une partie.
À gauche, le panneau de contrôle du son quand il est en position fermée ; à droite, en position ouverte. Le curseur permet au lecteur de régler le volume, tandis que le bouton permet de couper le son complètement.

Quant aux autres options, je vous conseille là encore de laisser les valeurs par défaut.

Déclarer des fichiers sonores

Maintenant que la bibliothèque est installée et configurée, il est temps de lier vos fichiers sonores à votre jeu. Pour cela, créez un nouveau passage et donnez lui le tag « startup » ; il sera donc lu par Twine à chaque fois que vous démarrerez le jeu. C’est dans ce passage que vous donnerez un nom à tous vos effets sonores, ce qui vous permettra de les « appeler » quand vous en aurez besoin dans votre jeu. Il vous faut maintenant écrire un code similaire à ceci :

{
<script>
 A.newTrack('theme', 'audio/theme.mp3', 'audio/theme.ogg');
 A.newTrack('beep', 'audio/bip.mp3');
</script>

}

Les accolades évitent que Twine n’ajoute plein de sauts de ligne à votre histoire, les balises script permettent au navigateur de comprendre que les lignes qui suivent sont en JavaScript. On utilise ensuite la méthode A.newTrack() de la bibliothèque. Entre les parenthèses, on donne à chaque musique son nom, entre guillemets simples, puis, après une virgule, l’adresse des différents fichiers qui correspondent à cette musique. Ici, on a utilisé des adresses relatives : un dossier « audio » a été placé au même endroit que le fichier votreProjet.html créé par Twine, et on y a inséré les différents fichiers sonores.

Sur la première ligne, on a donné deux adresses : elles correspondent à la même musique, le thème de notre jeu, enregistré sous deux formats différents ; en effet, certains navigateurs ne sont pas capable de lire certains formats de fichiers. Quand on propose plusieurs fichiers, le navigateur va alors chercher d’abord le premier ; s’il lui convient, il est satisfait et passe à la ligne suivante ; si c’est un format qui ne lui plaît pas, il va se tourner vers le deuxième, ainsi de suite. Vous pouvez déclarer autant de fichiers qu’il vous plaît pour une même musique, et autant de musiques que vous avez besoin en rajoutant une ligne A.newTrack à chaque fois. Enfin, vous n’êtes pas obligés de déclarer plusieurs formats. De manière générale, les MP3 sont compatibles avec la plupart des navigateurs récents.

Une fois que cette étape est terminée, vous pouvez maintenant demander à Twine de jouer ces fichiers quand vous en avez envie !

Ajouter un effet sonore

Imaginons que vous souhaitez que certains liens fasse « bip » quand on clique dessus. Vous avez d’ores et déjà déclaré votre fichier « bip.mp3 » à l’étape précédente, il s’appelle maintenant « bip ».

Pour cela, il va falloir créer un lien avec la macro (link:) de Harlowe, puis utiliser la méthode A.track() de la bibliothèque.

(link: 'Bouton qui fait Bip')[
<script>A.track('bip').play();</script>

]

La méthode A.track() est aussi une méthode JavaScript, on a donc besoin de la placer entre des balises <script>. Ce qu’on écrit ici est tout simple : je veux appeler le son nommé « bip » ; en ajoutant à la suite .play(), je dis tout simplement que je veux jouer ce son une fois. C’est donc ce qui va se passer chaque fois que j’appuie sur le lien « Bouton qui fait Bip ».

Ajouter des musiques

Parce que les boutons qui font bip, c’est bien gentil, mais ce n’est quand même pas très utile, mettons que je veuille plutôt lancer une musique d’ambiance pour mon jeu. Pour cela, on va utiliser la même méthode que précédemment, A.track(), et on va lui ajouter d’autres méthodes, comme notre .play() pour lui donner des comportements supplémentaires.

Si on veut une musique dès le début du jeu, puis qui tourne en boucle, on va inscrire dans notre premier passage du jeu :

<script>A.track('theme').loop(true).playWhenPossible()</script>
\

Grâce à .loop(true), le thème de notre jeu va tourner en boucle.

Le .playWhenPossible() est dû au comportement récent de la plupart des navigateurs. En effet, comme sur beaucoup de sites, des vidéos publicitaires se lançaient dès qu’on arrivait sur la page, avec le son parfois très fort, certains navigateurs ont décidé de couper le son des pages web tant qu’on a pas cliqué délibérément sur un élément sonore. Or, cela concerne aussi nos jeux : tant que le joueur n’a pas cliqué sur un lien, ces navigateurs coupent le son. L’option .playWhenPossible() se déclenchera alors dès que le joueur cliquera sur un lien, n’importe lequel, de votre jeu.

Si vous souhaitez avoir un peu plus de contrôle sur le moment où se lance votre musique, je vous conseille de créer un écran titre pour votre jeu, avec un lien « Commencer », qui mène au premier « vrai passage » de votre jeu, et qui lance la musique par la même occasion.

(link: 'Commencer')[
 <script>track('theme').loop(true).fadeIn(2);</script>

 (goto: 'Premier Passage')
]

Ici, plutôt que play(), qui aurait très bien fonctionné aussi, on a choisi fadeIn() : cette méthode permet d’ajouter un fondu sur un certain nombre de secondes (ici deux), plutôt que de démarrer directement à plein volume.

Et les arrêter…

C’est bien sympa toutes ces boucles, mais ça n’en finit pas ! Et si je veux changer la musique, il va bien falloir stopper celle en cours pour éviter la cacophonie.

Pour cela, plusieurs méthodes sont disponibles. Une fois encore, pour avoir un meilleur contrôle sur ce qu’il se passe à quel moment, je vous conseille de gérer tout ce qui touche à la musique dans des (link:) ; Twine est parfois un peu imprévisible quant au moment où il exécute le code JavaScript dans un passage.

Si je veux simplement mettre le thème en pause, pour pouvoir le reprendre plus tard au même instant, il faut utiliser pause(), tout simplement.

<script>A.track('theme').pause()</script>

Si je préfère l’arrêter complètement — il reprendra alors au début si je le relance — la méthode s’appelle stop() :

<script>A.track('theme').stop()</script>

Enfin, pour une transition plus douce, il y a aussi un fondu de fin, fadeOut() :

<script>A.track('theme').fadeOut(3)</script>

Il fonctionne de la même façon que fadeIn(), le nombre entre parenthèses correspond donc à la durée du fondu en secondes.

Si vous utilisez pas mal de musiques et ne savez plus trop ce qui se joue à quel moment, il peut être plus simple de couper toutes les musiques d’un coup avant d’en lancer une autre. Une méthode est prévue pour cela aussi :

<script>A.stopAll()</script>

Et voilà ! Nous avons fait le tour des fonctionnalités principales de la Harlowe Audio Lib. Même si ce tutoriel est loin, très loin d’aborder toutes ses possibilités, il devrait être suffisant pour vous permettre d’ajouter de la musique à vos jeux créés avec Harlowe.