SoundService

Show Deprecated
Not Creatable
Service

A service that determines various aspects of how Sounds play in the game. SoundService is also often used to store SoundGroups although this is not mandatory for SoundGroups to work.

What can SoundService do?

SoundService properties such as SoundService.AmbientReverb, SoundService.DistanceFactor, SoundService.DopplerScale and SoundService.RolloffScale can be used to change how all Sounds play in the game.

The SoundService:SetListener() function allows developers to set the position where sounds are heard from.

SoundService:PlayLocalSound() can be used to play a sound locally regardless of where it is parented to.

Developers looking to find out more about how sound works in Roblox should consult the documentation provided for the FMOD sound engine.

Code Samples

Play Local Sound

1local ServerScriptService = game:GetService("ServerScriptService")
2local SoundService = game:GetService("SoundService")
3
4-- Create custom plugin button
5local toolbar = plugin:CreateToolbar("Empty Script Adder")
6local newScriptButton = toolbar:CreateButton("Add Script", "Create an empty Script", "rbxassetid://1507949215")
7
8local function playLocalSound(soundId)
9 local sound = Instance.new("Sound")
10 sound.SoundId = soundId
11 SoundService:PlayLocalSound(sound)
12 sound.Ended:Wait()
13 sound:Destroy()
14end
15
16local function onNewScriptButtonClicked()
17 -- Create new empty script
18 local newScript = Instance.new("Script")
19 newScript.Source = ""
20 newScript.Parent = ServerScriptService
21 playLocalSound("rbxassetid://0") -- Insert audio asset ID here
22end
23
24newScriptButton.Click:Connect(onNewScriptButtonClicked)
Dynamic Reverb System

1local Players = game:GetService("Players")
2local CollectionService = game:GetService("CollectionService")
3local SoundService = game:GetService("SoundService")
4
5local localPlayer = Players.LocalPlayer
6
7local reverbTags = {
8 ["reverb_Cave"] = Enum.ReverbType.Cave,
9}
10
11-- collect parts and group them by tag
12local parts = {}
13for reverbTag, reverbType in pairs(reverbTags) do
14 for _, part in pairs(CollectionService:GetTagged(reverbTag)) do
15 parts[part] = reverbType
16 end
17end
18
19-- function to check if a position is within a part's extents
20local function positionInPart(part, position)
21 local extents = part.Size / 2
22 local offset = part.CFrame:PointToObjectSpace(position)
23 return offset.x < extents.x and offset.y < extents.y and offset.z < extents.z
24end
25
26local reverbType = SoundService.AmbientReverb
27
28while true do
29 task.wait()
30 if not localPlayer then
31 return
32 end
33
34 local character = localPlayer.Character
35
36 -- default to no reverb
37 local newReverbType = Enum.ReverbType.NoReverb
38
39 if character and character.PrimaryPart then
40 local position = character.PrimaryPart.Position
41
42 -- go through all the indexed parts
43 for part, type in pairs(parts) do
44 -- see if the character is within them
45 if positionInPart(part, position) then
46 -- if so, pick that reverb type
47 newReverbType = type
48 break
49 end
50 end
51 end
52
53 -- set the reverb type if it has changed
54 if newReverbType ~= reverbType then
55 SoundService.AmbientReverb = newReverbType
56 reverbType = newReverbType
57 end
58end

Summary

Properties

The ambient sound environment preset used by SoundService.

The number of studs to be considered a meter by SoundService when calculating 3D Sound volume attenuation.

This property determines the degree to with a 3D Sounds pitch varies due to the Doppler effect.

Sets whether Sound playback from a client will replicate to the server.

Sets how fast 3D Sound volume attenuates, or 'rolls off'.

Events

Methods


GetListener returns SoundServices current listener type and what is set as listener.

PlayLocalSound(sound: Instance): void  

Plays a Sound locally, meaning the sound will only be heard by the client calling this function, regardless of where it's parented to.

SetInputDevice(name: string, guid: string): void  


SetListener(listenerType: ListenerType, listener: Tuple): void  

Sets the listener for the SoundService.

SetOutputDevice(name: string, guid: string): void  


SetRecordingDevice(deviceIndex: number): boolean  


EndRecording(): table  YIELDS


Properties

AmbientReverb

The ambient sound environment preset used by SoundService.

The ReverbType this property simulates a range of different environment's impact on sound. Each different option corresponds with a preset available in the FMOD sound engine. For example, when AmbientReverb is set to Hangar, the sound will reverberate differently to simulate being in a large enclosed space.

Changing the AmbientReverb effects the following properties used by Roblox's sound engine.

  • Reverberation decay time
  • Initial reflection delay time
  • Late reverberation delay time relative to initial reflection
  • Reference high frequency
  • High-frequency to mid-frequency decay time ratio
  • Value that controls the echo density in the late reverberation decay
  • Value that controls the modal density in the late reverberation decay
  • Reference low frequency
  • Relative room effect level at low frequencies
  • Relative room effect level at high frequencies
  • Early reflections level relative to room effect
  • Room effect level at mid frequencies

Those interested in finding more out about ambient reverb presets should see the FMOD documentation on the topic. For most developers however, the ReverbType names are descriptive enough to be able to use this setting without advanced knowledge.

DistanceFactor

The number of studs to be considered a meter by SoundService when calculating 3D Sound volume attenuation.

By default, the DistanceFactor is 3.33. This means, for the purposes of volume attenuation, a meter is considered 3.33 studs. The greater the DistanceFactor, the more gradually sound will attenuate.


1local SoundService = game:GetService("SoundService")
2SoundService.DistanceFactor = 1 -- 1 meter = 1 stud
3SoundService.DistanceFactor = 10 -- 1 meter = 10 studs
4

Developers are advised to only change this property if their game uses a different scale. For example, when using larger custom characters, developers may want to reduce the DistanceFactor. In all other cases, Sound settings such as Sound.RollOffMode should be used instead.

Those looking to find out more about how 3D sound in Roblox works, should consult the FMOD documentation.

DopplerScale

This property determines the degree to with a 3D Sounds pitch varies due to the Doppler effect.

The Doppler effect describes a phenomenon whereby the pitch of a sound changes as the source and observer of the sound move further away, or closer together. The Doppler effect can often be seen in real life, such as when a car with a siren drives past.

Increasing this value exaggerates the impact of the Doppler effect, whereas decreasing it minimizes it. By default, the value of this property is 1.


1local SoundService = game:GetService("SoundService")
2SoundService.DopplerScale = 1 -- default
3SoundService.DopplerScale = 2 -- exaggerated Doppler effect
4SoundService.DopplerEffect = 0.5 -- subdued Doppler effect
5

Note the Doppler effect has no impact on 2D Sounds, (Sounds not parented to a BasePart or Attachment).

Developers wishing to learn more about the different settings Roblox's sound engine uses should consult the FMOD documentation.

RespectFilteringEnabled

The RespectFilteringEnabled property determines whether Sound playback is replicated from the client to the server, and therefore from server . In other words, when a LocalScript calls Sound:Play() and this property is true, the sound will only play on the respective client. If the property is false, other clients will also hear the sound.

RolloffScale

Sets how fast 3D Sound volume attenuates, or 'rolls off'.

Note, this property only applies to Sounds whose Sound.RollOffMode property is set to 'Inverse' or 'InverseTapered'. 'Linear' and 'LinearSquare' RollOffModes use a different attenuation model which is not influenced by this property. This property also has no impact on 2D sounds (Sounds not parented to a BasePart or Attachment).

The higher the RolloffScale, the more rapidly a 3D sound's volume will attenuate as the distance between the listener and the sound increases.

By default the roll off scale is set to 1, which simulates the real world.


1local SoundService = game:GetService("SoundService")
2SoundService.RolloffScale = 1 -- attenuation simulates real world
3SoundService.RolloffScale = 2 -- sound attenuates twice as fast as the real world
4

Developers wishing to learn more about the different settings Roblox's sound engine uses should consult the FMOD documentation.

VolumetricAudio

Not Scriptable

Events

DeviceListChanged

Roblox Script Security

Parameters

newDevices: Tuple

Methods

BeginRecording

Roblox Script Security

Returns

GetInputDevice

Roblox Script Security

Returns

GetInputDevices

Roblox Script Security

Returns

GetListener

This function returns SoundService's current listener type and what is set as listener.

The first result returned is the ListenerType of the listener, the second result is dependent on the ListenerType:

ListenerTypeDescription
`Enum.ListenerType.Camera`Does not return a listener object as Workspace/CurrentCamera is always used
`Enum.ListenerType.CFrame`Returns the `Datatype.CFrame` used in `Class.SoundService:SetListener()`
`Enum.ListenerType.ObjectPosition`Returns the `Class.BasePart` used in `Class.SoundService:SetListener()`
`Enum.ListenerType.ObjectCFrame`Returns the `Class.BasePart` used in `Class.SoundService:SetListener()`

The listener can be changed using SoundService:SetListener().


1local SoundService = game:GetService("SoundService")
2SoundService:SetListener(Enum.ListenerType.CFrame, CFrame.new(0, 0, 0))
3local listenerType, listener = SoundService:GetListener()
4print(listenerType, listener)
5

What is a listener?

The listener determines the point from which audio in the game is being 'heard' by the player. For 3D Sounds (Sounds parented to a BasePart or Attachment) the listener influences the volume and left/right balance of a playing sound. Listeners have no influence on the playback of 2D sounds as they have no position of emission.

By default, the listener is set to the CurrentCamera. However, a range of different types of listeners can be used.


Returns

The current ListenerType and what the listener has been set to. Dependent on ListenerType the listener could be a BasePart, a CFrame or nil.

GetOutputDevice

Roblox Script Security

Returns

GetOutputDevices

Roblox Script Security

Returns

GetSoundMemoryData

Roblox Script Security

Returns

PlayLocalSound

void

Plays a Sound locally, meaning the sound will only be heard by the client calling this function, regardless of where it's parented to. This function is most useful for playing a Sound locally in the Studio client, for instance in a Script for a Plugin.

Parameters

sound: Instance

The Sound to be played.


Returns

void

Code Samples

Play Local Sound

1local ServerScriptService = game:GetService("ServerScriptService")
2local SoundService = game:GetService("SoundService")
3
4-- Create custom plugin button
5local toolbar = plugin:CreateToolbar("Empty Script Adder")
6local newScriptButton = toolbar:CreateButton("Add Script", "Create an empty Script", "rbxassetid://1507949215")
7
8local function playLocalSound(soundId)
9 local sound = Instance.new("Sound")
10 sound.SoundId = soundId
11 SoundService:PlayLocalSound(sound)
12 sound.Ended:Wait()
13 sound:Destroy()
14end
15
16local function onNewScriptButtonClicked()
17 -- Create new empty script
18 local newScript = Instance.new("Script")
19 newScript.Source = ""
20 newScript.Parent = ServerScriptService
21 playLocalSound("rbxassetid://0") -- Insert audio asset ID here
22end
23
24newScriptButton.Click:Connect(onNewScriptButtonClicked)

SetInputDevice

void
Roblox Script Security

Parameters

name: string
guid: string

Returns

void

SetListener

void

Sets the listener used by the client.

The first parameter is the ListenerType of the listener, the second paramater is dependent on the listener type.

  • Camera ListenerType - Does not return a listener object as Workspace.CurrentCamera is always used
  • CFrame ListenerType - The CFrame to be used
  • ObjectPosition ListenerType - The BasePart to be used
  • ObjectCFrame ListenerType - The BasePart to be used

The listener can be retrieved using SoundService:GetListener():


1local SoundService = game:GetService("SoundService")
2SoundService:SetListener(Enum.ListenerType.CFrame, CFrame.new(0, 0, 0))
3local listenerType, listener = SoundService:GetListener()
4print(listenerType, listener)
5

What is a listener?

The SoundService's listener determines the point from which audio in the game is being 'heard' by the player. For 3D Sounds (sounds parented to a BasePart or Attachment) the listener influences the volume and left/right balance of a playing sound. Listeners have no influence on the playback of 2D sounds as they have no position of emission.

By default, the listener is set to the CurrentCamera. However, a range of different types of listeners can be used.

Parameters

listenerType: ListenerType

The ListenerType of the listener.

listener: Tuple

Dependent on the ListenerType. BasePart for 'ObjectPosition' or 'ObjectCFrame', CFrame for 'CFrame', nil for 'Camera'.


Returns

void

SetOutputDevice

void
Roblox Script Security

Parameters

name: string
guid: string

Returns

void

SetRecordingDevice

Roblox Script Security

Parameters

deviceIndex: number

Returns

EndRecording

Yields
Roblox Script Security

Returns

GetRecordingDevices

Yields
Roblox Script Security

Returns