Search public documentation:
Updated on 7/21/03 by Chris Linder (DemiurgeStudios?), to separate C++ Audio Subsystem code into its own doc.
Updated on 7/22/03 by Chris Linder (DemiurgeStudios?), for first public release.
Updated on 11/10/03 by Jan Svarovsky (KujuEntertainment?), for sound volume/radius clarification.
Updated on 2005-04-03 by Michiel Hendriks, v3323 update.
- Sound Reference
- Related Documents
- Importing Sounds in UnrealEd
- Script Sound Functions
> How can I play a stereo sound? You can't. If you really want to, have a programmer remove the code in ALAudioSubsystem that will disregard stereo sounds and make sure they are played with SF_No3D. The reason I removed support for stereo sounds is because they don't attenuate and artists tend to import stereo for sound effects which will then cause all sorts of issues. -- Daniel, Epic Games Inc.
native simulated final function PlaySound( sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch, optional bool Attenuate )PlaySound plays a sound attached to the location of the actor that calls PlaySound. The parameters to this function are described below.
|sound Sound||This is the sound to play. This must be a mono sound to be heard in 3D. If the sound is stereo, it will not play in 3D. Because the sound is not played in 3D, it will not attenuate with distance nor will there be any stereo separation based on the direction of the sound. The stereo sound will play at full volume when you are inside the SoundRadius and will not play at all outside the radius.||no default|
|optional ESoundSlot Slot||This is the slot in which to play the sound. There are 8 slots. The first slot, SLOT_None=0, represents no slot and any sounds played here will be played and mixed into whatever is playing already. In all the other slots (SLOT_Misc, SLOT_Pain, SLOT_Interact, SLOT_Ambient, SLOT_Talk, SLOT_Interface), only one sound can be played per actor. If a new sound is played in a slot that already has a sound playing and bNoOverride (described below) has not been set, the playing sound will be cut off and then new sound will be played. Note that slots work on a per actor basis; if there are many actors all playing sounds on the same slot, many sounds will be heard, just one sound per actor.||SLOT_Misc|
|optional float Volume||Volume is a scale from 0.0, which is silent, to 1.0, which is full volume. 0.5 is half volume (-6dB), 0.25 is quarter (-12dB) and so on. Sounds are played at full volume in the sound browser in Unrealed. You cannot make sounds louder, only softer. The Volume that is passed into PlaySound is scaled by one or two values. SoundVolume is a property of ALAudioSubsystem which is set in <your_game>.ini. All sound volumes are multiplied by this value which has a range between 0.0 and 1.0. The default value of SoundVolume is 1.0. When PlaySound is called from a Pawn, Volume is also multiplied by SoundDampening which is an attribute of Pawn. SoundDampening initially defaults to 1.0. The last thing that happens to Volume is that it is clamped between 0.0 and 1.0.||TransientSoundVolume|
|optional bool bNoOverride||This option is only useful for sounds that are played on a slot other than SLOT_None (see Slot above). If bNoOverride is set to true and another sound tries to play on this slot in this actor, it will not play. This will happen even if both calls to PlaySound have bNoOverride set to true. This prevents the sounds called with bNoOverride from being interrupted. By default this option is false and if another sound is played on the same slot by the same actor, the new sound will interrupt the old one. Note that slots work on a per actor basis; if there are many actors all playing sounds on the same slot, many sounds will be heard, just one sound per actor.||false|
|optional float Radius||Radius, in Unreal units, is the radius at which the sound begins to drop in volume. Between 0 and Radius, the sound is played at a constant volume of Volume. From then on outwards, the sound drops in volume by a scaled version of the way it works in the real world. At Radius times 100, the sound is completely cut off. In the real world, doubling the radius halves the volume. In Unreal the rate of falloff is affected by RollOff which is a global in the sound library. To be exact, equation is volume_drop_in_db = 20 * log10(1 + RollOff * (current_radius - Radius) / Radius). The transition at the edge of the outer radius (100 * Radius) is a little tricky. If you are inside the outer radius when PlaySound is called and move out of it, you will continue to hear the sound and it will continue to drop in volume. If you are outside the outer radius when the sound plays and move in, you will not hear the sound at all.||TransientSoundRadius|
|optional float Pitch||Pitch is clamped between 0.5 and 2.0. At 0.5 the sound is played at half the speed of the original sound, will take twice as long to play, and will sound one octave lower. At 2.0 the sound will be played at twice the speed, will take half as long to play, and will sound like it is one octave higher. This is ignoring Doppler shift which will additionally raise and lower the pitch of the sound.||1.0|
|optional bool Attenuate||This parameter should only be used by actors that are "owned" by the local player. "Owners" are determined by the SpawnOwner parameter of the Spawn function or the SetOwner function. Weapons in CodeDrop 2226 are "owned" by the local player for example. If Attenuate is true, which is its default, the sound will play in 3D originating at the location of the actor calling PlaySound. If Attenuate is false the sound will not play in 3D. Because the sound is not played in 3D, it will not attenuate with distance nor will there be any stereo separation based on the direction of the sound.||true|
native simulated final function PlayOwnedSound( sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch, optional bool Attenuate )The parameters of PlayOwnedSound are the same as PlaySound which you should refer to for a complete explanation. The only difference is that Attenuate defaults to false.
native simulated final function DemoPlaySound( sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch, optional bool Attenuate )DemoPlaySound is called from C++ by PlaySound and PlayOwnedSound when you doing Demo Recording. This function is called on the server and replicated to the client to play a sound. Presumably you would not want to call this function directly from either script or C++
native final function float GetSoundDuration( sound Sound )GetSoundDuration returns the length of the sound in seconds. This is the real world duration of the sound, thus is has not be "corrected" with the game speed. When sound duration is of importance for certain events, for example when a player has to wait for the sound to be finished, be sure to correct the duration with the gamespeed (
Level.TimeDilation). By default in the UnrealEngine2.5 10% faster than expected, with game speed set to 1 a real world second takes 1.1 seconds in game (see SetGameSpeed() in GameInfo, e.g. the requested speed is always multiplied with 1.1).
native final function int PlayMusic( string Song, float FadeInTime )Music in Unreal games in no longer handled with "tracked" songs. Instead, Ogg Vorbis ( http://www.vorbis.com/ ), a "completely open, patent-free, professional audio encoding and streaming technology", is used to encode sound files. OGG files are sort of like MP3s in that both are encoding standards that compress normal wav files. This function starts playing an OGG file as music for the game. Song is the name of the OGG file without the .OGG extention. OGG files are stored in the "Music" directory. So for example, if you had a song "MySong.ogg" in your Music directory, you would play it my calling:
PlayMusic("MySong", 2.0);. FadeInTime is the time it takes for the song to fade in to full volume which in the previous example is 2 seconds. This function returns the handle to the song which can be later used to stop the sound with StopMusic. If 0 is returned, PlayMusic failed. Unlike sounds, which are loaded then played, music is streamed. There are many advantages to streaming but one disadvantage is that only 8 streams can be played at the same time.
native final function StopMusic( int SongHandle, float FadeOutTime )StopMusic will stop the song with the given SongHandle. SongHandle is from the PlayMusic function. FadeOutTime is the time from when this function is called to when the song will be silent, unregistered, and stop using a music stream.
native final function StopAllMusic( float FadeOutTime )This will stop all songs played with PlayMusic. FadeOutTime is the time from when this function is called to when all the songs will be silent, unregistered, and all the music streams will be free.
native final function int PlayStream( string Song, optional bool UseMusicVolume, optional float Volume, optional float FadeInTime, optional float SeekTime );
|song|| The full path to the file to play back, this includes extention. For example |
|UseMusicVolume|| If true the ||true|
|InVolume|| The playback volume, only used if ||1|
|FadeInTime||Fade in duration.||0|
|SeekTime||Offset to start playing from, in seconds||0|
native final function StopStream( int Handle, optional float FadeOutTime );Stops the stream with the given handle.
FadeOutTimeis time to fade out the music, if set to 0 the music stops instantly.
native final function int SeekStream( int Handle, float Seconds );Sets the current playback position of the song identified by
native final function bool AdjustVolume( int Handle, float NewVolume )Change the playback volume of the given stream.
native final function bool PauseStream( int Handle )Toggles playback of the given stream.
var(Sound) float TransientSoundVolumeThis is the default sound volume for sounds played with PlaySound or PlayOwnedSound. This volume can be overridden in both these functions.
var(Sound) float TransientSoundRadiusThis is the default sound radius for sounds played with PlaySound or PlayOwnedSound. This radius can be overridden in both these functions.
var(Sound) ESoundOcclusion SoundOcclusionThis is how sounds played with PlaySound or PlayOwnedSound as well as Ambient Sounds for this actor will be occluded. This setting applies to all sound playing for this actor. You cannot, for example, have an ambient sound occluded in one manner and have sounds played with PlaySound occluded in another. There are four settings for this variable explained in the chart below:
|OCCLUSION_Default||This is the default. It behaves like OCCLUSION_BSP described below.|
|OCCLUSION_None||Sounds will not be occluded at all.|
|OCCLUSION_BSP||Sounds will be occluded by BSP but not by blocking volumes. (does a FastLineCheck from the location of the sound to the listener.)|
|OCCLUSION_StaticMeshes||Sounds will be occluded by static meshes and BSP but not by blocking volumes. (does a SingleLineCheck from the location of the sound to the listener.)|
var(Sound) sound AmbientSoundThis is the ambient looping sound effect of this actor. AmbientSound can be set on any Actor; it does not need to be a class AmbientSound. The sound must be mono to be heard in 3D. If the sound is stereo it will not play in 3D. Because the sound is not played in 3D, it will not attenuate with distance nor will there be any stereo separation based on the direction of the sound. The stereo sound will play at full volume when you are inside the SoundRadius and will not play at all outside the radius.
var(Sound) float SoundRadiusThis is the radius of the ambient sound. Like PlaySound, the radius is 1/100 of the radius of the sound in Unreal Units. The transition at the edge of the radius is handled differently from PlaySound however. The transition at the edge of the radius is not perfectly smooth. Once you step inside the sound radius you will suddenly be able to hear it though it will be faint. If you step outside the radius the sound will suddenly be cutoff. The cutoff will be faint but there is still a sharp discernible transition if you look for it.
var(Sound) byte SoundVolumeSoundVolume is a scale from 0, which is silent, to 255, which is the volume the sound plays at the sound browser in Unrealed. You cannot make sounds louder, only softer. It is possibly to enter a value greater than 255, but it will only loop the volume values so that a setting of 256=0, 257=1, and so on... If bFullVolume is set to false (which is its default), SoundVolume is scaled by AmbientVolume which is a 0.0 to 1.0 multiplier for all ambient sounds. AmbientVolume is defined in <your_game>.ini.
var(Sound) byte SoundPitchSoundPitch is a scale clamped between 32 to 128. 64 is the default value which means the sound will play at the normal pitch/speed. At 32 the sound is played at half the speed of the original sound, will take twice as long to play, and will sound one octave lower. At 128 the sound will be played at twice the speed, will take half as long to play, and will sound like it is one octave higher. This is ignoring Doppler shift which will additionally raise and lower the pitch of the sound.
var(Sound) bool bFullVolumeIf this is set to true, the ambient sound of this actor will ignore the AmbientVolume settings in <your_game>.ini. See SoundVolume above for more details about volume.