LarryG on 22/10/2012 at 04:46

---

I thought I would post all that I have learned about songs so that those who know more can correct me and fill in the pieces, and those who know less than I do can learn at least as much as I know.

NOTE: This thread pertains to the original LGS song compiler and song player. It does not relate to the use of Telliamed's song compiler. That is a different animal. I took the approach that the LGS song compiler works just fine and we don't need a new one. All we needed was to understand the grammar of their schema files and how to use them. With 1.19 there are new capabilities which enabled the discovery of that grammar.


To start things off, I used the new DromEd command "songschema_dumpmono <name_of_song.snc_file>" to decompile all the T2 and SS2 songs I could find and dump the results to monolog. Those song schemas are found at the bottom of this post, giving us a good set of working examples to look at.

Overview
The Dark Engine has a "song player" which can play background music based on a special kind of playlist called a "song schema". You write the song schema in a simplistic human readable language designed specifically for the creating a playlist that can be sensitive to "events" occurring during gameplay. Once you have written the "song schema" you have to compile it into a binary file that the game uses. The DromEd command rebuild_songs is used to perform that compile and create the binary files for all the song schemas found in your songsrc directory. The binary files that get created are called a "songs" and are placed in your song directory by rebuild_songs. A mission can have only one song (playlist).

DromEd Aspects
The song to be used by a mission is specified using Editors > Mission Parameters > Song Parameters; just type the name of the song that you want he mission to use, and that song will automatically start to play when the mission starts. If you don't want music to start up right away, do what LGS did and start all your songs with a silent wav sound file. More about this later.

To send an "event" to the song so that it can respond and change what is playing, you place an ambientSound marker (fnord > ambientSound) and add the AmbientHacked property to it, setting the radius that the player must intrude, the Flags set to "Music", and the Schema set to the name of the event you want triggered. For example, in the T2 song M04SONG, if you want the "start" event to be triggered, you would put "start" as the Schema Name. So it would look like this:

[ATTACH=CONFIG]1426[/ATTACH]

Events are not responded to immediately. The currently playing wav file has to complete before the song player looks for new events. If multiple events are sent while a wav is playing, only most recently received event is responded to. So you probably shouldn't place your song ambientSound markers close to one another, and you probably shouldn't make your wav files such that they play for hours and hours before ending.

Writing Song Schemas
A song schema is a text file with a sns suffix found in your songsrc directory. It is a human readable file comprised of "song statements" and you can use Notepad or (http://notepad-plus-plus.org/) Notepad++ or equivalent to write it (I prefer Notepad++ and highly recommend it for this and other needs).

There are a very limited set of song statements, and I am not certain of the usage for all of them, but what I do know I will share. Note: carets (<, >) are used to bracket required parameter values.


* Song <name_of_song>
* DeclareSections <list of section_names separated by spaces>
* DeclareEvents * * * UNKNOWN FORMAT AND USAGE * * *
* Section <section_name>
* Sample <"name_of_wav">
* Silence * * * UNKNOWN FORMAT AND USAGE * * *
* Seconds * * * UNKNOWN FORMAT AND USAGE * * *
* Samples * * * UNKNOWN FORMAT AND USAGE * * *
* LoopCount <integral_number_of_times_to_loop>
* Immediate * * * UNKNOWN FORMAT AND USAGE * * *
* OnEvent <"theme event_name">
* GotoSection <section_name> Probability <percentage_value_ending_in_%>
* GoToEnd * * * UNKNOWN FORMAT AND USAGE * * *
* Volume * * * NOT IMPLEMENTED OR NOT WORKING * * *
* Pan * * * NOT IMPLEMENTED OR NOT WORKING * * *
* // <comment-text> -- I also think you can use a semi-colon after any other statement to add a comment to that line, but I have not tested that


A song schema must begin with a Song statement naming the song.

Following the Song statement you should have a DeclareSections statement listing all the different song sections in the song schema.

Following the DeclareSections statement come the song sections. A song section defines the wav to be played and what to do after playing the wav.

A song section starts with a Section statement defining the section name. This name is used by GotoSection statements which branch between the song sections.

Following the Section statement you can specify the number of times for the section to be played before testing events using the optional LoopCount statement (if omitted the section's sample, see the Sample statement below, is played only once before testing for events)

Next comes the Sample statement defining the name of the wav to be played by the section. The name of the wav must be enclosed in quotes. So if you want the wav file "begin.wav" to play, your Sample statement would be:

[INDENT]Sample "begin.wav"[/INDENT]


Following the Sample statement comes a series of OnEvent blocks. You should have an OnEvent block for every possible event in every song section. That way there is always an appropriate branch to take no matter what event a player happens to trip.

An OnEvent block begins with an OnEvent statement defining the event that triggers the following statements. If the current event is not the event named in the OnEvent statement, then the next OnEvent statement is examined until a match is found. The empty string ("") is used to define the block of statements to execute if there is no event that has been flagged, and the OnEvent "" statement should always be the first one found in each section. When you are define an OnEvent statement for an event, the keyword OnEvent must be followed by the word "theme" and the event_name, all enclosed in quotes. So if the event to be looked for is "start", the OnEvent statement is:

[INDENT]OnEvent "theme start"[/INDENT]


After the OnEvent statement a series of one or more GotoSection statements constitute the remainder of the OnEvent block. If you always want to branch to the section referred to in the GotoSection statement you should define the Probability to be 100%. If you want the song player to have multiple options for branching, you just use multiple GotoSection statements where the sum of the probabilities add up to 100%. Take a look at SS2's ENGSONG and ENGSONG2 for examples.

The Empty Section
LGS typically uses a special section called "empty" as the very first section. This section plays a silent wav until one of the possible mission events occurs. Take a look at any of the schemas below. This effectively keeps all music from playing until some event takes place.

Special Considerations
All wave files used in a song must have the exact same format. So, for example, if you use LGS's empty.wav, all of the other wavs that you use must be Microsoft PCM format Codec, 22050 sample rate, and 2 channels (stereo). Otherwise your custom wav files may play weirdly or not at all. And be sure to save your wav files to your snd directory. You can use a separate sub-directory just for your song if you wish, or just save them inside of snd.

Testing Your New Song in DromEd
You have all your wav files in snd, you have written your song schema, saved it to your songsrc directory as a sns file, compiled it using the DromEd command rebuild_songs, and checked that the binary snc file was written to your song directory. Now you want to test it out without going to all the trouble of placing ambientSound markers and having to walk all over your map. Fortunately there are a series of DromEd commands to help out. These are all the song related DromEd commands that I have found:



First you load the song using the load_song command. The song_name is the name of the snc file without the snc extension. So if your song binary is TESTSONG.snc, you would use the command

[INDENT]load_song testsong[/INDENT]

Next, play the song using the play_song command. If you don't hear anything, that's probably because you copied LGS and started your song schema with a silent section, and only want to make noise after the player triggers an event. So you need to emulate the triggering of an event. That's what the song_event command is for. Suppose you have an event called "start". To trigger it, you would type,

[INDENT]song_event "theme start"[/INDENT]

This will not trigger a change in sounds immediately; the current section needs to complete before the song player will test for a new event. So wait a bit, and you should hear the new section start up soon. In this manner you can test each event and make sure it does what you want before you start placing ambientSound markers.

If your song doesn't play, try loading one of the T2 songs and testing it. If that plays fine, then the problem may be with your wav files or with your song schema and you need to look closely at them. If an original T2 song doesn't play, then there may be something wrong with your DromEd setup. That's outside the scope of this tutorial.







SS2 - ENGSONG


SS2 - ENGSONG2


T2 - M01SONG


T2 - M04SONG


SS2 - SONG02



SS2 - SONG03



SS2 - SONG04



SS2 - SONG05



SS2 - SONG06



SS2 - SONG07



SS2 - SONG08 (Yeah, I see that it says Song06, but the file this came from was SONG08.SNC)



SS2 - SONG09



SS2 - SONG10



SS2 - SONG11



SS2 - SONG13



SS2 - SONG14

LarryG on 22/10/2012 at 17:14

---

You don't have to find it. It's built into DromEd. It is executed by the rebuild_songs DromEd command

LarryG on 22/10/2012 at 20:21

---

Added a testing section to the first post.