Spectral Music Player

by Selene310187 aka darklady310187



Version: 1.6

bug fix release + optional special music tweak plugins
(see changelog)


**********************************************************


Important:
##########

Updating from version 1.5 to 1.6:
-----------------------------------
Replace the old .esp and .bsa files with the new ones. Once you have loaded your savegame, talk to the drum and exit the menu
of the Spectral Music Player afterwards. This initiates a fix that reduces the risk that other followers turn hostile towards the drum due
to friendly fire in combat (see changelog for more information).


Updating from previous versions to 1.5:
-----------------------------------------

Start the game and load your current savegame. Stop the current playback of the playlists. Dismiss the drum by commanding it to
vanish. Save your game in a new savegame slot. Exit the game. Make a back-up of this savegame in case something goes wrong.

In the next step, we need to delete all traces of the plugin from your savegame with ReSaver (part of FallrimTools) - this process is
called savegame cleaning. It makes sure that the bug fixes for the Anniversary Edition (since version 1.4) take effect and the new
combat music setting "No Combat Music" (since version 1.5) is available in your savegame (see changelog).

Download and install FallrimTools: https://www.nexusmods.com/skyrimspecialedition/mods/5031
Start ReSaver. Open the savegame that you created before in ReSaver. Expand "Plugins (ESP & ESM)". Right-click on the entry
"Spectral Music Player.esp" and choose "Delete plugin changeforms". Right-click on this entry again and choose
"Delete plugin script instances" this time. Save the savegame under a new name so you can find the edited savegame faster when
you want to load your savegame in the game.

Replace the old .bsa and .esp files with the new ones.

The final step is about adding the drum summoning spell back to your character because the game sees the plugin as a newly added mod
after the savegame cleaning. Start the game and load the edited savegame.
Open the console and type in this command: startquest BB03AddTomeDrum
Confirm with Return or Enter key. The console command starts a quest which adds the spell tome to your inventory without a
notification. Open your inventory and use the tome "Spell Tome: Bardic Knowledge - Advanced Music" which adds the summoning spell to
your character. Stop the quest using this console command: stopquest BB03AddTomeDrum
Save your game.


*************************************



How to use the Spectral Music Player



Step 1: Add the music
======================

Put the Music folder, the Spectral Music Player.bsa and the Spectral Music Player.esp from the archive into your Data folder.

Download a music package of your choice from Skyrim NexusMods.

Alternatively, you can convert any .mp3 (or similar audio file) to .xwm (or .wav) with a converter tool like
Yakitori Audio Converter: https://www.nexusmods.com/skyrimspecialedition/mods/17765

Put up to 50 songs into each CustomSongs... subfolder under Data\Music\BetterUntoldLegendsRewards

If you experience problems with .wav sound files convert them to .xwm

Please make sure that Windows doesn't hide the file extensions.

Rename the files accordingly:


Track001.xwm
...
Track050.xwm


or


Track001.wav
...
Track050.wav


You can use a tool to make the renaming process easier like Advanced Renamer: https://www.advancedrenamer.com
- click on "Add method" > New Name
- Type: Track0
- click on ...
- drag the songs you want to rename into the window of the program
- click on "Start batch" and on "Start"


Step 2: Activate the Spectral Music Player.esp
==============================================
Activating the esp is possible e.g. in the main menu of the game (Start game -> Mods -> Load order -> check the box). Alternatively, you can
use Vortex (beginner-friendly) and Wrye Bash (has some nice gimmicks like creating savegame profiles). Both tools are available at Nexusmods.com.


Step 3: Access the Spectral Music Player menu
==============================================

You can access the music player by summoning the Spectral Drum via the "Bardic Knowledge - Advanced Music" summoning spell and talking
to the Drum afterwards. The spell can be crafted at the Tanning Rack if you have at least one of the rewards from the Untold Legends quest.


Step 4: Adjust the track limits
================================
Go to the ingame Music Player menu of the Spectral Drum and navigate to Settings > Track Limits. Set the track limit of each category
according to the number of tracks inside the corresponding subfolder.

Available custom song categories:
Town, Tavern, Home, Combat, Explore and Dungeon


Step 5: Choose a mode
=====================
Skip Mode:
This is the default mode. The next song is played after X seconds (the amount of seconds can be set in the Settings menu). You can
control which song is played next via the playlist controls like "Next", "Previous" or "Random".

Cycle Mode:
Songs are always played in random order and in full length. Due to the random nature of this mode, the playlist controls are
limited to "Play", "Pause" and "Stop".



Step 6: Choose the combat music type which is played during combat (Settings > Combat Music)
==================================================================
The default combat music type is Skyrim's default combat music ("Default"). The other combat music types are "Drumming"
(the default drumming sounds of the Spectral Drum) and "Custom" (if you want to play the tracks from the CustomSongsCombat folder
during combat).


Step 7: Select a playlist and enjoy!
====================================
When you have selected a playlist confirm your selection with Play. It will be assigned to the Current Playlist section in the main menu of
the Spectral Music Player. Click on Stop to remove a playlist from this section. Pause will pause the current playback (and play a
silence track instead) but will not remove the playlist from Current Playlist.





Disclaimer:
============
The mod is open-source in a non-commercial use*. Feel free to do what you want with it as long as you mention my name (Selene310187)
in your credits.
* only exception: I allow Donation Points on Nexus Mods

Here are some ideas for possible projects: You could use the mod as a framework for a music package. Or build music boxes for your home mod
(the relevant scripts which you can use as base have the word "music" in their name).


Changelog:
==========

Version Beta 1:
---------------
Initial release


Version Beta 1.1:
----------------
If you summon the drum with its default summon spell and then use the advanced music version, the background drumming sounds will be removed so
that they will not interfere the playback of your chosen playlist.

There's a now an alternative way* to get the spell for the ones who don't want to do the Untold Legends quest. Just type the following into the
console: startquest BB03AddTomeDrum
Confirm with Return or Enter key. The console command starts a quest which adds the book to your inventory without a notification. After the book
is added, you can stop the quest with this command: stopquest BB03AddTomeDrum


* If you are interested in the technical details: The spell tome is added via Quest Aliases (the Reference Alias ones).
The first Reference Alias is for the player (use "Specific Reference" and "Select Forced Ref") and the second one for the spell tome which
has "Create Reference to Object" as Fill Type, "Create" is set to "In", pointing to the player Alias. Important: The quest should have the
"Run Once" flag checked so the spell tome is only added once.
More information on Quest Aliases: https://www.creationkit.com/index.php?title=Quest_Aliases




Version 1.0:
------------
Auto-Remove Vanilla Music option works for all playlists now instead of only one

When the Default combat music type is selected again, it will turn off the options "Include Dragons", "Include Boss" and "No Weak"
automatically (as they only work with the "Drumming" and "Custom" combat music type)

shortened the text of the "Remove Default Music" menu because some portion of the text was cut off ingame

the notification 'Please select another combat music type than "Default".' now appears as message in the upper left corner of the screen instead
of a message box

cleaned the esp up by removing redundant entries from it


Version 1.1:
------------
added optional playback continuation after you commanded the drum to vanish (disabled at default; Page 2 in the Settings menu)

you can access the music player menu via equipping the misc item "Spectral Drum - Remote Control" even when the drum is not
there (disabled at default; Page 2 in the Settings menu)


Version 1.2:
-------------
When the Default combat music type is active, the non-combat music from the cycle mode playlists will play again after you have
finished combat

the Default combat music will terminate faster (this should also fix the stuck combat music bug of the Vanilla game)

after you have reloaded a savegame, the playback from the cycle mode playlists including the custom or drumming
combat music will continue (it takes a few seconds until the custom music kicks in again)

The default music auto-removal feature after loading a savegame is also fixed. The fix will only take effect, if you toggle the
feature off in the settings and on afterwards

plugin description: added the missing console command for stopping the quest which adds the tome

correction of the ingame description - advanced combat buffs: It said that these buffs also increase health but this was cut
during the development

correction of the ingame description - remote control: it said mistakenly that you can hotkey the remote control. But I noticed
during testing the new version that you can't hotkey normal misc items

correction of the ingame description - Auto-Remove Vanilla Music: the feature kicks in after clicking on the Play button AND
closing the main menu of the music player


Version 1.3
------------
When you told the drum to vanish and do fast-traveling, the drum will not appear again. Now it will only appear
again when you summon it.


Version 1.4
-----------
Bug fixes for the Anniversary Edition of Skyrim:
fixed the automatic song switching when the music player is in SkipMode
fixed mode switching: switching from Cycle Mode back to SkipMode works now


If you have played a previous version of the mod before, the fixes will only take effect after you have cleaned your savegame
with ReSaver, see section "Updating from previous versions to 1.6".



Version 1.5
-----------

I added the "No Combat Music" as additional combat music setting (disabled at default). If this setting is enabled, the custom music
won't get interrupted by any combat music. The setting can be found in the menu of the Spectral Music Player under Settings >
Combat Music.

If you swim in the water, the drum will swim, too.


If you have played a previous version of the mod before, the "No Combat Music" combat music setting is only available after you have
cleaned your savegame with ReSaver, see section "Updating from previous versions to 1.6".


Version 1.6
-----------

Bug fixes:
**********
After reloading the savegame and the playback of the playlists is active, you will be able to stop the playback of the
current playlist now.

When the "No Combat Music" combat music setting is active and you finish combat, you will be able to stop the playback of the current
playlist as well.

Hitting the stop button of the dungeon playlist, truly stops its playback.

The risk that other followers turn hostile towards the drum due to friendly fire in combat is reduced. Please talk to the drum and exit the
menu of the Spectral Music Player to initiate this bug fix. If you experience that your other followers are attacking the drum nevertheless,
you can stop the fight by commanding the drum to vanish. After that you can summon the drum again if you wish. Regarding friendly fire
due to magic attacks, Amazing Follower Tweaks (https://www.nexusmods.com/skyrimspecialedition/mods/6656) has an optional add-on that
"completely prevents magic based friendly fire between teammates". The file is called "AFT_NoFriendlySpellDamage" and can be found in the
Optional Files section of AFT. You don't need to install AFT to use the add-on; it's stand-alone.

Bonus tip: If your other followers are fighting each other (and not the drum), fighting can be stopped with the resetai console command.
Open the console, click on one follower, type resetai and confirm with return or enter keys, leave the console open, click on the
other follower and repeat the resetai console command, close the console.


Additions:
**********
Two optional special music tweak plugins.

Variant A gives the default special music of the game (e.g. level-up or discovery of a new location music) a higher priority than the custom music
of Spectral Music Player. So the special music will always play when the situation requires it.

The B variant gets rid of the special music entirely so that you don't hear the special music tracks after the playback of the music player is
stopped.

Please activate either the A or the B variant of the Special Music Tweak and load your chosen tweak after "Spectral Music Player.esp".

Edited default music types (only the optional plugins edit these music types):
MUSDiscoveryCity
MUSDiscoveryDungeon
MUSDiscoveryGeneric
MUSDiscoveryHighHrothgar
MUSDiscoveryTown
MUSDread
MUSDungeonCleared
MUSReveal
MUSReward
MUSSpecialDeath
MUSSpecialSuccess
MUSStinger



Credits:
========

Thanks to Dylbill for the "Message Menu Tutorial SSE", especially the video version:
https://www.nexusmods.com/skyrimspecialedition/mods/46410
https://youtu.be/BbIvY-Jer0g
https://youtu.be/RIej0my5q3w





Bugs/limitations:
=================

Special music like level-up music or discover of new location music only plays when the playback of the music player is stopped:
In the previous version, all custom music types had a priority of 1. This conflicted with the special music type which also has a priority
of 1. In one situation you heard the special music and in the other, when you should hear the special music, you heard the custom music
instead. For the sake of consistency, I decided that the custom music wins the battle (i.e. it got a higher priority which is surprisingly 0).

If you prefer that the special music should have a higher priority, activate "Spectral Music Player - Special Music Tweak - A.esp".

If you don't want to hear any special music after the playback of the music player is stopped, activate
"Spectral Music Player - Special Music Tweak - B.esp" instead.


The drum stops following although it was commanded to follow:
If this issue happens, command the drum to vanish and summon it again.


No playback in some cells:
If a cell has no music assigned, you won't hear the music from the playlists in this cell

Hearing default music and the custom music simultaneously:
During the development, I noticed that the engine had sometimes problems with pausing the default music when the music from the playlist is playing so that you
hear both simultaneously. That's why I built the "Auto-Remove Vanilla Music" feature in to mitigate the issue. As long as this feature is active, clicking on the
Play button of a playlist and closing the menu of the music player afterwards will remove the default music temporarily. The feature can be deactivated anytime
in the Settings menu. Alternatively, you can remove the default music manually using the "Remove Default Music" option in the main menu of the music
player (this removal is temporary as well).



Playback delay:
When you enter/finish combat with the default combat music type being active or reload a savegame, it takes a few seconds until the custom music kicks in. The reason
for the delay at the beginning of the combat is probably the target searching function which determines what type of combat music should play for the current opponent.
Or it has something to do with the priority of the custom/drumming combat music which is equal to the default combat music (I can't set it higher because it may conflict
with the special combat music of the game). The delayed playback of the music from the playlists are reloading a savegame is due to the music cleanup script (see second
annotation in the "Updating from previous versions to 1.2" section)