===== Overview =====
**<Soundtrack>** defines music tracks to play during the game, as well as tracks specific to missions and intro/ending tracks.

===== Soundtrack Life Cycle =====

The engine selects which track to play based on a priority system when a player enters a system.

Mission tracks are given priority over everything else until they finish or are stopped.

When a new system is entered, all soundtracks are entered into a probability table (if the player has entered the system previously then the old table is kept). Any tracks without attributes matching the system are discarded. If a given system track has already been played, it is skipped. Probability is then calculated based on locationCriteria, and tracks that have been played recently are put at the back of the queue. The engine then works down the list of matching tracks for the system.



===== Usage =====

	<Soundtrack UNID="..."
			filename=			"..."
			title=				"..."
			composedBy=			"..."
			performedBy=			"..."
			priority=			"..."
			locationCriteria=		"..."
			attributes=			"..."
			>
  <Segments>
    <Segment startPos="..."				endPos="..."/>
   </Segments>
   </Soundtrack>
   
===== Attributes =====  
   
**filename=** is the path to the file. Note that for packaging to .tdb the files must be in the same directory as the xml.

**title=** The title of the track. Shows up on the intro screen when the track is playing.

**composedBy=** The composer. Shows up on the intro screen when the track is playing.

**performedBy=** The performer, in case its different from the composer. Shows up on the intro screen when the track is playing.

**priority=** Gives the soundtrack priority over tracks with lower values. This is useful if there's a lot of system attributes that match soundtracks and you want to give priority to one. A good example is how //Eternity Port//'s soundtrack is configured.

**locationCriteria=** This field dictates which systems the track can play in. All of the //Stars of the Pilgrim Soundtrack// tracks have "humanSpace" in their locationCriteria, allowing only nodes with the "humanSpace" attribute to play it.

**attributes=** The attributes that the engine looks for are travelSoundtrack, combatSoundtrack, missionSoundtrack, systemSoundtrack, and specialSoundtrack. Travel and combat soundtracks are self-explanatory - they're selected by the engine depending on whether the player is in or out of combat.

//systemSoundtrack// describes a track meant for a specific system or set of systems. The engine will look at the locationCriteria field and play the track only if the star system the player is in matches the criteria. For example, the track //Jiang// in the //Stars of the Pilgrim Soundtrack// plays only in systems with the "ungoverned" attribute. This criterion should be accompanied by either travelSoundtrack or combatSoundtrack.

//missionSoundtrack// attribute means the soundtrack must be called by UI functions, and the soundtrack manager will not interrupt the track to transition between travel and combat tracks.

//specialSoundtrack// keeps the track out of the soundtrack manager, so it is not played randomly. Added in API 34.

//victorySoundtrack// is an attribute that appears on Battle Arena victory tracks. It doesn't have any engine effect; it's just an attribute.

**Segments** These chop the track up into pieces so the engine knows when a good place to start/stop is for transitioning between tracks. A value of 1000 here is equal to 1 second.

[[modding:function:ui_functions|UI and Soundtrack functions]]

[[modding:reference|Return to Modding Reference]]