Sparen's Danmakufu ph3 Tutorials Lesson 15 - Using Danmakufu's Sound Functions

The video for this lesson is Trickysticks's Youmu, Half Ghost Gardener, chosen due to its exceptional quality and effective sound and music choices.

Part 1: What will be Covered in this Lesson?

Sound is very important in any form of modern video game. Using sound effects and background music effectively make the experience significantly better, and they provide mood, ambience, and style. Of course, there are multiple ways to implement sound in Danmakufu, and we will go into these shortly.

Before reading this guide, I expect that you already understand what .mp3 and .wav files are. I will cover .ogg files (OGG Vorbis) briefly, as they are the preferred option for BGM tracks in Danmakufu, but I will not cover .mp3 and .wav files. Note that this guide requires that you do not use #BGM, as these sound functions are in fact a replacement for #BGM in Stage scripts and Plural scripts.

Part 2: How do I Use Danmakufu's Audio Functions?

To begin the lesson, I will explain the beginner-level audio functions that come prepackaged with Danmakufu. These Audio Functions require little to no effort to use, and are easier to understand and utilize than Sound Objects. But of course, they have their limitations.

Now, there are a number of Audio Functions. LoadSound() MUST be called prior to using PlayBGM() or PlaySE(), as Danmakufu must load the audio files into memory. Additionally, LoadSound must be used in the same script as the Play functions. If you LoadSound in a System script, you cannot PlaySE with the same path in a Single script and expect the sound to play. You must load the files in the same script where you play them.

Of course, looking at the function list, there is also a RemoveSound(). If you do use LoadSound(), please use RemoveSound() in @Finalize. Removing loaded sounds is one of the only uses of @Finalize in ph3.

There are two Play functions and one Stop function, and their usage should be clear from the documentation on the Wiki. You give a path to the loaded sound effect or bgm track, and for BGM, you also give loop points. Anyways, it's about time I elaborated on what is acceptable for a BGM track and what is acceptable for a Sound Effect.

Part 3: Which File Types Should I Use?

Most people don't really know any better when it comes to audio files. I mean, they all hold sound, right? Well, yes. But each file type has its own strengths and weaknesses.

First, .mp3, which is undeniably the most popular way to share music due to its relatively small size, since it doesn't keep track of the parts of the music inaudible to most humans. In essence, it's meant for keeping audio tracks small. Unfortunately, it is not so great when looping. .mp3 tracks are used as BGM tracks but never for Sound Effects.

Next is .wav, which is uncompressed. In other words, they are gigantic. Some scripters find it convenient to use .wav files as BGM. This is not acceptable. A 50 MB .wav can easily be exported to a 10 MB .ogg, saving the user a lot in download time and disk space. However, for sound effects, .wav files are the preferred option because they are very small in file size and high-quality.

Then of course, there is OGG Vorbis. OGG Vorbis is Open Source and completely free, and works excellently as BGM in Danmakufu due to the support for looping. If you are going to loop your BGM, please do not open the track in Audacity and copy-paste the looped section 10 times or download a super extended version from Youtube. All you are doing is providing the player of your script with music files that are probably 5-10x as big as they should be. Simply export as .ogg using Audacity. Note that .ogg are rarely if ever used as Sound Effects. So don't use them for Sound Effects unless you're really trying to save space.

In conclusion, use .ogg for BGM and .wav for Sound Effects.

Part 4: How do I Create Sound Objects?

Now, I've already discussed the uses of Danmakufu's default audio functions. But what if you want to loop your tracks at a certain point? What if you want to control the volume? Now we're getting into Sound Object territory.

First, let's begin by creating Sound Objects. The Sound Object Functions are pretty confusing for those who are unfamiliar with dealing with music, so we'll go through them.

To create a Sound Object, we use ObjSound_Create(), which returns the ID of your sound object. A single sound object can be played multiple times.

Once you have created a sound object, you must give it a file path to the sound you want it to play, whether it is a bgm or a sound effect. You use ObjSound_Load(obj, filepath) to load a given sound file to the object. You can override this by loading a different sound at any time. After this, it is recommended to use ObjSound_SetSoundDivision() to state whether your sound object refers to a BGM or a sound effect. This function is completely optional.

Now of course, the goodies that I mentioned earlier, such as volume and looping. Let's take a look.

Part 5: How do I Use and Manipulate Sound Objects?

First we will discuss how to play sound objects. You use ObjSound_Play(), ObjSound_Stop(), and ObjSound_IsPlaying() to control sound objects. ObjSound_SetFade() can be used to fade the sound rather than abruptly stopping it.

If you want to play a sound object with a given volume, then use ObjSound_SetVolumeRate(). The volume goes from 0 to 100 linearly. It used to be exponential but this was changed. It is highly recommended that all your sound effects be around the same volume, as you will most likely want to use the same function for creating all of them. As for Pan Rate, controlled by ObjSound_SetPanRate(), you can control which earbud/side you want the sound to go to, with -100 being all to the left side and 100 to all on the right side. This is used in cases such as the warp sound effects in Subterranean Animism, where all of the sound effect goes to one ear and not the other. For most cases, you will never use this function, but it exists.

Now it is time to talk about looping. Sound objects by default do not loop. You must use ObjSound_SetLoopEnable() to allow a track to loop. After this, there are two main methods for how to loop - by time, and by sample.

To loop by time, use ObjSound_SetLoopTime(). For example, let's say that I have a music track where the loop starts at 5.43 seconds and the loop ends at 85.43 seconds. I will use the following to loop it:

    function CreateTrack{
	let obj = ObjSound_Create();
	ObjSound_Load(obj, GetCurrentScriptDirectory() ~ "./bgm/clownpiece.ogg");
	ObjSound_SetSoundDivision(obj, SOUND_BGM);
	ObjSound_SetLoopEnable(obj, true);
	ObjSound_SetLoopTime(obj, 5.43, 85.43);
	return obj;
    }

When it plays, it will play from the beginning, and once it hits the 85.43 second mark, it will go to the 5.43 second mark and continue playing from there. Any parts of the BGM after 85.43 seconds will not be played unless the loop time is changed. If the end loop time is greater than the length of the song, the song will return to the 5.43 second mark as soon as the entire track finishes - there will not be a period with no sound.

Samples are another way to loop tracks. For getting the sample counts, you must ask the composer or you must manually find them yourself using a tool such as Audacity. Loops work in a similar way, except that you use ObjSound_SetLoopSampleCount() instead.

To end this lesson, I will discuss restarting tracks using ObjSound_SetRestartEnable(). Easily the most frustrating function in the entire sound object section, it will, if set to true, restart the song from the very start if the sound object is stopped and restarted later. Otherwise the song will continue from where it left off when ObjSound_Play() is called. Combined with looping and stopping and playing and restarting, this function can be a royal pain to figure out, but it's quite useful if you need it. It is, however, an optional function. Don't use it unless you need it.

For future reference, I will be providing a sound effect library for public use here: Sparen's Sound Library. I suggest that you look at the tasks used to create the sound objects, and perhaps use them as a reference when creating your own.

Quiz: Sounds in Danmakufu

1) Junko wants her music to be as pure as possible. To ensure this, she wants her bgm to be recognized by Danmakufu as a BGM. How should she do this?

A. ObjSound_SetSoundDivision(SOUND_BGM);
B. ObjSound_SetSoundDivision(SOUND_SE);
C. ObjSound_SetSoundDivision(obj, SOUND_BGM);
D. ObjSound_SetSoundDivision(obj, SOUND_MUSIC);

2) Ringo is busy eating dango when she realizes that the music playing in Danmakufu suddenly jumped to a point in the middle of the song. What could have happened? Her code is below:

    ObjSound_SetLoopTime(obj, 27, 85); //not the actual loop points of Pumpkin of September, sorry

A. Her start point in the loop (27) is incorrect and should be lower
B. Her end point in the loop (85) is incorrect and should be higher
C. The bgm is shorter than one minute and 25 seconds

Part 6: How Can I Use Audacity to Export to .ogg?

In this tutorial, I've mentioned Audacity a lot, but for good reason. It's a free piece of open-source software that has all kinds of audio manipulation features. You can add effects, new tracks, and all kinds of stuff, or you can simply use it for looping music or exporting between different file types.

Since Audacity is a must-have for all Danmakufu scripter (and video game designers, to an extent), you should definitely get it and be familiar with how to use it. The official website is here and you can download the software here as well.

Anyways, I'll only go over exporting to .ogg here. First, open your .mp3/.wav/whatever sound file in Audacity. Then go to File -> Export Audio. Under file type, select OGG Vorbis. And then save! You're done.

As stated previously, .ogg files are vastly better when you need to loop music tracks in Danmakufu, so Audacity is a helpful tool.

Summary

• You must Load a sound before it can be played.
• Different file types have different types and advantages - .ogg is best for BGM and .wav is best for Sound Effects
• Sound Objects can be customized to loop, have volume rates and pan rates, and more

Sources and External Resources

N/A