Difference between revisions of "Playing custom background music"
imported>Jaime74 (Moved from category "Useful Code" to "Tutorials") |
imported>Syscrusher m (→Better Music System (BMS): Spelling correction) |
||
(7 intermediate revisions by 2 users not shown) | |||
Line 8: | Line 8: | ||
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: | 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: | ||
*[[:Category:SoundCommands|Sound Commands]] (short: SC) by Scanti | *[[:Category:SoundCommands|Sound Commands]] (short: SC) by Scanti | ||
*[http://www. | *[http://www.nexusmods.com/oblivion/mods/19772/ Enhanced Music and Control] (short: EMC) by HawkleyFox | ||
*[http://www. | *[http://www.nexusmods.com/oblivion/mods/26892/ 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). | 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). | ||
Line 18: | Line 18: | ||
===StreamMusic=== | ===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. | 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 | 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. | will randomly pick one track from within the ''YourPlaylist'' subfolder (which we can consider a "playlist") and immediately start streaming it. | ||
Line 36: | Line 36: | ||
===Enhanced Music and Controls (EMC)=== | ===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. | 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 | 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! | Note that EMC commands overrule any attempt to play music ''either'' via SoundCommands ''or'' via StreamMusic! | ||
Line 46: | Line 46: | ||
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! | 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, | 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! | 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- | 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|Defining cell-specific playlists for Better Music System]]. | A description how this can be done is given in this separate tutorial: [[Defining cell-specific playlists for Better Music System|Defining cell-specific playlists for Better Music System]]. | ||
Line 58: | Line 58: | ||
* that these methods interfere with each other, one taking precedence over others | * 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 | 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. | The code below shows an example of how to do this. | ||
Line 67: | Line 67: | ||
#Your mod defines a cell called ''YourCell'', in which your custom music should automatically be played on entering | #Your mod defines a cell called ''YourCell'', in which your custom music should automatically be played on entering | ||
#All music tracks for this cell-specific playlist are located under ''Data\Music\YourPlaylist'' | #All music tracks for this cell-specific playlist are located under ''Data\Music\YourPlaylist'' | ||
#There's only 1 track to be | #There's only 1 track to be played (''YourTrack.mp3'') | ||
This script is still quite | This script is still quite complex, and it already covers some very special situations. A more detailed explanation will follow... | ||
ScriptName YourModQuestScript | ScriptName YourModQuestScript | ||
Line 156: | Line 156: | ||
endif | endif | ||
end ; end of gameMode block | end ; end of gameMode block | ||
==See also== | ==See also== | ||
*[[StreamMusic]] | *[[StreamMusic]] |
Latest revision as of 21:28, 14 May 2014
Tools used in this tutorial
Required |
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?[edit | edit source]
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[edit | edit source]
StreamMusic[edit | edit source]
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)[edit | edit source]
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)[edit | edit source]
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)[edit | edit source]
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[edit | edit source]
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:
- 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
- Your mod defines a cell called YourCell, in which your custom music should automatically be played on entering
- All music tracks for this cell-specific playlist are located under Data\Music\YourPlaylist
- 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[edit | edit source]
- 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