Sound Commands

OBSE plug-in SoundCommands v4.0

What is it?

The aim of this plug-in is to add various commands that allow you to control the sound system in Oblivion. This is a modders resource and you are free to include this plug-in with your code. You need OBSE for this plug-in to work. You can download OBSE from:

http://obse.silverlock.org/

This plug-in only supports Oblivion version 1.2.0.416. If you use it with an earlier version it won't cause any errors, the commands will just get ignored.

How do I use it?

The new commands are as follows:

SetMasterVolume

Sets the global master volume. This setting effects all the volumes.

SetMusicVolume

This sets the volume of the background music in the game.

The volume mode parameter allows you to alter the behavior of the volume command. It has 3 settings:

0 - Immediately change the music's volume but when the track changes go back to the original volume before the command was issued.

1 - Immediately change the music volume and make it stick.(This is a combination of settings 0 and 2). This is the default setting.

2 - Change the music volume when the current track ends and a new one plays.

SetEffectsVolume

Sets the effects volume.

SetFootVolume

Set the volume of your footsteps.

SetVoiceVolume

Sets how loudly people talk.

FadeMusic

NB: This command is experimental. Please let me know if it causes any problems.

This fades the music volume from the starting volume to the end volume, taking the specified amount of time to complete. While the music is fading the SetMusicVolume command won't do anything.

GetMusicVolume

This command returns the current volume of the music. As there are several ways of setting the music volume there are several ways of reading it. It will return -1 if you are using an unsupported version of oblivion (except for volume type 0) or if the FadeMusic command is currently fading the music (as the volume will be constantly changing).

The volume type parameter has 3 settings:

0 - This returns the value stored in the fDefaultMusicVolume Oblivion.INI setting. This is the volume the player wants their music to play at.

1 - This returns the volume level that is currently stored by the sound system. It may not actually be the current music volume. It's changed by SetMusicVolume methods 1 and 2. (This is the default setting).

2 - This is the music volume of the track currently being played. The volume may change once the track finishes and a new one plays. This is changed by SetMusicVolume methods 0 and 1.

PlayMusicFile

This command will immediately play the music file pointed to by the filename. If the filename contains a wildcard character the command will load a random music file matching the wildcarded filename. i.e. PlayMusicFile "data\music\mymusic\*.mp3" will play a random mp3 file in the data\music\mymusic folder.

The music will get overidden according to the rules that the Oblivion engine uses. i.e. if you change a cell and the music type for that cell is different from the type that's playing or if you enter or exit combat.

GetEffectsVolume
GetFootVolume
GetVoiceVolume
GetMasterVolume

These commands allow you to find out the volume that different categories of sounds are playing at. It has one optional parameter.

If it is set to 0 then the command will get the INI setting for that volume type. This will be the volume that the user wishes the volume to be at.

If it set to 1 (which is the default value) it will get the current volume level for that volume type.


The volume parameter for all the commands is in the range of 0 (for silent) to 1 (for full volume). If you try to set the volume outside this range, the volume will get clamped to within the range. The volume setting seems to be logarithmic and not linear.

Usage requirements.

You can do whatever you like with this plug-in. Just include it in with your mod if you do use the command.

Change log.

v 4.0

Added GetEffectsVolume, GetFootVolume, GetVoiceVolume, GetMasterVolume commands.

v 3.0

Added PlayMusicFile command.

v 2.0

Added new GetMusicVolume command.

Patched the oblivion exe so that it doesn't write back any volume settings changed within a script to your Oblivion.ini file. Settings changed in the audio menu will still update the INI file.

Added some housekeeping to the FadeMusic command for when you quit the game.

The source code now uses structures instead of complicated pointers to pointers to pointers.

v 1.0

First release.