Difference between revisions of "Music.tbl"

From FreeSpace Wiki
Jump to: navigation, search
(...you've no clue. I tried to make the top half (pertaining to soundtrack) more human-readable while drastically cutting down the format sample at the bottom to the necessary portions. I'll work on menu music on my next edit.)
(Related Links)
 
(20 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
{{TableVersion|5307}}
 
{{TableVersion|5307}}
 
+
{{Tables}}
'''music.tbl''' is a [[Tables|table file]] used by the ''FreeSpace'' game engine to define the [[music]] played during the game.
+
<code>'''music.tbl'''</code> is a [[Tables|table file]] used by the ''FreeSpace'' game engine to define the [[music]] played during the game.
  
 
In FSO, this table can be further extended with any [[modular table]] with a filename ending with <code>-mus</code> (e.g. <code>AF-mus.tbm</code>, <code>bp-mus.tbm</code>, <code>v_music-mus.tbm</code>).
 
In FSO, this table can be further extended with any [[modular table]] with a filename ending with <code>-mus</code> (e.g. <code>AF-mus.tbm</code>, <code>bp-mus.tbm</code>, <code>v_music-mus.tbm</code>).
  
== Description ==
 
 
<code>music.tbl</code> consists of two sections defined as follows:
 
<code>music.tbl</code> consists of two sections defined as follows:
 
# The soundtracks, which are music files intended to be played ''during a mission''.
 
# The soundtracks, which are music files intended to be played ''during a mission''.
 
# The menu music, which are music files intended to be played for other purposes.
 
# The menu music, which are music files intended to be played for other purposes.
  
Comments (which are not read by the game engine) can be added at the start of a line or after any line containing formatting using a semicolon (<code>;</code>).
+
Comments (which are not parsed by the game engine) can be added at the start of a line, or after any line containing formatting, by beginning with a semicolon (<code>;</code>).
  
 
<code>-mus.tbm</code> modular tables use the exact same formatting as <code>music.tbl</code>.
 
<code>-mus.tbm</code> modular tables use the exact same formatting as <code>music.tbl</code>.
  
 
== Soundtrack ==
 
== Soundtrack ==
Each individual soundtrack should start with <code>#SoundTrack Start</code> and end with <code>#SoundTrack End</code>.
+
'''Each''' individual soundtrack '''must''' start with <code>#SoundTrack Start</code>, end with <code>#SoundTrack End</code>, and have the following lines in between:
 +
# <code>$Soundtrack Name:</code>
 +
# One of the following:
 +
::* 12 lines, all starting with <code>$Name:</code>
 +
{{Table3610|
 +
::* 12-14 lines, all starting with <code>$Name:</code>
 +
::* 14 lines, all starting with <code>$String:</code>
 +
}}
 +
 
 
=== $Soundtrack Name: ===
 
=== $Soundtrack Name: ===
<code>$Soundtrack Name:</code> is immediately followed by the soundtrack order number and the name of the soundtrack.
+
<code>$Soundtrack Name:</code> is immediately followed by the name of the soundtrack. This primarily affects how the soundtrack is referred to in [[FRED]] as well as its variants. The name of the soundtrack can be prefixed with a number to keep listings organised, such as the underlined code below:
*Syntax: '''Integer''': '''String'''
+
  $Soundtrack Name: <u>1: Genesis</u>
**Example: 1: Genesis
 
  
 
==== Flags ====
 
==== Flags ====
 
{{Table3610|
 
{{Table3610|
The following flags can be added in additional lines after <code>$Soundtrack Name:</code> in [[modular table]]s.
+
The following flags can be added in extra lines after <code>$Soundtrack Name:</code> in [[modular table]]s.
  
 
===== +nocreate =====
 
===== +nocreate =====
This flag should be added if the soundtrack is intended to completely overwrite an existing soundtrack.
+
This flag should be added if the soundtrack is intended to completely overwrite an existing soundtrack with the exact same name.
  
 
===== +Cycle: FS1 =====
 
===== +Cycle: FS1 =====
This cycles the NRML and BTTL tracks the FS1 way, instead of the FS2 way.
+
This cycles the Normal and Battle tracks the FS1 way, instead of the FS2 way.
  
 
===== +Allied Arrival Overlay: NO =====
 
===== +Allied Arrival Overlay: NO =====
Line 42: Line 48:
 
{| border=1 cellpadding=4 style="border-collapse: collapse; border: solid 1px #995050;"
 
{| border=1 cellpadding=4 style="border-collapse: collapse; border: solid 1px #995050;"
 
|- align="center" colspan=3 style="background:#351515; border: solid 1px #995050;"
 
|- align="center" colspan=3 style="background:#351515; border: solid 1px #995050;"
! $Name: ('''required''') !! Filename !! Number of measures (''m'') !! Samples per measure (''s'') !! Comments (optional)
+
! $Name: (''fixed'') !! Filename !! Number of Measures (''m'') !! Samples per Measure (''s'') !! Comments (optional)
 
|- align="left"
 
|- align="left"
 
| <code>$Name:</code> || <code>FS2_Amb_A01.wav</code> || <code>25.0</code> || <code>105840</code> || <code>; * Ambience</code>  
 
| <code>$Name:</code> || <code>FS2_Amb_A01.wav</code> || <code>25.0</code> || <code>105840</code> || <code>; * Ambience</code>  
 
|}
 
|}
  
====$Name:====
+
The subsections describe each of the above columns in more detail.
 +
 
 +
==== $Name: ====
 
The individual music segments in a soundtrack is defined using '''at least 12 lines''', all beginning with <code>$Name:</code>. The ''FreeSpace'' engine parses and plays the audio file referenced in each line in the following order:
 
The individual music segments in a soundtrack is defined using '''at least 12 lines''', all beginning with <code>$Name:</code>. The ''FreeSpace'' engine parses and plays the audio file referenced in each line in the following order:
  
Line 54: Line 62:
 
! Order !! Situation !! Details
 
! Order !! Situation !! Details
 
|- align="left"
 
|- align="left"
| 1 || Ambience || Normal track&mdash;plays when nothing is happening or units are out of combat range
+
| 1 || Ambience || Normal track.<br/>Plays when nothing is happening or units are out of combat range.<br/>Loops on itself until another situation is called, but if Ambience 2 is defined in FSO builds, will usually segue to it.
 
|-  
 
|-  
| 2 || Allied Arrival during Ambience || Plays when a friendly unit arrives while Ambience is playing
+
| 2 || Allied Arrival during Ambience || Plays when a friendly unit arrives while Ambience is playing.<br/>By default, plays on top of other audio tracks without seguing; in FSO builds, if <code>+Allied Arrival Overlay: NO</code> is added below <code>$Soundtrack Name:</code>, the currently playing track will segue into this instead.
 
|-  
 
|-  
| 3 || Enemy Arrival during Ambience || Plays when a hostile unit arrives while Ambience is playing
+
| 3 || Enemy Arrival during Ambience || Plays when a hostile unit arrives while Ambience is playing.
 
|-  
 
|-  
| 4 || Battle 1 || Battle track 1&mdash;plays when units are in combat range; usually segues into Battle 2
+
| 4 || Battle 1 || Battle track 1.<br/>Plays when units are in combat range.<br/>Usually segues into Battle 2.
 
|-  
 
|-  
| 5 || Battle 2 || Battle track 2&mdash;plays when units are in combat range; usually segues into Battle 3
+
| 5 || Battle 2 || Battle track 2.<br/>Plays when units are in combat range.<br/>Usually segues into Battle 3.
 
|-  
 
|-  
| 6 || Battle 3 || Battle track 3&mdash;plays when units are in combat range; usually segues into Battle 1
+
| 6 || Battle 3 || Battle track 3.<br/>Plays when units are in combat range.<br/>Usually segues into Battle 1.
 
|-  
 
|-  
| 7 || Allied Arrival during Battle || Plays when a friendly unit arrives while any Battle track is playing
+
| 7 || Allied Arrival during Battle || Plays when a friendly unit arrives while any Battle track is playing.<br/>By default, plays on top of other audio tracks without seguing; in FSO builds, if <code>+Allied Arrival Overlay: NO</code> is added below <code>$Soundtrack Name:</code>, the currently playing track will segue into this instead.
 
|-  
 
|-  
| 8 || Enemy Arrival during Battle || Plays when a hostile unit arrives while any Battle track is playing
+
| 8 || Enemy Arrival during Battle || Plays when a hostile unit arrives while any Battle track is playing.
 
|-  
 
|-  
| 9 || Victory 1 || Plays when a goal is completed
+
| 9 || Victory 1 || Plays when a goal is completed.<br/>Segues into Victory 2, Ambience, or a Battle track depending on the remaining goals and hostile units remaining, and whether Victory 2 has already been called.
 
|-  
 
|-  
| 10 || Victory 2 || Plays when all goals are completed ''and'' there are absolutely no hostile units present; is only called once
+
| 10 || Victory 2 || Victory 1 segues into this track when all goals are completed ''and'' there are absolutely no hostile units present.<br/>Is only called once; if additional goals are validated in-mission and/or new hostile units arrive after this track has already been played, Victory 1 will segue into Ambience or a Battle track.
 
|-  
 
|-  
| 11 || Goal Failed || Plays when the primary goals of a mission are failed; does not appear to be called in-game
+
| 11 || Goal Failed || Plays when the goals of a mission are failed.<br/>Does not appear to be called in-game.
 
|-  
 
|-  
| 12 || Player Dies || Plays when the player is killed and goes to the death screen
+
| 12 || Player Dies || Plays when the player is killed and goes to the death screen.
 
|}
 
|}
 
{{Table3610|
 
{{Table3610|
Line 84: Line 92:
 
! Order !! Situation !! Details
 
! Order !! Situation !! Details
 
|- align="left"
 
|- align="left"
| 13 || Ambience 2 || Normal track&mdash;if Ambience 3 is defined, usually segues into it, otherwise segues into Ambience
+
| 13 || Ambience 2 || Normal track.<br/>Plays when nothing is happening or units are out of combat range.<br/>If Ambience 3 is defined, usually segues into it, otherwise segues into Ambience.
 
|-  
 
|-  
| 14 || Ambience 3 || Normal track&mdash;usually segues into Ambience
+
| 14 || Ambience 3 || Normal track.<br/>Plays when nothing is happening or units are out of combat range.<br/>Usually segues into Ambience.
 
|}
 
|}
  
The order and situation of the 12 lines '''cannot be changed''' and are '''required''' in order for the engine to parse the audio files in the correct situations. If there is no audio file available for any of the situations (such as Battle 3, for instance), a placeholder line denoting an empty track should still be included, like so:
+
The order and situation of the lines '''cannot be changed''' and are '''required''' in order for the engine to parse the audio files in the correct situations. If there is no audio file available for any of the situations (such as Battle 3, for instance), a placeholder line denoting an empty track should still be included, such as the bolded code below:
 
   ...
 
   ...
 
   $Name: FS2_Btl_A02.wav 27.8 81415 ; * Battle 2
 
   $Name: FS2_Btl_A02.wav 27.8 81415 ; * Battle 2
Line 97: Line 105:
  
 
====Filename====
 
====Filename====
The filename of the audio file must also include its file extension. FS1 and FS2 only support the playback of Waveform Audio (.wav) files; FSO supports the playback of .wav and OGG vorbis (.ogg) files.
+
The filename of the audio file must also include its file extension. FS1 and FS2 only support the playback of Waveform Audio (<code>.wav</code>) files.
  
====Measures and Samples per Measure====
+
{{Table36|
 +
FSO supports the playback of Waveform Audio and OGG Vorbis (<code>.ogg</code>) files.
 +
 
 +
If there are two versions of the same file&mdash;one in Waveform Audio and one in OGG Vorbis format&mdash;FSO will typically attempt to play the OGG Vorbis version, even if the referenced file in <code>music.tbl</code> has a <code>.wav</code> file extension. In addition, if <code>$Name:</code> references a file that has the <code>.ogg</code> file extension, but only a Waveform Audio version of the file is available, FSO will still play the latter as if it is referenced directly in <code>music.tbl</code>.
 +
}}
 +
 
 +
====Number of Measures and Samples per Measure====
 
The ''FreeSpace'' engine's dynamic music capabilities are defined using the number of measures (''m'') and samples per measure (''s''). Using ''m'', the engine parses the audio track by dividing it into individual parts, called ''measures''; if an event happens that would change the music being played, the game will play the current audio track until the end of the current measure, whereupon it segues into the correct audio track via a built-in crossfade. The length of the measures is defined using ''s'', which is the number of ''samples'' in a measure.
 
The ''FreeSpace'' engine's dynamic music capabilities are defined using the number of measures (''m'') and samples per measure (''s''). Using ''m'', the engine parses the audio track by dividing it into individual parts, called ''measures''; if an event happens that would change the music being played, the game will play the current audio track until the end of the current measure, whereupon it segues into the correct audio track via a built-in crossfade. The length of the measures is defined using ''s'', which is the number of ''samples'' in a measure.
  
Line 126: Line 140:
 
   $Name: FS2_Amb_A01.wav 31.3 88200 ; * Ambience  
 
   $Name: FS2_Amb_A01.wav 31.3 88200 ; * Ambience  
  
===Specific Music Tracks===
 
 
{{Table3610|
 
{{Table3610|
*If table doesn't have retail like '''$Name:''' at the beginning of the line then a new method for parsing tables can be used
+
=== $String: ===
*Instead $'''String''': can be used where the string is shortened name of the music track.
+
FSO includes an alternate way to parse individual tracks.
*After the initial entry on the line, rest of the music entry is added after it.
+
 
*Name of the music track, name of the associated music file with file extension, number of measure, number of samples per measure
+
Instead of using <code>$Name:</code>, <code>$String:</code> can be used, with the <code>''String''</code> syntax being the situation reference, such as:
*Syntax: $'''String''': '''String''' '''Float''' '''Integer'''
+
  $Normal 1: FS2_Amb_A01.ogg 25.0 105840 ; * Ambience
*Example: $Battle 1:     FS2_Btl_G01.ogg           25.8  176400
+
 
*Note that this system still requires a specific order, and a different one from the original.
+
Note that this system follows a different situation order from parsing <code>$Name:</code>, and it also cannot be changed under any circumstances. The situation order for parsing <code>$String:</code>, as well as the corresponding <code>$String:</code> to use for each situation, is as follows:
 
}}
 
}}
{|-
+
{| border=1 cellpadding=4 style="border-collapse: collapse; border: solid 1px #995050;"
| style="width:350px"|'''Ambience'''
+
|- align="center" colspan=3 style="background:#351515; border: solid 1px #995050;"
| style="width:100px"|''"Normal 1"''
+
! Order !! Situation !! <code>$String:</code> to Use !! Details
 +
|- align="left"
 +
| 1 || Ambience || <code>$Normal 1:</code> || Normal track&mdash;plays when nothing is happening or units are out of combat range; usually segues into Ambience 2
 
|-
 
|-
|'''Ambience 2'''
+
| 2 || Ambience 2 || <code>$Normal 2:</code> || Normal track&mdash;plays when nothing is happening or units are out of combat range; usually segues into Ambience 3
|''"Normal 2"''
 
 
|-
 
|-
|'''Ambience 3'''
+
| 3 || Ambience 3 || <code>$Normal 3:</code> || Normal track&mdash;plays when nothing is happening or units are out of combat range; usually segues into Ambience
|''"Normal 3"''
 
 
|-
 
|-
|'''Allied Arrival during Normal'''
+
| 4 || Allied Arrival during Ambience || <code>$Ally arrival 1:</code> || Plays when a friendly unit arrives while any Ambience track is playing
|''"Ally arrival 1"''
 
 
|-
 
|-
|'''Allied Arrival during Battle'''
+
| 5 || Allied Arrival during Battle || <code>$Ally arrival 2:</code> || Plays when a friendly unit arrives while any Battle track is playing
|''"Ally arrival 2"''
 
 
|-
 
|-
|'''Enemy Arrival during Normal'''
+
| 6 || Enemy Arrival during Ambience || <code>$Enemy arrival 1:</code> || Plays when a friendly unit arrives while any Ambience track is playing
|''"Enemy arrival 1"''
 
 
|-
 
|-
|'''Enemy Arrival during Battle'''
+
| 7 || Enemy Arrival during Battle || <code>$Enemy arrival 2:</code> || Plays when a friendly unit arrives while any Battle track is playing
|''"Enemy arrival 2"''
 
 
|-
 
|-
|'''Battle 1'''
+
| 8 || Battle 1 || <code>$Battle 1:</code> || Battle track 1—plays when units are in combat range; usually segues into Battle 2
|''"Battle 1"''
 
 
|-
 
|-
|'''Battle 2'''
+
| 9 || Battle 2 || <code>$Battle 2:</code> || Battle track 2—plays when units are in combat range; usually segues into Battle 3
|''"Battle 2"''
 
 
|-
 
|-
|'''Battle 3'''
+
| 10 || Battle 3 || <code>$Battle 3:</code> || Battle track 3—plays when units are in combat range; usually segues into Battle 1
|''"Battle 3"''
 
 
|-
 
|-
|'''Goal Failed'''
+
| 11 || Goal Failed || <code>$Failure 1:</code> || Plays when the primary goals of a mission are failed
|''"Failure 1"''
 
 
|-
 
|-
|'''Victory 1 ( goal completed )'''
+
| 12 || Victory 1 || <code>$Victory 1:</code> || Plays when a goal is completed
|''"Victory 1"''
 
 
|-
 
|-
|'''Victory 2 ( all enemies dead, goals completed )'''
+
| 13 || Victory 2 || <code>$Victory 2:</code> || Plays when all goals are completed and there are absolutely no hostile units present; is only called once
|''"Victory 2"''
 
|-
 
|'''Player dies'''
 
|''"Dead 1"''
 
 
|-
 
|-
 +
| 14 || Player Dies || <code>$Dead 1:</code> || Plays when the player is killed and goes to the death screen
 
|}
 
|}
  
 
== Menu Music ==
 
== Menu Music ==
*Menu music tracks are defined with '''filename''' after the track's '''name'''.
+
All menu music tracks are defined in the lines within '''one''' instance of <code>#Menu Music Start</code> and <code>#Menu Music End</code>. Up to 50 menu music tracks can be defined across all <code>.tbl</code> and <code>-mus.tbm</code> files being referenced.
*There is a limit of 50 menu music tracks.
 
*Syntax for all of the '''Menu Music''' entries are similar
 
*Syntax: $Filename: ''Filename.xxx''
 
**Example: $Filename: FS2_Brief_01.wav
 
  
 +
Each menu music track '''must''' have the following 2 lines in order:
 +
# <code>$Name:</code>
 +
# <code>$Filename:</code>
 +
 +
For the subsections, refer to the code used to call <code>FS2_Brief_01.wav</code> in-game, which is:
 +
  $Name: Brief1
 +
  $Filename: FS2_Brief_01.wav ; briefing music 1
  
===$Name:===
+
=== $Name: ===
*Defines the name of the menu music
+
The first line always starts with <code>$Name:</code>, followed by the name of the audio track, which is mainly referred to in FRED and its variants.
*Syntax: '''String'''
+
  $Name: Brief1
  
===+nocreate===
 
 
{{Table3610|
 
{{Table3610|
*Used with [[Modular Tables|modular tables]] to set the parser to use the modular table only for modifying an existing entry instead of creating new (possibly incomplete) one.}}
+
* The following flag can be added after <code>$Name:</code> in modular tables:
 +
=== +nocreate ===
 +
This flag should be added if the track is intended to completely overwrite an existing track with the exact same name.
 +
}}
  
 
+
=== $Filename: ===
===$Filename:===
+
The last line starts with <code>$Filename:</code>, followed by the file name of the audio track.
*Defines the actual file
+
  $Filename: FS2_Brief_01.wav ; briefing music 1
*Syntax: '''String''', filename with file extension
 
  
 
== Format Sample ==
 
== Format Sample ==
Line 253: Line 258:
 
   $Filename: FS2_Brief_03.wav ; briefing music 3
 
   $Filename: FS2_Brief_03.wav ; briefing music 3
 
   #Menu Music End
 
   #Menu Music End
 +
 +
== Related Links ==
 +
* [https://www.hard-light.net/forums/index.php?topic=89836.msg1787087 Music tables 301 | Hard Light Productions Forums]
 +
* [https://web.archive.org/web/20010314181125/http://ml.warpcore.org/fdl/199911/msg00204.html Archived post about music.tbl from the FreeSpace Developer List]
  
 
[[Category:Tables]]
 
[[Category:Tables]]

Latest revision as of 05:06, 26 November 2022

Revision information.....

FSO Revision: 5307
Note: Please update the version when the page is updated. If your edit had nothing to do with new code entries then please do not edit the version


List of Tables and related code files
* Notes Modular Tables
** Notes tables which only use modular tables
Ai.tbl* /ai/aicode.cpp
Ai_profiles.tbl* /ai/ai_profiles.cpp
Animation.tbl** /model/modelanimation.cpp
Armor.tbl* /ship/ship.cpp
Asteroid.tbl* /asteroid/asteroid.cpp
Autopilot.tbl* /autopilot/autopilot.cpp
Cheats.tbl* /cheats_table/cheats_table.cpp
Colors.tbl* /globalincs/alphacolors.cpp
Curves.tbl* /math/curves.cpp
Controlconfigdefaults.tbl /controlconfig/controlsconfigcommon.cpp
Credits.tbl* /menuui/credits.cpp
Cutscenes.tbl* /cutscene/cutscenes.cpp
Decals.tbl** /decals/decals.cpp
Fireball.tbl* /fireball/fireballs.cpp
Fonts.tbl* /graphics/font.cpp
Game_settings.tbl* /mod_table/mod_table.cpp
Glowpoints.tbl* /model/modelread.cpp
Help.tbl* /gamehelp/contexthelp.cpp
Hud_gauges.tbl* /hud/hudparse.cpp
Icons.tbl* /mission/missionbriefcommon.cpp
Iff_defs.tbl* /iff_defs/iff_defs.cpp
Lighting_Profiles.tbl* /lighting/lighting_profiles.cpp
Lightning.tbl* /nebula/neblightning.cpp
Mainhall.tbl* /menuui/mainhallmenu.cpp
Medals.tbl* /stats/medals.cpp
Messages.tbl* /mission/missionmessage.cpp
Mflash.tbl* /weapon/muzzleflash.cpp
Music.tbl* /gamesnd/eventmusic.cpp
Nebula.tbl* /nebula/neb.cpp
Objecttypes.tbl* /ship/ship.cpp
Options.tbl* Not In Codebase
Particle effects(-part.tbm)** /particle/effects...
Post_processing.tbl /graphics/gropenglpostprocessing.cpp
Rank.tbl* /stats/scoring.cpp
Scpui.tbl* Not In Codebase
Scripting.tbl* /parse/scripting.cpp
Ships.tbl* /ship/ship.cpp
Sexps.tbl** /parse/sexp/sexp_lookup.cpp
Sounds.tbl* /gamesnd/gamesnd.cpp
Species_defs.tbl* /species_defs/species_defs.cpp
Species.tbl* /menuui/techmenu.cpp
Ssm.tbl* /hud/hudartillery.cpp
Stars.tbl* /starfield/starfield.cpp
Strings.tbl* /localization/localize.cpp
Tips.tbl* /menuui/playermenu.cpp
Traitor.tbl* /stats/scoring.cpp
Tstrings.tbl* /localization/localize.cpp
Virtual_pofs.tbl* /model/modelreplace.cpp
Weapon_expl.tbl* /weapon/weapons.cpp
Weapons.tbl* /weapon/weapons.cpp

music.tbl is a table file used by the FreeSpace game engine to define the music played during the game.

In FSO, this table can be further extended with any modular table with a filename ending with -mus (e.g. AF-mus.tbm, bp-mus.tbm, v_music-mus.tbm).

music.tbl consists of two sections defined as follows:

  1. The soundtracks, which are music files intended to be played during a mission.
  2. The menu music, which are music files intended to be played for other purposes.

Comments (which are not parsed by the game engine) can be added at the start of a line, or after any line containing formatting, by beginning with a semicolon (;).

-mus.tbm modular tables use the exact same formatting as music.tbl.

Soundtrack

Each individual soundtrack must start with #SoundTrack Start, end with #SoundTrack End, and have the following lines in between:

  1. $Soundtrack Name:
  2. One of the following:
  • 12 lines, all starting with $Name:
FS2 Open 3.6.10:
  • 12-14 lines, all starting with $Name:
  • 14 lines, all starting with $String:

$Soundtrack Name:

$Soundtrack Name: is immediately followed by the name of the soundtrack. This primarily affects how the soundtrack is referred to in FRED as well as its variants. The name of the soundtrack can be prefixed with a number to keep listings organised, such as the underlined code below:

  $Soundtrack Name: 1: Genesis

Flags

FS2 Open 3.6.10:

The following flags can be added in extra lines after $Soundtrack Name: in modular tables.

+nocreate

This flag should be added if the soundtrack is intended to completely overwrite an existing soundtrack with the exact same name.

+Cycle: FS1

This cycles the Normal and Battle tracks the FS1 way, instead of the FS2 way.

+Allied Arrival Overlay: NO

This allows the Allied Arrival track to play on its own, as it did in FS1.

$Name:

For this section, refer to the code for FS2_Amb_A01.wav, as follows:

  $Name:	FS2_Amb_A01.wav				25.0	105840	; * Ambience 

The code above can be explained using the following table:

$Name: (fixed) Filename Number of Measures (m) Samples per Measure (s) Comments (optional)
$Name: FS2_Amb_A01.wav 25.0 105840 ; * Ambience

The subsections describe each of the above columns in more detail.

$Name:

The individual music segments in a soundtrack is defined using at least 12 lines, all beginning with $Name:. The FreeSpace engine parses and plays the audio file referenced in each line in the following order:

Order Situation Details
1 Ambience Normal track.
Plays when nothing is happening or units are out of combat range.
Loops on itself until another situation is called, but if Ambience 2 is defined in FSO builds, will usually segue to it.
2 Allied Arrival during Ambience Plays when a friendly unit arrives while Ambience is playing.
By default, plays on top of other audio tracks without seguing; in FSO builds, if +Allied Arrival Overlay: NO is added below $Soundtrack Name:, the currently playing track will segue into this instead.
3 Enemy Arrival during Ambience Plays when a hostile unit arrives while Ambience is playing.
4 Battle 1 Battle track 1.
Plays when units are in combat range.
Usually segues into Battle 2.
5 Battle 2 Battle track 2.
Plays when units are in combat range.
Usually segues into Battle 3.
6 Battle 3 Battle track 3.
Plays when units are in combat range.
Usually segues into Battle 1.
7 Allied Arrival during Battle Plays when a friendly unit arrives while any Battle track is playing.
By default, plays on top of other audio tracks without seguing; in FSO builds, if +Allied Arrival Overlay: NO is added below $Soundtrack Name:, the currently playing track will segue into this instead.
8 Enemy Arrival during Battle Plays when a hostile unit arrives while any Battle track is playing.
9 Victory 1 Plays when a goal is completed.
Segues into Victory 2, Ambience, or a Battle track depending on the remaining goals and hostile units remaining, and whether Victory 2 has already been called.
10 Victory 2 Victory 1 segues into this track when all goals are completed and there are absolutely no hostile units present.
Is only called once; if additional goals are validated in-mission and/or new hostile units arrive after this track has already been played, Victory 1 will segue into Ambience or a Battle track.
11 Goal Failed Plays when the goals of a mission are failed.
Does not appear to be called in-game.
12 Player Dies Plays when the player is killed and goes to the death screen.
FS2 Open 3.6.10:
  • The following lines can be added.
Order Situation Details
13 Ambience 2 Normal track.
Plays when nothing is happening or units are out of combat range.
If Ambience 3 is defined, usually segues into it, otherwise segues into Ambience.
14 Ambience 3 Normal track.
Plays when nothing is happening or units are out of combat range.
Usually segues into Ambience.

The order and situation of the lines cannot be changed and are required in order for the engine to parse the audio files in the correct situations. If there is no audio file available for any of the situations (such as Battle 3, for instance), a placeholder line denoting an empty track should still be included, such as the bolded code below:

  ...
  $Name:	FS2_Btl_A02.wav				27.8	81415	; * Battle 2
  $Name:	silence.wav				0.0	0	; * Battle 3
  $Name:	FS2_AArv_A01.wav			1.8	105840	; * Allied Arrival during Battle
  ...

Filename

The filename of the audio file must also include its file extension. FS1 and FS2 only support the playback of Waveform Audio (.wav) files.


FS2 Open, 3.6.x:

FSO supports the playback of Waveform Audio and OGG Vorbis (.ogg) files.

If there are two versions of the same file—one in Waveform Audio and one in OGG Vorbis format—FSO will typically attempt to play the OGG Vorbis version, even if the referenced file in music.tbl has a .wav file extension. In addition, if $Name: references a file that has the .ogg file extension, but only a Waveform Audio version of the file is available, FSO will still play the latter as if it is referenced directly in music.tbl.

Number of Measures and Samples per Measure

The FreeSpace engine's dynamic music capabilities are defined using the number of measures (m) and samples per measure (s). Using m, the engine parses the audio track by dividing it into individual parts, called measures; if an event happens that would change the music being played, the game will play the current audio track until the end of the current measure, whereupon it segues into the correct audio track via a built-in crossfade. The length of the measures is defined using s, which is the number of samples in a measure.

m is user-defined and can be set to a decimal point for greater fine-tuning.

s is calculated using the following formula:

  s = 2 × sample rate (hertz) × total audio length (seconds; up to 3 decimal places) ÷ m

Depending on the m and s values declared, the game may only play a portion of the actual audio file or, if the values result in it attempting to play the audio file beyond its actual length, playing nothing for a period of time after it finishes playing the actual audio file.

In the case of FS2_Amb_A01.wav, it is defined in music.tbl as an audio track that has 25 m and 105,840 s, so even though the file has an actual audio length of 62.556 seconds, the engine only ever parses the first 60 seconds of the audio file as its total audio length (hence omitting the last 2.556 seconds), split into 25 measures. This is because a reversal of the above calculation for s results in:

  105,840 (s) × 25 (m) ÷ 22,050 (hertz) ÷ 2 = 60.000 seconds

The length of the measures in the audio track cannot be individually adjusted by any meanss applies to all the measures in the audio file with no exceptions.

Alternate Calculation Method

If defining m and s is too time-consuming, the following formulae can be used to still make use of the FreeSpace engine's dynamic music capabilities, and would result in a maximum of 2 seconds' silence (since each measure would be 2 seconds long):

  m = audio file length (seconds; up to 3 decimal places) ÷ 2
  s = 4 × sample rate (hertz)

As an example, if we use the above alternate formulae with the actual audio length of FS2_Amb_A01.wav, we get the following:

  m = 62.556 seconds ÷ 2 = 31.278
  s = 4 × 22,050 (hertz) = 88,200

m would be rounded to the nearest decimal point. Hence, we would input the following as the alternate length for FS2_Amb_A01.wav in music.tbl:

  $Name:	FS2_Amb_A01.wav				31.3	88200	; * Ambience 


FS2 Open 3.6.10:

$String:

FSO includes an alternate way to parse individual tracks.

Instead of using $Name:, $String: can be used, with the String syntax being the situation reference, such as:

  $Normal 1:	FS2_Amb_A01.ogg				25.0	105840	; * Ambience 

Note that this system follows a different situation order from parsing $Name:, and it also cannot be changed under any circumstances. The situation order for parsing $String:, as well as the corresponding $String: to use for each situation, is as follows:

Order Situation $String: to Use Details
1 Ambience $Normal 1: Normal track—plays when nothing is happening or units are out of combat range; usually segues into Ambience 2
2 Ambience 2 $Normal 2: Normal track—plays when nothing is happening or units are out of combat range; usually segues into Ambience 3
3 Ambience 3 $Normal 3: Normal track—plays when nothing is happening or units are out of combat range; usually segues into Ambience
4 Allied Arrival during Ambience $Ally arrival 1: Plays when a friendly unit arrives while any Ambience track is playing
5 Allied Arrival during Battle $Ally arrival 2: Plays when a friendly unit arrives while any Battle track is playing
6 Enemy Arrival during Ambience $Enemy arrival 1: Plays when a friendly unit arrives while any Ambience track is playing
7 Enemy Arrival during Battle $Enemy arrival 2: Plays when a friendly unit arrives while any Battle track is playing
8 Battle 1 $Battle 1: Battle track 1—plays when units are in combat range; usually segues into Battle 2
9 Battle 2 $Battle 2: Battle track 2—plays when units are in combat range; usually segues into Battle 3
10 Battle 3 $Battle 3: Battle track 3—plays when units are in combat range; usually segues into Battle 1
11 Goal Failed $Failure 1: Plays when the primary goals of a mission are failed
12 Victory 1 $Victory 1: Plays when a goal is completed
13 Victory 2 $Victory 2: Plays when all goals are completed and there are absolutely no hostile units present; is only called once
14 Player Dies $Dead 1: Plays when the player is killed and goes to the death screen

Menu Music

All menu music tracks are defined in the lines within one instance of #Menu Music Start and #Menu Music End. Up to 50 menu music tracks can be defined across all .tbl and -mus.tbm files being referenced.

Each menu music track must have the following 2 lines in order:

  1. $Name:
  2. $Filename:

For the subsections, refer to the code used to call FS2_Brief_01.wav in-game, which is:

  $Name:		Brief1		
  $Filename:	FS2_Brief_01.wav			; briefing music 1

$Name:

The first line always starts with $Name:, followed by the name of the audio track, which is mainly referred to in FRED and its variants.

  $Name:		Brief1


FS2 Open 3.6.10:
  • The following flag can be added after $Name: in modular tables:

+nocreate

This flag should be added if the track is intended to completely overwrite an existing track with the exact same name.

$Filename:

The last line starts with $Filename:, followed by the file name of the audio track.

  $Filename:	FS2_Brief_01.wav			; briefing music 1

Format Sample

The following is a heavily truncated version of music.tbl located within Root_FS2.vp.

  ;
  ; music.tbl
  ;
  ; Specifies which .wav files to use for the different sections of event-driven sound-tracks
  ;
  ; format:  $Name:  filename.wav  num_measures (samples_per_measure)
  ;
  #SoundTrack Start	         				; SoundTrack 0
  $Soundtrack Name: 1: Genesis
  $Name:	FS2_Amb_A01.wav				25.0	105840	; * Ambience 
  $Name:	FS2_AArv_A01.wav			1.8	105840	; * Allied Arrival during Normal
  $Name:	FS2_Arv_B01.wav				3.8	81415	; * Enemy Arrival during Normal
  $Name:	FS2_Btl_A01.wav				25.8	66150	; * Battle 1
  $Name:	FS2_Btl_A02.wav				27.8	81415	; * Battle 2
  $Name:	FS2_Btl_A03.wav				39.8	81415	; * Battle 3
  $Name:	FS2_AArv_A01.wav			1.8	105840	; * Allied Arrival during Battle
  $Name:	FS2_Arv_B02.wav				3.8	81415	; * Enemy Arrival during Battle
  $Name:	FS2_Vict_A01.wav			2.8	52920	; * Victory 1 ( goal completed )
  $Name:	FS2_Vict_A02.wav			30.8	52920	; * Victory 2	( all enemies dead, goals completed )
  $Name:	FS2_Dth_A01.wav				23.8	132300	; * Goal Failed
  $Name:	FS2_Dth_A01.wav				23.8	132300	; * Player dies
  #SoundTrack End							; End Soundtrack 0
  ;
  #SoundTrack Start	     					; SoundTrack 1
  $Soundtrack Name: 2: Exodus
  $Name:	FS2_Amb_B01.wav				17.0	132300	; * Ambience 
  $Name:	FS2_AArv_A01.wav			1.8	105840	; * Allied Arrival during Normal
  $Name:	FS2_Arv_B01.wav				4.8	81415	; * Enemy Arrival during Normal
  $Name:	FS2_Btl_B01.wav				39.8	132300	; * Battle 1
  $Name:	FS2_Btl_B02.wav				23.8	75600	; * Battle 2
  $Name:	FS2_Btl_B03.wav				31.8	75600	; * Battle 3
  $Name:	FS2_AArv_A01.wav			1.8	105840	; * Allied Arrival during Battle
  $Name:	FS2_Arv_B04.wav				4.8	75600	; * Enemy Arrival during Battle
  $Name:	FS2_Vict_A01.wav			2.8	52920	; * Victory 1 ( goal completed )
  $Name:	FS2_Vict_B02.wav			40.8	88200	; * Victory 2	( all enemies dead, goals completed )
  $Name:	FS2_Dth_A01.wav				23.8	132300	; * Goal Failed
  $Name:	FS2_Dth_A01.wav				23.8	132300	; * Player dies
  #SoundTrack End							; End Soundtrack 1
  ;
  #Menu Music Start
  $Name:		Brief1				
  $Filename:	FS2_Brief_01.wav			; briefing music 1
  
  $Name:		Brief2
  $Filename:	FS2_Brief_02.wav			; briefing music 2
  
  $Name:		Brief3
  $Filename:	FS2_Brief_03.wav			; briefing music 3
  #Menu Music End

Related Links