Sound

Sound : Instance

Overview

Sound is an object used to generate sound.

A Sound placed as a child of BasePart or Attachment generates sound in that position and the volume changes as the distance to listener changes. In other cases, the volume is constant in the entire place.

Properties

IsLoaded

bool

Specifies whether a sound is loaded to server and ready to be played. If this property is true, the sound is successfully loaded and ready to be played.

It is used in conjunction with the Loaded event to check whether a sound is loaded before playing it.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.IsLoaded)

IsPaused

bool

Returns true if the sound is not being played.

Returns true if the sound is paused by the Pause() method, stopped by the Stop() method, or it has never been played. This property cannot be used to stop the playback of a sound; use either the Stop() or Pause() method instead.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.IsPaused)

IsPlaying

bool

Returns true if the sound is being played. This property cannot be used to play a sound; use the Play() method instead.

Unlike the Playing property, this property is read-only.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.IsPlaying)

LoopRegion

NumberRange

Currently not supported.

Code Samples

Looped

bool

Sets whether to replay a sound when its playback is finished.

If set true, the sound is repeated until it is stopped or paused. It is useful for a sound effect that requires constant playback, like background music or ambient sound.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound.Looped = true

PlayOnRemove

bool

If set true, the sound is played when it is removed from experience. The sound is played if:

• sound:Destroy()

• sound.Parent = nil

• sound.Parent.Parent = nil

It is useful when creating a sound effect for a removable object like explosion.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.PlayOnRemove)

PlaybackLoudness

number

A number between 0 and 1,000, specifying the volume of the sound being played.

This property is useful when creating an audio equalizer or a visual effect responsive to a sound because it applies the amplitude of a sound in real time.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.PlaybackLoudness)

PlaybackRegion

NumberRange

Currently not supported.

Code Samples

PlaybackRegionsEnabled

bool

Currently not supported.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.PlaybackRegionsEnabled)

PlaybackSpeed

number

The PlaybackSpeed property is a numeric value determining the speed of the playback speed of an audio track.

The normal playback speed is 1.0. A value greater than 1.0 accelerates the playback speed; a value less than 1.0 decelerates the playback speed.

This property is useful for time manipulation effects, slow motion, creating fast-forward audio design, or in scenarios where audio playback speed must be synchronized with other gameplay elements or animation.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.PlaybackSpeed)

Playing

bool

This property indicates whether the sound is currently being played. It can be toggled and is always replicated.

If Playing is set false, the sound is stopped, but TimePosition is not reset. If Playing is set true again, the sound is resumed from its current position. On the other hand, the Play() method plays the sound from StartTimePosition.

This property is different from the IsPlaying property, which is read-only.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound.Playing = false

RollOffMaxDistance

number

RollOffMaxDistance is a numeric property within the Lua Sound class of the game development platform.

It specifies the maximum distance at which a 3D sound begins attenuating or its volume begins decreasing when the sound is moving away from its parent object (BasePart or Attachment), measured in centimeters.

Developer can control the range and intensity of a 3D sound in game through this property.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.RollOffMaxDistance)

RollOffMinDistance

number

The RollOffMinDistance property is a numeric value specifying the minimum distance at which a sound is heard at the maximum intensity.

The sound past this distance begins attenuating according to the roll-off curve or mode defined for the sound object.

This property is important when defining spatial audio experience in a 3D environment such as game or simulation. It ensures realistic sound when listener is getting closer or moving away from sound source.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.RollOffMinDistance)

RollOffMode

Enum.RollOffMode

The RollOffMode property is the Enum.RollOffMode type and it determines how sound is attenuated as it travels in a space.

This property offers flexibility in many different use cases of audio design in a 3D environment by controlling how sound attenuates by distance.

Developer can customize audio experience by creating a linear, logarithmic, or user-defined attenuation curve according to desired realism mode or effect through various roll-off modes.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.RollOffMode)

SoundGroup

SoundGroup

The SoundGroup property is a group of sound objects that shares a specific setting or action such as volume, pitch, or effect filter.

As developer can manage various sounds as if they are a single entity, it is much easier for developer to adjust the audio experience of a group rather than adjusting it individually.

A sound group allows the advanced audio control and effective management of the audio in game or application where sound needs to be adjusted dynamically or by scenario.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.SoundGroup)

SoundId

string

The unique identifier of the sound file to be played. Setting the ID of a sound asset for this property allows the sound to be loaded and played.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.SoundId)

StartTimePosition

number

Sets the starting point of a sound when it is played by the Play() method, measured in seconds.

When the Play() method is called, the sound begins playing from the position set by this property. If Play() is called again while the sound is being played, it will always begin playing from the position set by StartPosition, disregarding the current TimePosition.

When the Stop() method is called, this property is reset to 0. On the other hand, both the Resume() method and Playing = true resume playing the sound from TimePosition, not from StartTimePosition.

This property controls only the playback starting point. If the current position of the sound being played needs to be checked, use the TimePosition property instead.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

-- Sets the sound to be played from the 50-second mark.
Sound.StartTimePosition = 50
Sound:Play()

-- Replays the sound from the 50-second mark when Play is called during playback
wait(5)  -- Although TimePosition is approximately at the 55-second mark,
Sound:Play()  -- the sound replays at the 50-second mark

TimeLength

number

The length of a sound measured in seconds. For an unloaded sound, this value is 0.

This property, along with PlaybackSpeed, is often used to adjust the playback speed of a sound so that it can be played during a specific timeframe.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

print(Sound.TimeLength)

TimePosition

number

The current playback position of a sound, measured in seconds. Change this value to instantly move the play position of a sound during playback.

TimePosition is increased by the PlaybackSpeed ratio per second during playback. When TimePosition reaches TimeLength, the sound stops playing unless it is Looped.

Both the Resume() method and Playing = true resume playing the sound from TimePosition. If the Stop() method is called, this property is reset to 0. On the other hand, the Play() method plays the sound from StartTimePosition.

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound.TimePosition = 0.9

Volume

number

The volume of a sound. Default is 0.5 and this value can be set between 0 and 10.

If the sound is a member of SoundGroup, the playback volume is affected by the SoundGroup.Volume property of the group (note that the value of this property itself does not change).

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound.Volume = 0.5

Methods

Pause

Pauses the sound if it is being played.

Because the Playing property is set false, but TimePosition is not reset, both Resume() and Playing = true can resume playing the sound from the current TimePosition.

Parameters

Return

void

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound:Pause()

Play

Plays a sound. Moves the playback position to the value set by StartTimePosition and sets the Playing property true.

Parameters

Return

void

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

Sound:Play()

Resume

Resumes the playback of a sound. Because the Playing property is set true, but TimePosition is unchanged, the sound is resumed from the position of TimePosition.

Used to resume the playback of a sound from the position paused by the Pause() method.

Parameters

Return

void

Code Samples

Sound:Pause()
wait(2)

Sound:Resume()

Stop

Stops playback. The Playing property is set false and both TimePosition and StartTimePosition are reset to 0.

Parameters

Return

void

Code Samples

Sound:Stop()

Events

Ended

Occurs when the playback of a sound is finished and stopped. It is often used for tasks like removing a sound of which playback is finished.

Note: This event does not occur for a sound of which Looped is set true (because such a sound is played in loop).

This event does not occur if a sound is stopped before its playback is finished, either. In this case, use the Stopped event instead.

Parameters

string SoundId	The SoundId of the sound of which playback is finished

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnEnded()
    print("Sound has ended.")
end
Sound.Ended:Connect(OnEnded)

Loaded

Occurs when the sound is loaded.

As this event occurs only when a sound is loaded, it is recommended to check the IsLoaded property of the sound before connecting it with this event.

Parameters

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnLoaded()
    print("Sound has been loaded.")
end
Sound.Loaded:Connect(OnLoaded)

Paused

Occurs whenever the playback of a sound is paused by the Pause() method.

Parameters

string SoundId	The SoundId of the sound of which playback is paused

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnPaused()
    print("Sound has been paused.")
end
Sound.Paused:Connect(OnPaused)

Played

Occurs whenever the sound is played by the Play() method.

Note: This event does not occur if a sound is played at the time of its removal, due to PlayOnRemove being set true.

Parameters

string SoundId	The SoundId of the played sound

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnPlayed()
    print("Sound has started playing.")
end
Sound.Played:Connect(OnPlayed)

Resumed

Occurs when the playback of a sound is resumed by the Resume() method.

Parameters

string SoundId	The SoundId of the resumed sound

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnResumed()
    print("Sound has resumed playing.")
end
Sound.Resumed:Connect(OnResumed)

Stopped

Occurs when the playback of a sound is stopped by the Stop() method. This event does not occur if a sound is removed during its playback.

Parameters

string SoundId	The SoundId of the stopped sound

Code Samples

local Worksapce = game:GetService("Workspace")
local Sound = Worksapce.Sound

local function OnStopped(soundId)
    print("Sound has stopped:", soundId)
end
Sound.Stopped:Connect(OnStopped)

Sound:Play()
wait(2)
Sound:Stop()

See also

Sound