Frictional Game Wiki

<h1>Managing Audio</h1> <div class="level1"> <p> &lt;note>This article is just a sampling. Any experienced modders that know more about audio playback, please feel free to flesh out this page.&lt;/note> </p> </div> <h2>Recommended Prerequisites</h2> <div class="level2"> <p> The recommended format for audio playback in HPL3 is the FMOD sound bank format. This is a special format that allows a number of sound files to be bundled together into a single library package as well as technical settings (such as reverb) to be easily accessible by the game engine. To create files in this format, download the <a href="http://www.fmod.org/download-previous-products" class="urlextern" title="http://www.fmod.org/download-previous-products" rel="nofollow">FMOD Ex Designer</a> software. </p> <p> Also, to understand exactly how audio is handled in HPL3, you should go and read through <a href="/doku.php?id=hpl3:engine:sound" class="wikilink1" title="hpl3:engine:sound">Sound</a>, as it covers the technical side in much greater detail than can be accomplished here. </p> </div> <h2>Preparing FMOD Sound Banks</h2> <div class="level2"> <p> Replacing the .snt file format used in HPL2, an FMOD soundbank file is the preferred method of storing audio files for your mod. It allows sound to be played from within the game world, letting the player hear it in relation to where they are and where they are facing. It also lets you fine tune your audio in a number of different ways as well as define a number of game-engine specific properties. </p> <p> This guide will show you how to create a very basic sound bank for use in your mod. First, start up FMOD Designer and create a new project. You can name it whatever you like, but it is recommended to give it a name that lets you and others know what kinds of audio files will be inside it. </p> <p> When you first create the project, it will show you the following screen. (There will also be an event group created by default called "untitled". Delete this event group for now via "Right Click > Delete".) </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial01.png" class="media" title="hpl3:community:fmodtutorial01.png"><img src="/lib/exe/fetch.php?w=600&tok=d80cbd&media=hpl3:community:fmodtutorial01.png" class="mediacenter" alt="" width="600" /></a> </p> <p> The first thing we need to do is create an event group. An event group is a way to organize the sound events within your sound bank, similarly to how files are stored on your computer. You can create as many groups as you want, as well as creating groups within a group, but for now, let's just create a single group. Name it whatever you want, within reason. </p> <p> Following this, we want to create the sound event itself. An event in FMOD represents a sound or sounds being played, and they contain most of the properties that you would want to set to a sound. (When you play a sound from within the game, you will be using the name of this event.) </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial02.png" class="media" title="hpl3:community:fmodtutorial02.png"><img src="/lib/exe/fetch.php?w=600&tok=cd164c&media=hpl3:community:fmodtutorial02.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Our event is currently empty, so we want to add a sound file to the playlist. This controls what sounds will be played when the event is triggered. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial03.png" class="media" title="hpl3:community:fmodtutorial03.png"><img src="/lib/exe/fetch.php?w=600&tok=341839&media=hpl3:community:fmodtutorial03.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Our events are good for now, so next we want to create a sound definition. A sound definition represents the sound file itself. Click on the "Sound Defs" tab, right-click the window on the left, and select "Add sound def(s) from sound files…". In the dialog box, select the sound file you chose for your event. All the relevant properties will be set for you, so that's all you need to do here. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial04.png" class="media" title="hpl3:community:fmodtutorial04.png"><img src="/lib/exe/fetch.php?w=600&tok=cfef48&media=hpl3:community:fmodtutorial04.png" class="mediacenter" alt="" width="600" /></a> </p> <p> When you created the project, a soundbank was created for you, but it is likely named something obnoxiously obtuse like "YourProjectName_001". For the sake of clarity, you might want to rename it to something more helpful. Click on the "Banks" tab, select the soundbank from the list (of one) on the left, and rename it in the properties window on the right in the "Name" box. (This step is optional but recommended.) </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial05.png" class="media" title="hpl3:community:fmodtutorial05.png"><img src="/lib/exe/fetch.php?w=600&tok=612c95&media=hpl3:community:fmodtutorial05.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Your soundbank is now complete (don't forget to save), but you still need to generate the files that HPL3 is actually going to use. To do this, go to the Project menu and select "Build…". In the dialog, check the box next to your soundbank, then press "Build". </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial06_1.png" class="media" title="hpl3:community:fmodtutorial06_1.png"><img src="/lib/exe/fetch.php?w=600&tok=bd72f3&media=hpl3:community:fmodtutorial06_1.png" class="mediacenter" alt="" width="600" /></a> </p> <p> You are now ready to use your newly-created soundbank within your mod. After all is said and done, the files in your sounds folder should look like this. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:fmodtutorial07.png" class="media" title="hpl3:community:fmodtutorial07.png"><img src="/lib/exe/fetch.php?w=600&tok=3c3b47&media=hpl3:community:fmodtutorial07.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Most of these files are development or temporary files generated for you by FMOD Designer, but when you release your mod you only need the files ending in ".fdp" (the project file), ".fev" (the event-definition file), and ".fsb" (the soundbank file). </p> </div> <h2>Playing FMOD Soundbanks</h2> <div class="level2"> <p> There are a number of functions provided by HPL3 to create and manage sounds played within the game. The game-related information relevant to the sound is either stored within the soundbank files or generated at run-time using Soundscape areas, so the functions themselves are relatively simple to use. </p> <p> These functions are as follows: </p> <pre class="code">//////////////////////////////////////////////////////////////////////////////// // Remember to add "#include &lt;helpers/helper_audio.hps&gt;" to the top of your // script file before using these functions. // Basic playback functions void Sound_CreateAtEntity(const tString &in asSoundName, const tString &in asSoundFile, const tString &in asEntity, float afFadeTime = 0.0f, bool abSaveSound = false, float afTargetVolume = 1.0f) void Sound_Play(const tString &in asSoundName, float afFadeTime, bool abResetVolMul = false) void Sound_Stop(const tString &in asSoundName, float afFadeTime) void Sound_Fade(const tString &in asSoundName, float afVolumeDest, float afFadeTime) bool Sound_Exists(const tString &in asSoundName) // Advanced playback functions Sound_CreateAtEntity_UsePrefix(const tString &in asSoundName, const tString &in asSoundFile, const tString &in asEntity, float afFadeTime, bool abSaveSound, float afTargetVolume = 1.0f) </pre><p> </p> <p> &lt;note>These functions also support .snt files, but the .snt format has been deprecated by Frictional Games for use in HPL3. As such, not all features of .snt files are guaranteed to work, nor are they guaranteed to work everywhere. For this reason, it is recommended that you instead save your audio files in an FMOD soundbank.&lt;/note> </p> </div> <h4>Sound_CreateAtEntity</h4> <div class="level4"> <p> This function creates a sound dynamically, positioned at the specified entity, and plays the sound immediately. Sounds created in this way will be given a name, which can be used in other functions to affect a sound without creating a new one. (Useful for loops or sound effects.) </p> <p> Using this function to create a sound from an FMOD soundbank requires that the sound file name is given in the following format: "SoundbankFileName/Event/Group/Names/EventName". </p> <ul> <li class="level1"> <b>asSoundname</b>: The name of the sound to be created.</li> <li class="level1"> <b>asSoundFile</b>: The name of the sound file.</li> <li class="level1"> <b>asEntity</b>: The name of the entity to create the sound at. Accepts the name "player". (If the entity cannot be found, this function will do nothing.)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade in.</li> <li class="level1"> <b>abSaveSound</b>: Whether or not the sound object should be saved when the game is saved. (Useful for sounds that start at the beginning of a level.)</li> <li class="level1"> <b>afTargetVolume</b>: The volume at which the should be played. (0.0 - 1.0)</li> </ul> <pre class="code">// Example Usage Sound_CreateAtEntity("speaker_beep", "level_sounds/speaker/beep", "intro_speaker"); </pre><p> </p> </div> <h4>Sound_Play</h4> <div class="level4"> <p> This function makes an existing sound object begin playing. The sound object can be placed in the level editor or have been created by a previous call to Sound_CreateAtEntity. </p> <ul> <li class="level1"> <b>asSoundName</b>: The name of the sound to be played. (Supports wildcard characters (*) for playing many sounds at once.)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade in.</li> <li class="level1"> <b>abResetVolMul</b>: Whether the volume for the sound should be reset to its default value.</li> </ul> <pre class="code">// Example Usage Sound_Play("explosion_bomb_*", 0.1); </pre><p> </p> </div> <h4>Sound_Stop</h4> <div class="level4"> <p> This function stops the playing of a currently playing sound. </p> <ul> <li class="level1"> <b>asSoundName</b>: The name of the sound to be stopped. (Supports wildcard characters (*) for stopping many sounds at once.)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade out.</li> </ul> <pre class="code">// Example Usage Sound_Stop("interrupting_cow", 0); === Sound_Fade === This function gradually changes the volume of a sound from its current volume to a new one. * **asSoundName**: The name of the sound. (Supports wildcard characters (*) for affecting many sounds at once.) * **afVolumeDest**: The target volume to fade to. (0.0 - 1.0) * **afFadeTime**: The time in seconds to fade from the old volume to the new one. &lt;code&gt;// Example Usage Sound_Fade("ominous_noises_*", 0.25, 3.0); </pre><p> </p> </div> <h4>Sound_Exists</h4> <div class="level4"> <p> This function checks whether a sound object exists. </p> <ul> <li class="level1"> <b>asSoundName</b>: The name of the sound. (Supports wildcard characters (*) for checking many sounds at once.)</li> </ul> <ul> <li class="level1"> <b>returns</b>: Whether a sound object of the given name exists.</li> </ul> <pre class="code">// Example Usage if (Sound_Exists("horse_noises")) { // Magic happens here... } </pre><p> </p> </div> <h4>Sound_CreateAtEntity_UsePrefix</h4> <div class="level4"> <p> This function works similarly to Sound_CreateAtEntity with one major difference. If the sound object is created within a soundscape, this function will look for any specialized sound events in the soundbank for use within that soundscape. For example, if a sound with the event path "groupname/footstep" is created within the "smallroom" soundscape, this function will try to use the sound event named "groupname/smallroom/footstep". </p> <p> Using this function to create a sound from an FMOD soundbank requires that the sound file name is given in the following format: "SoundbankFileName/Event/Group/Names/EventName". </p> <ul> <li class="level1"> <b>asSoundname</b>: The name of the sound to be created.</li> <li class="level1"> <b>asSoundFile</b>: The name of the sound file.</li> <li class="level1"> <b>asEntity</b>: The name of the entity to create the sound at. Accepts the name "player". (If the entity cannot be found, this function will do nothing.)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade in.</li> <li class="level1"> <b>abSaveSound</b>: Whether or not the sound object should be saved when the game is saved. (Useful for sounds that start at the beginning of a level.)</li> <li class="level1"> <b>afTargetVolume</b>: The volume at which the should be played. (0.0 - 1.0)</li> </ul> <pre class="code">// Example Usage Sound_CreateAtEntity_UsePrefix("footstep", "level_sounds/player/footstep", "player"); </pre><p> </p> </div> <h2>Playing Music</h2> <div class="level2"> <p> WIP </p> </div> <h2>Preparing Voice Files</h2> <div class="level2"> <p> Voice files are a specially handled form of audio in HPL3. Their main purpose is to represent the sound played from character voices, either in audio logs or in an active dialogue (such as the conversation with Dr. Munshi). They are also used to represent character barks (e.g. random sounds from monsters). Unlike FMOD soundbanks, voice file audio sources are stored in a raw audio format, usually in a designated lang folder. The voice files themselves are special XML files that detail dialogue trees, handle subtitles, and generally manage the playback of audio files in character interactions. </p> <p> Like FMOD soundbanks, voice files need some setup before they can be used in-game. The way they are created is with the VoiceHandler utility program that comes bundled with SOMA. To start, we will need to open that program and create a new project. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial01.png" class="media" title="hpl3:community:voicetutorial01.png"><img src="/lib/exe/fetch.php?w=600&tok=9c7f4c&media=hpl3:community:voicetutorial01.png" class="mediacenter" alt="" width="600" /></a> </p> <p> For the purposes of this tutorial, I will be making a voice file dialogue out of <a href="https://www.freesound.org/people/shadoWisp/sounds/257479/" class="urlextern" title="https://www.freesound.org/people/shadoWisp/sounds/257479/" rel="nofollow">this free audio clip</a>, featuring a short one-sided conversation between an NPC in a game and a ghost. In order to use it in our dialogue, however, the clip must be split into a number of distinct audio files, each representing a particular line of dialogue. I won't be covering this step in detail, but using a free utility like <a href="http://www.audacityteam.org/" class="urlextern" title="http://www.audacityteam.org/" rel="nofollow">Audacity</a> this process is relatively straightforward. </p> <p> Before we can create our dialogue, we need to create the scenes that the dialogue will be a part of, as well as any characters who participate in it. For this tutorial, we only have one scene, and our conversation only has one vocal participant. </p> <p> Click on the "Voice Settings" tab and create a new voice scene and character. The scene only needs a name, and that can be whatever you like. The character has two fields that we care about: "Name" and "Display Name". The Name is the name of the character that the voice file will use when deciding who is talking at the moment while the Display Name is the name that will appear in the subtitles. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial02.png" class="media" title="hpl3:community:voicetutorial02.png"><img src="/lib/exe/fetch.php?w=600&tok=14a638&media=hpl3:community:voicetutorial02.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Heading back to the "Subjects" tab, it's time to create our dialogue. In voice file vernacular, every chunk of dialogue is called a "Subject", and each is handled as its own branch of conversation. Click the "Add Subject" button at the bottom-left of the window. </p> <p> There are a lot of text boxes that pop-up with a new subject, but most of these aren't necessary for what we are currently doing, so ignore those for now. If you want, clicking the "Hide Options" box in the top-right will hide most of these boxes. (Don't do this now, however, as some of these boxes we will need later.) </p> <p> &lt;note>While we aren't using them in this tutorial, the "Callback" and "Entity" boxes are very useful to fill out for your mod. The "Entity" box holds the name of an entity in your level that, when the subject is played, will automatically be set as the source of the voice audio. The "Callback" box holds the name of a callback function that you would like to be triggered when the subject ends.&lt;/note> </p> <p> The subject's name by default is "Subject0", but we want to rename that into something a bit more useful. We are also going to want to select the "Scene" drop-down menu and select the scene that we created earlier. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial03.png" class="media" title="hpl3:community:voicetutorial03.png"><img src="/lib/exe/fetch.php?w=600&tok=0bfe74&media=hpl3:community:voicetutorial03.png" class="mediacenter" alt="" width="600" /></a> </p> <p> Now it's time to create the dialogue itself. In the drop-down menu called "Select Character", choose the character we created for this dialogue. Then in the box next to it, type out the text that subtitles the first line of the dialogue. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial04.png" class="media" title="hpl3:community:voicetutorial04.png"><img src="/lib/exe/fetch.php?w=600&tok=f585d4&media=hpl3:community:voicetutorial04.png" class="mediacenter" alt="" width="600" /></a> </p> <p> When that's finished, press the enter key to add a second line. Repeat this for all the lines in the dialogue. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial05.png" class="media" title="hpl3:community:voicetutorial05.png"><img src="/lib/exe/fetch.php?w=600&tok=fcd73c&media=hpl3:community:voicetutorial05.png" class="mediacenter" alt="" width="600" /></a> </p> <p> &lt;note>The enter key will add a new line of dialogue for the currently speaking character. This is useful for breaking up a line of dialogue from a character that is too long. To create a line of dialogue for a new character, press the "+" button at the bottom of the subject.&lt;/note> </p> <p> Next, we need to hook up the lines of dialogue with the actual audio files. To do this, click the arrow button next to each line, and under "File Name" type the name of the audio file to be played. Do this for every line of dialogue. </p> <p> <a href="/lib/exe/detail.php?id=hpl3%3Acommunity%3Aother%3Amanaging_audio&media=hpl3:community:voicetutorial06.png" class="media" title="hpl3:community:voicetutorial06.png"><img src="/lib/exe/fetch.php?w=600&tok=f0bd9f&media=hpl3:community:voicetutorial06.png" class="mediacenter" alt="" width="600" /></a> </p> <p> That's all we need. Now it's time to save the voice file. </p> <p> The most common place to save a voice file is in the same directory as the map files the voices will be played on. When doing this, name the voice file the same name as the map (for example, if your map is named "scary_map.hpm", name the voice file "scary_map.voice"). This ensures that the voice file and the map will be paired correctly when the game is launched. </p> <p> &lt;note>In order for the subtitles to be displayed, they need to be added to the lang file for your map. Fortunately, this process is handled for you. When you run your map after creating the voice file, the lang file will automatically be updated with the correct lang categories and entries. (This process may take a moment, so don't be surprised if the subtitles do not appear the first time you play your dialogue.)&lt;/note> </p> </div> <h2>Playing Raw Audio Files</h2> <div class="level2"> <p> The simplest way to play an audio file is to do so directly. This has the benefit of having the most straight-forward implementation (just drop your audio files into your mod folder and you're done), but it comes with the drawback of not being able to position the sound in the world. This could be the preferred method for audio playback during mod testing or in times when player position relative to the sound is unnecessary, such as when playing sound from a terminal or when the audio source is right in front of the player. </p> <p> The relevant functions to achieve this are the following: </p> <pre class="code">//////////////////////////////////////////////////////////////////////////////// // Remember to add "#include &lt;helpers/helper_audio.hps&gt;" to the top of your // script file before using these functions. // Basic playback functions void Sound_PlayGui(const tString &in asSoundFile, float afVolume, eSoundEntryType aEntryType = eSoundEntryType_Gui) void Sound_FadeInGui(const tString &in asSoundFile, float afVolume, float afFadeTime) void Sound_StopGui(const tString &in asSoundFile, float afFadeTime, bool abPlayEnd = true) bool Sound_GuiIsPlaying(const tString &in asSoundFile) // Advanced playback functions void Sound_FadeGuiVolume(const tString &in asSoundFile, float afVolumeDest, float afFadeTime) void Sound_FadeGuiSpeed(const tString &in asSoundFile, float afSpeedDest, float afFadeTime) </pre><p> </p> </div> <h4>Sound_PlayGui</h4> <div class="level4"> <p> This is the base function for your audio-playing needs. It plays a sound from an FMOD sound bank, a .snt file, or a raw audio file. (.wav, .ogg, .mp3) </p> <ul> <li class="level1"> <b>asSoundFile</b>: The path to your sound file.</li> <li class="level1"> <b>afVolume</b>: The volume at which to play the sound. (0.0 - 1.0)</li> <li class="level1"> <b>aEntryType</b>: The entry type of the sound. (It's usually best to ignore this parameter.)</li> </ul> <pre class="code">// Example usage Sound_PlayGui("sounds/button_beep.ogg", 1.0); </pre><p> </p> </div> <h4>Sound_FadeInGui</h4> <div class="level4"> <p> Functionally similar to Sound_PlayGui, except it allows the option to specify a fade-in timer to your audio. </p> <ul> <li class="level1"> <b>asSoundFile</b>: The path to your sound file.</li> <li class="level1"> <b>afVolume</b>: The volume at which to play the sound. (0.0 - 1.0)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade in.</li> </ul> <pre class="code">// Example Usage Sound_PlayGui("sounds/building_tremor.ogg", 1.0, 3.5); </pre><p> </p> </div> <h4>Sound_StopGui</h4> <div class="level4"> <p> This function allows you to manually stop the playback of an audio file. It also allows the option to specify a fade-out timer. </p> <ul> <li class="level1"> <b>asSoundfile</b>: The path to your sound file. (Must be an audio file currently playing, or this function does nothing.)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds for the sound to fade out.</li> <li class="level1"> <b>abPlayEnd</b>: If you want end events to be triggered. (Only applicable if afFadeTime is 0. Not applicable to raw audio files.)</li> </ul> <pre class="code">// Example Usage Sound_StopGui("sounds/sudden_noises.ogg", 0.0); </pre><p> </p> </div> <h4>Sound_GuiIsPlaying</h4> <div class="level4"> <p> This function lets you check to see if a sound file is currently playing or not. </p> <ul> <li class="level1"> <b>asSoundfile</b>: The path to your sound file.</li> </ul> <ul> <li class="level1"> <b>returns</b>: True if the specified sound file is currently playing, otherwise false.</li> </ul> <pre class="code">// Example Usage if (Sound_GuiIsPlaying("sound/quizzical_music.ogg)) { // Some magic happens here... } </pre><p> </p> </div> <h4>Sound_FadeGuiVolume</h4> <div class="level4"> <p> This function allows you to change the volume of a currently playing sound file. </p> <ul> <li class="level1"> <b>asSoundfile</b>: The path to your sound file.</li> <li class="level1"> <b>afVolumeDest</b>: The target volume to fade to. (0.0 - 1.0)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds to fade from the old volume to the new volume.</li> </ul> <pre class="code">// Example Usage Sound_FadeGuiVolume("sound/be_quiet.ogg", 0.25, 0.75); </pre><p> </p> </div> <h4>Sound_FadeGuiSpeed</h4> <div class="level4"> <p> This function lets you change the playback speed of a currently playing sound file. This operation does affect the pitch of the sound. </p> <ul> <li class="level1"> <b>asSoundfile</b>: The path to your sound file.</li> <li class="level1"> <b>afSpeedDest</b>: The target speed to fade to. (1.0 = Normal speed)</li> <li class="level1"> <b>afFadeTime</b>: The time in seconds to fade from the old speed to the new speed.</li> </ul> <pre class="code">// Example Usage Sound_FadeGuiSpeed("sound/helium_talking.ogg", 2.0, 0.5); </pre><p> </p> </div>