[V1.20 + v2.00] Tutorial 5: External Sound Files.
Welcome to Tutorial No. 5. The following tutorial will discuss about the sound implementation and the options implemented in Mission-X
The tutorial will cover the following topics:
The tutorial will cover the following topics:
- Introduction and technical staff
- How sound is implemented in the Mission file
- What are the attributes and their meanings
- Sound implementation example
- Download Demo
- How to stop a playing sound file.
- Finishing Words
Introduction and technical staff
Sound in Mission-X was implemented using FMOD library.
The FMOD library is a cross platform and it is used in many known applications and other titles that most of us are familiar with, you can head to their site and see for yourself.
When I read the API of the FMOD library I found out that it's "over qualified" for what I really needed, I aimed for a sound player, and I got a full feature orchestra library ( not that I'm complaining ). I decided that the plugin will not use all the bell and whistle that available with the library, instead I have implemented a simple file player that the library will handle, while the designer will need to "bake" the music in the relevant format. This also means that all effects will be done externally and the output of this work will be saved to a sound file that the plugin will read and play.
The benefits: Less CPU and library overhead.
The FMOD library is a cross platform and it is used in many known applications and other titles that most of us are familiar with, you can head to their site and see for yourself.
When I read the API of the FMOD library I found out that it's "over qualified" for what I really needed, I aimed for a sound player, and I got a full feature orchestra library ( not that I'm complaining ). I decided that the plugin will not use all the bell and whistle that available with the library, instead I have implemented a simple file player that the library will handle, while the designer will need to "bake" the music in the relevant format. This also means that all effects will be done externally and the output of this work will be saved to a sound file that the plugin will read and play.
The benefits: Less CPU and library overhead.
How sound is implemented in the Mission file
Since this is my first attempt to implement external sound support, I tried to use familiar elements that should already be known to the designer.I decided to integrate the sound calls with any message that works with the "Queue Message" mechanism, meaning Feedback and Event Messages. The benefits:
- Sound play is synch with text messages, if you so choose.
- Sound can be played based on mission-x events ( not FMOD events ).
What are the attributes and their meanings
There are only four new attributes that manage sound play and one new element that holds the sound file location.
Lets do a short introduction: First, we need to define the directory where all sound files will be store. For that I used a new Element under the GlobalSetting that was borrowed from next version, The element name is <Dir> short for directory.
Lets do a short introduction: First, we need to define the directory where all sound files will be store. For that I used a new Element under the GlobalSetting that was borrowed from next version, The element name is <Dir> short for directory.
<GlobalSettings>
...
<Dir customDir="hamburger01" soundDir="sound" />
</GlobalSettings>
...
<Dir customDir="hamburger01" soundDir="sound" />
</GlobalSettings>
As you can see there are two directories to define, the first is the mission's custom directory under the {X-Plane 9 }/Custom Scenery/missionx path, and the second is the sound sub directory under it.
This will result in: "{X-Plane 9 }/Custom Scenery/missionx/hamburger01/sound" path.
This will result in: "{X-Plane 9 }/Custom Scenery/missionx/hamburger01/sound" path.
Now that we defined the sound directory, we can place sound files in it and call them when using the broadcast element or the Event's Msg sub element.
* The new attributes that were added to all message elements are:
soundFile: The name of the file in directory ( case sensitive )
soundVol: The volume to play the file. Values between 0 and 1. There is no global sound volume, you need to define it each file.
muteVoice: Overrides message speaker synthesizer. In some cases you will broadcast a message and play a sound file. With the following attribute, you can instruct the Queue Manager process to only display the message as text, so no two sounds will play simultaneously.
soundMix: Allow you to play to files simultaneously if they overlap. Default is to stop the playing file, and start playing the new one.
That's it, these are the additions a designer will have to make in order to define and play a sound file during mission.
Now lets write a short example...
* The new attributes that were added to all message elements are:
soundFile: The name of the file in directory ( case sensitive )
soundVol: The volume to play the file. Values between 0 and 1. There is no global sound volume, you need to define it each file.
muteVoice: Overrides message speaker synthesizer. In some cases you will broadcast a message and play a sound file. With the following attribute, you can instruct the Queue Manager process to only display the message as text, so no two sounds will play simultaneously.
soundMix: Allow you to play to files simultaneously if they overlap. Default is to stop the playing file, and start playing the new one.
That's it, these are the additions a designer will have to make in order to define and play a sound file during mission.
Now lets write a short example...
Sound implementation example
<xml ...>
<Mission....>
<GlobalSettings>
<Map dirName="norway02" fileName="norway02.bmp" width="805" height="545" />
<Dir customDir="norway02" soundDir="sound" />
</GlobalSettings>
<Mission....>
<GlobalSettings>
<Map dirName="norway02" fileName="norway02.bmp" width="805" height="545" />
<Dir customDir="norway02" soundDir="sound" />
</GlobalSettings>
> You can see that there is duplication in <Dir> element and <Map...> element regarding directory names. This is done in order to be compatible with v1.20 xml format and not change the structure of the file as in v1.30.
> Please keep in mind that we need both <Dir> attributes to construct the sound directory path.
Next, we need to "play" a sound file.
Lets check these two examples:
> Please keep in mind that we need both <Dir> attributes to construct the sound directory path.
Next, we need to "play" a sound file.
Lets check these two examples:
First Example:
<Feedbacks>
<Broadcast id="1" distanceToBroadcast="5" soundFile="ding.wav" soundVol="0.2" >[<![CDATA[Some Message]]></Broadcast>
</Feedbacks>
<Feedbacks>
<Broadcast id="1" distanceToBroadcast="5" soundFile="ding.wav" soundVol="0.2" >[<![CDATA[Some Message]]></Broadcast>
</Feedbacks>
Second Example:
< Event id="1" type="onSuccess" >
<Msg repeatMsg ="0" soundFile="dong.wav" soundVol="0.2" ><![CDATA[Message Text]]></Msg>
</Event>
< Event id="1" type="onSuccess" >
<Msg repeatMsg ="0" soundFile="dong.wav" soundVol="0.2" ><![CDATA[Message Text]]></Msg>
</Event>
You can see that the implementation is the same in both cases.
The other two sound attributes I did not used since their default values are sufficient for this example. All that is left is to test the outcome and check if the sound played as expected.
The other two sound attributes I did not used since their default values are sufficient for this example. All that is left is to test the outcome and check if the sound played as expected.
Download Demo
Tutorial 05 - Sound example
You can download the following file to test the Sound implementation.
Installation Guide:
You can download the following file to test the Sound implementation.
Installation Guide:
- Unpack the file into X-Plane install directory.
It will merge its directories into the existing ones, so no worry regarding overtiring. - Launch X-Plane, and load Tutorial_05.xml .
- Take off from LOWI, and hear the sound ( it should be right after you leave the runway airspace ).
How to stop a playing sound file
Currently there is no flag that stops the sound file, nor a timer that will shut it automatically.The only way to stop a playing sound file, is to play another file with attribute soundMix set to zero ( 0 ), which is also the default.
I have added a short silence.mp3 file (~0.5 sec long ), that has no sound to the tutorial demo directory. I did not use it in the demo, but all you need to do:
Add an area with event that causes the silence.mp3 to play or add event to existing area that will have the opposite sound outcome regarding an action. for example: onEnter event, will play file XXX.mp3 and onLeave will play silence.mp3 just remember to set "stopOnReach" attribute to zero at the areaZone element.
I have added a short silence.mp3 file (~0.5 sec long ), that has no sound to the tutorial demo directory. I did not use it in the demo, but all you need to do:
Add an area with event that causes the silence.mp3 to play or add event to existing area that will have the opposite sound outcome regarding an action. for example: onEnter event, will play file XXX.mp3 and onLeave will play silence.mp3 just remember to set "stopOnReach" attribute to zero at the areaZone element.
Finishing Words
The external sound file support is a welcome addition indeed, but I do not want to raise expectations that designer will widely use this feature in their missions. Though the implementation is quite simple, the real deal is to get the right sounds and "bake" them. This is not a simple process and as of this writing there are no missions that use it yet...
But, I hope that this simple platform will benefit designers in the near future, if they so choose.
Until then, you are welcome to send me an e-mail regarding the tutorial and the implementation of this feature.
Enjoy
Snagar
But, I hope that this simple platform will benefit designers in the near future, if they so choose.
Until then, you are welcome to send me an e-mail regarding the tutorial and the implementation of this feature.
Enjoy
Snagar