Playing custom background music

This article provides a simple tutorial about how to stream custom audio tracks as background music in specific cells of your own mod. It puts special focus on compatibility with more popular music overhauls like Sound Commands, Enhanced Music and Control and BetterMusicSystem. The sample code included in this article is based on a tested and working solution.

Why this article?

The vanilla method for playing custom background music is to use the StreamMusic function. There are already excellent tutorials about using StreamMusic, such as Creating a Music Playlist. This is why StreamMusic is not described in more details here.

This article deals with the issue that arises whenever users have either of the following music extensions installed, because they overrule StreamMusic and thus make its usage unreliable:

• Sound Commands (short: SC) by Scanti
• Enhanced Music and Control (short: EMC) by HawkleyFox
• Better Music System (short: BMS) by side777

This tutorial summarizes briefly, in the first part, how to play custom tracks with each of these three extensions. This doesn't go deep into the details, because all of this is already documented in other articles (links included). The second part describes how to detect if users of your mod have one or more of these extensions installed, and how to use the most appropriate code for playing your custom music. In the end, you should know how to integrate your custom music into your mod's own cells without bothering about the game setup of the users.

Part 1: Different methods of streaming background music

StreamMusic

StreamMusic is Oblivion's vanilla function for playing custom background music. It is known to have a lot of limitations, but it's still the only way to stream music on all user systems that don't use OBSE and don't have any of the other extensions installed. If you don't want to force users of your mods to install one of those extensions, you should always enable your mods to play music with this vanilla function, if necessary. Using StreamMusic is quite simple, e.g.

StreamMusic "Data\Music\YourPlaylist\*.*"

will randomly pick one track from within the YourPlaylist subfolder (which we can consider a "playlist") and immediately start streaming it.

Please read the original StreamMusic article to learn more.

SoundCommands (SC)

SoundCommands is a plugin for OBSE that provides some more comfortable sound functions. Apart from its various possibilities to change music volume, fading etc., it also adds a more reliable command (PlayMusicFile) to start custom tracks. The usage is quite similar to StreamMusic:

PlayMusicFile "Data\Music\YourPlaylist\*.*"

This will do roughly the same as the StreamMusic sample above, only in a more reliable way. However, this method forces users to have both OBSE and SoundCommands installed.

Note that SC commands overrule any attempt to play music via StreamMusic!

Please read the original Sound Commands article to learn more.

Enhanced Music and Controls (EMC)

This is another plugin for OBSE, which comes with an even more comfortable set of sound functions. It goes beyond SoundCommands' possibilities by providing methods to define and play playlists with script functions. As Better Music System (see below) is based on the older EMC, most users will problably have it installed simply because they use BMS. I.e. EMC is always present implicitly when someone uses BMS.

Note that EMC commands overrule any attempt to play music either via SoundCommands or via StreamMusic!

Read the Enhanced Music and Control (on TESNexus) to learn more.

Better Music System (BMS)

This complete music overhaul is based on EMC (as mentioned above). While it uses core EMC functions to play music, it seems to take precedence over any attempt to play music with EMC code from within other mods!

This means, implicitly, that it blocks all of the other methods listed above!

In other words: If you want to start custom background music tracks by simply writing StreamMusic, SC or EMC code, this won't work whenever the user uses BMS!

Instead, you need to define a BMS-compatible playlist and integrate it into your mod. A description how this can be done is given in this separate tutorial: Defining cell-specific playlists for Better Music System.

Part 2: Automatically detecting the most appropriate method

The brief descriptions above demonstrate that

• there are at least four common methods of streaming background music
• that these methods interfere with each other, one taking precedence over others

Hence, if you are developing a mod that should play specific music (e.g. inside a specific cell), you cannot rely on the one or the other method without forcing the users to either install or uninstall certain music extensions! This would have big impact on the acceptance of your mod, so you need to write some more script code to detect which plugins are installed in the user's environment, and then use the most appropriate method to play your music.

The code below shows an example of how to do this.

Note that this code is based on the following preconditions:

1. You have created a custom playlist for BMS containing your cell music, as described here (same links as above). This playlist is defined in a separate esp, which also contains a quest called BMSYourMod
2. Your mod defines a cell called YourCell, in which your custom music should automatically be played on entering
3. All music tracks for this cell-specific playlist are located under Data\Music\YourPlaylist
4. There's only 1 track to be played (YourTrack.mp3)

This script is still quite complex, and it already covers some very special situations. A more detailed explanation will follow...

ScriptName YourModQuestScript

short cellMusicStarted
short emcSuccessful
short currentMusicType
short streamMusicTimer

begin gameMode
if player.getInCell YourCell == 1 
 if questExists "BMSYourMod" == 1
   ; --
   ; -- This is the part for Better Music System (BMS)
   ; --
   if cellMusicStarted == 0
     printToConsole "Starting cell music via BetterMusicSystem."
     set cellMusicStarted to 1
     ; no additional code required here, we can rely on BetterMusicSystem to do everything
   endif
   else 
     if cellSoundStarted == 0
       if isPluginInstalled "Enhanced_Music_Control" == 1
       ; --
       ; -- This is the part for Enhanced Music Controls (EMC)
       ; --
		printToConsole "Starting music via EnhancedMusicControl..."
       set emcSuccessful to 1
       if (emcPlaylistExists "YourPlaylist") == 0
         let emcSuccessful := emcCreatePlaylist "YourPlaylist" "Data\Music\YourPlaylist\*.*"
       endif
       if emcSuccessful == 0
         printToConsole "EnhancedMusicControl FAILED: Couldn't create playlist YourPlaylist!"
       else
         if emcIsMusicSwitching == 1
           printToConsole "EnhancedMusicControl is currently switching sound..."
             return 
         else
           set currentMusicType to emcGetDesiredMusicType
           printToConsole "Changing playlist for current MusicType %g..." currentMusicType
           let emcSuccessful := emcChangePlaylist currentMusicType "YourPlaylist"
           if emcSuccessful == 0
             printToConsole "EnhancedMusicControl FAILED: Couldn't change playlist!"
           else
             set cellMusicStarted to 1
             PrintToConsole "Starting of music track with EnhancedMusicControl complete."
           endif
         endif
       endif
     endif
     if isPluginInstalled "Enhanced_Music_Control" == 0 || emcSuccessful == 0
       if isPluginInstalled "SoundCommands" == 1
         ; --
         ; -- This is the part for SoundCommands (EMC)
         ; --
         printToConsole "Starting music via SoundCommands..."
         playMusicFile "Data\Music\YourPlaylist\YourTrack.mp3"
         set cellMusicStarted to 1
         printToConsole "Starting of music track with SoundCommands complete."
       else
         ; --
         ; -- This is the part for the vanilla StreamMusic method
         ; --
         printToConsole "Starting music via vanilla StreamMusic command..."
         set streamMusicTimer to 180 ; i.e. the length ofYourTrack.mp3 in seconds
         streamMusic "Data\Music\YourPlaylist\YourTrack.mp3"
         set cellMusicStarted to 1
           printToConsole "Starting music with StreamMusic complete"
         endif
       endif
     endif
     if (isPluginInstalled "Enhanced_Music_Control" == 0 || emcSuccessful == 0) && isPluginInstalled "SoundCommands" == 0  
       if streamMusicTimer > 0
         let streamMusicTimer -= getSecondsPassed
         printToConsole "streamMusicTimer=%g" streamMusicTimer
       else
         set cellMusicStarted to 0
       endif
     endif
   endif
 elseif cellMusicStarted > 0
   ; --
   ; -- if player has already been inside the cell, and the music was started, but now he's outside again
   ; --
   set cellMusicStarted to 0
 endif
end ; end of gameMode block

See also

• StreamMusic
• Creating a Music Playlist (describes usage of StreamMusic in more details)
• Sound Commands
• Enhanced Music and Control (on TESNexus)
• Better Music System (on TESNexus)
• Defining cell-specific playlists for Better Music System