Sound

Sound : Instance

Overview

Sound is an object that plays audio.

When a Sound is parented to a BasePart (including MeshPart) or Attachment, it plays at that location and its volume changes with distance from the listener. Otherwise, it plays at the same volume throughout the place.

Sound is not actually heard on the server; sounds are simulated and played separately on the server and client. Therefore, depending on execution order or values changed locally, the server and client may have different playback positions and different start/end times.

For sounds playing on the server, the current state and properties of the Sound instance set on the server are replicated to users who join later, so they can hear the sound as well.

The playback range of a Sound is determined by the combination of PlaybackRegionsEnabled, StartTimePosition, PlaybackRegion, LoopRegion, and Looped. For detailed playback range control, see the Sound manual.

Properties

IsLoaded

boolean

Indicates whether a valid SoundId has been entered and the sound is loaded. Use it together with the Loaded event to check if the sound is loaded before playing.

When the sound is loaded, TimePosition is reset to 0. If you connect the Loaded event after the sound has already loaded, the event will not be called, so it is best to check IsLoaded first.

Code Samples

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

if Sound.IsLoaded then
    Sound:Play()
else
    Sound.Loaded:Wait()
    Sound:Play()
end

IsPaused

boolean

Returns true when the sound is not playing. It is true when the sound has been paused or stopped via Pause() or Stop(), has never been played, or an invalid SoundId has been entered.

This is a read-only property; use the Pause() or Stop() method to control playback.

Code Samples

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

if Sound.IsPaused then
    Sound:Resume()
end

IsPlaying

boolean

Returns true when the sound is currently playing. Unlike the Playing property, this is read-only; use the Play() method to control playback.

Code Samples

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

if not Sound.IsPlaying then
    Sound:Play()
end

Looped

boolean

Sets whether the sound plays in a loop. When set to true, the sound restarts from the beginning (or loop start) after it finishes.

Changing the value during playback applies immediately. While Looped is true, the Ended event does not fire even if the sound reaches the end, and Looped does not apply to sounds played through PlayOnRemove.

You can track the number of loops with the DidLoop event.

Code Samples

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

Sound.Looped = true

LoopRegion

NumberRange

A range in seconds that defines the desired loop start and end time within the PlaybackRegion.

PlaybackRegion determines the range used when starting or restarting a sound with Play(), while LoopRegion determines the range used when loops repeat. Therefore, if you call Play() again during looped playback, playback restarts based on PlaybackRegion.Min, not LoopRegion.Min.

To use this property, PlaybackRegionsEnabled must be true and Looped must be true. This property applies only during looped playback; on the first play, PlaybackRegion is used.

Changing the value while the sound is playing applies immediately. If PlaybackRegionsEnabled = false, you can set the value, but it does not apply to the actual playback range.

LoopRegion is applied as follows:

• First play (DidLoop = 0): PlaybackRegion is used; LoopRegion is ignored.

• Loop play (DidLoop ≥ 1): The narrower of LoopRegion and PlaybackRegion is used.

  • LoopRegion.Min > PlaybackRegion.Min: Start at LoopRegion.Min

  • LoopRegion.Min ≤ PlaybackRegion.Min: Start at PlaybackRegion.Min

  • LoopRegion.Max < PlaybackRegion.Max: End at LoopRegion.Max

  • LoopRegion.Max ≥ PlaybackRegion.Max: End at PlaybackRegion.Max

• LoopRegion.Min = LoopRegion.Max: This property is disabled and PlaybackRegion is used for the loop as well.

Code Samples

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

Sound.PlaybackRegionsEnabled = true
Sound.PlaybackRegion = NumberRange.new(0, 30)

Sound.LoopRegion = NumberRange.new(10, 25)
Sound.Looped = true

Sound:Play()

PlaybackLoudness

number

Represents the amplitude value of the currently playing sound in the range 0–1000. Useful for audio visualization or sound-reactive effects.

This value is calculated automatically based on the playing audio signal and is not affected by Volume, SoundGroup.Volume, distance attenuation, PlaybackSpeed, or system volume. However, it may become 0 if a 3D sound is outside RollOffMaxDistance. Because the server does not play audio, reading this value on the server always returns 0.

Code Samples

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

game:GetService("RunService").Heartbeat:Connect(function()
    local loudness = Sound.PlaybackLoudness
    Part.Size = Vector3.new(1, 1 + loudness / 100, 1)
end)

PlaybackRegion

NumberRange

A range in seconds that defines the desired start and end time within TimeLength.

PlaybackRegionsEnabled must be set to true to use this property.

Changing the value while the sound is playing applies immediately. If PlaybackRegionsEnabled = false, you can set the value, but it does not apply to the actual playback range.

Behavior:

• PlaybackRegion.Min > 0: Playback starts at PlaybackRegion.Min.

• PlaybackRegion.Min ≤ 0: Playback starts at 0 (negative values are clamped to 0).

• PlaybackRegion.Max < TimeLength: Playback ends exactly at that time.

• PlaybackRegion.Max ≥ TimeLength: Playback ends at TimeLength.

• PlaybackRegion.Min = PlaybackRegion.Max: This property is disabled (playback from 0 to TimeLength).

Code Samples

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

Sound.PlaybackRegionsEnabled = true
Sound.PlaybackRegion = NumberRange.new(5, 20)

Sound:Play()

PlaybackRegionsEnabled

boolean

Enables PlaybackRegion and LoopRegion so you can play only a specific part of the sound or define a loop segment. When PlaybackRegionsEnabled is on, StartTimePosition is ignored.

Changing the value while the sound is playing is reflected immediately.

Code Samples

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

Sound.PlaybackRegionsEnabled = true
Sound.PlaybackRegion = NumberRange.new(5, 20)

Sound.LoopRegion = NumberRange.new(10, 15)
Sound.Looped = true

Sound:Play()

PlaybackSpeed

number

Sets the playback speed of the sound. 1.0 is normal speed; higher values play faster and lower values play slower. Changing playback speed also changes the pitch.

Changing the value while the sound is playing applies immediately. The currently supported recommended range is 0.5–2.

Code Samples

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

Sound.PlaybackSpeed = 2.0
Sound:Play()

Playing

boolean

Indicates the playback state of the sound and can be set directly.

Behavior:

• Playing = false: Pauses the sound. TimePosition is preserved, and the Paused or Stopped event does not fire.

• Playing = true: Resumes playback from the current TimePosition. The Played or Resumed event does not fire.

• Difference from Play(): Play() starts from StartTimePosition (or PlaybackRegion.Min).

If it is already set to the same value, the operation is ignored.

Code Samples

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

Sound:Play()
wait(2)
Sound.Playing = false
wait(1)
Sound.Playing = true

PlayOnRemove

boolean

When set to true, the sound plays when the Sound instance is removed. If the sound is not playing when removed, it starts from the beginning; if it is playing when removed, it continues from the current position.

Useful for playing sounds when objects disappear, such as explosion or destruction effects.

Looped does not apply to sounds played through PlayOnRemove. If PlaybackRegionsEnabled = true, PlaybackRegion applies, and the Played, Resumed, Ended, Paused, and Stopped events do not fire.

For sounds played through PlayOnRemove, whether playback is 2D or 3D is determined based on the position where the sound was removed. For 3D sounds, attenuation based on RollOffMinDistance and RollOffMaxDistance still applies.

The sound plays in these cases:

• sound:Destroy()

• sound.Parent = nil

• sound.Parent.Parent = nil

Code Samples

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

Sound.PlayOnRemove = true
Sound:Destroy()

PreviewPlaying

boolean

Indicates the preview playback state of the sound.

Code Samples

PreviewTimePosition

number

Indicates the current playback position of the sound preview in seconds.

Code Samples

RollOffMaxDistance

number

Sets the maximum distance in studs at which a 3D sound (parented to a BasePart or Attachment) can be heard. Beyond this distance, the sound is inaudible. Attenuation does not apply to 2D sounds.

How the sound attenuates depends on RollOffMode.

Code Samples

local Workspace = game:GetService("Workspace")
local part = Workspace.Part
local Sound = part.Sound

Sound.RollOffMaxDistance = 100

RollOffMinDistance

number

Sets the minimum distance in studs at which a 3D sound (parented to a BasePart or Attachment) is heard at full volume. Beyond this distance, the sound attenuates according to RollOffMode. Attenuation does not apply to 2D sounds.

Code Samples

local Workspace = game:GetService("Workspace")
local part = Workspace.Part
local Sound = part.Sound

Sound.RollOffMinDistance = 10
Sound.RollOffMaxDistance = 100

RollOffMode

Enum.RollOffMode

Sets how the volume of a 3D sound (parented to a BasePart or Attachment) attenuates with distance. It determines how the sound fades between RollOffMinDistance and RollOffMaxDistance.

The default value is Enum.RollOffMode.Inverse. The Listener is based on the Camera by default, and attenuation does not apply to 2D sounds.

Attenuation is applied under the following conditions:

Listener distance	Sound volume state
distance ≤ RollOffMinDistance	Attenuation is not applied.
RollOffMinDistance < distance < RollOffMaxDistance	Attenuation is applied based on RollOffMode.
distance ≥ RollOffMaxDistance	The sound is inaudible.
RollOffMaxDistance = RollOffMinDistance	Attenuation is not applied.

Code Samples

local Workspace = game:GetService("Workspace")
local part = Workspace.Part
local Sound = part.Sound

Sound.RollOffMode = Enum.RollOffMode.Linear

SoundGroup

SoundGroup

Sets the SoundGroup this sound belongs to. All sounds in a SoundGroup are affected by the group’s Volume setting, so you can control their volume together.

Changing SoundGroup while the sound is playing applies immediately. If the SoundGroup's Volume is 0, sounds belonging to that group are not output.

Code Samples

local Workspace = game:GetService("Workspace")

local musicGroup = Instance.new("SoundGroup")
musicGroup.Volume = 0.5
musicGroup.Parent = Workspace

local Sound = Workspace.Sound

Sound.SoundGroup = musicGroup

SoundId

string

The asset ID of the sound file to play. Specify the sound asset using the ovdrassetid:// format.

SoundId is an empty string by default. Changing SoundId during playback stops the sound and resets TimePosition to 0, but values such as StartTimePosition, PlaybackRegion, and LoopRegion are preserved. The Stopped or Ended event does not fire in this case.

If SoundId is invalid or empty, TimePosition does not change, and a warning may be output when changing TimePosition. StartTimePosition can be set normally even if SoundId is invalid.

Loading may fail if you enter a nonexistent asset, an asset of a type other than sound, a private asset you do not have permission to access, or a value with an invalid URL format.

Code Samples

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

Sound.SoundId = "ovdrassetid://1234567890"
Sound:Play()

StartTimePosition

number

Sets the position in seconds from which to start when playing with the Play() method. This property only works when PlaybackRegionsEnabled = false.

Notable behavior:

• Negative values are clamped to 0.

• When Looped = true: Applied only on the first play; loops start from 0.

• Resume() or Playing = true resumes from the current TimePosition, not StartTimePosition.

• Values greater than TimeLength are preserved.

Code Samples

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

Sound.StartTimePosition = 50
Sound:Play()

wait(5)
Sound:Play()

TimeLength

number

The total length of the sound in seconds. Returns 0 if the sound is not loaded.

Use with PlaybackSpeed to adjust speed so the sound plays for a desired duration.

Code Samples

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

Sound.PlaybackSpeed = Sound.TimeLength / 5
Sound:Play()

TimePosition

number

The current playback position of the sound in seconds. Changing this value immediately seeks the playback position while the sound is playing.

While the sound is playing, TimePosition increases at a rate of PlaybackSpeed per second and stops when it reaches TimeLength unless Looped is true.

If you set TimePosition below the playable range, playback starts at the start of the playable range. If you set it beyond the playable range, the next loop proceeds when Looped = true; when Looped = false, the Ended event fires and playback ends.

Code Samples

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

Sound:Play()
wait(2)
Sound.TimePosition = 10

local progress = Sound.TimePosition / Sound.TimeLength * 100
print("Playback progress:", progress, "%")

Volume

number

Sets the volume of the sound. Value between 0 (mute) and 10 (max); default is 0.5.

If the sound is in a SoundGroup, it is also affected by the group’s Volume setting.

The final output volume is affected by Sound.Volume, SoundGroup.Volume, distance attenuation, audio effects, and other factors together.

Code Samples

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

Sound.Volume = 2.0
Sound:Play()

Methods

Pause

Pauses the sound. TimePosition is preserved, so you can resume from the same position with Resume().

Only works when a valid sound asset is set. If called on a sound that is already stopped or not playing, the Paused event does not fire.

Parameters

Return

void

Code Samples

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

Sound:Play()
wait(2)
Sound:Pause()

Play

Starts playing the sound. The start position depends on the PlaybackRegionsEnabled setting.

Only works when a valid sound asset is set.

Start position:

• PlaybackRegionsEnabled = false: Starts from StartTimePosition

• PlaybackRegionsEnabled = true: Starts from PlaybackRegion.Min

Calling Play() again while playing seeks back to the start position. In this case, the sound is already playing, so the Played event does not fire.

Parameters

Return

void

Code Samples

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

Sound.StartTimePosition = 10
Sound:Play()

Resume

Resumes a stopped sound from the current TimePosition. Used together with Pause().

Only works when a valid sound asset is set. If called on a sound that is already playing, the Resumed event does not fire.

Parameters

Return

void

Code Samples

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

Sound:Play()
wait(2)
Sound:Pause()
wait(1)
Sound:Resume()

Stop

Stops the sound and resets TimePosition to 0 while keeping other properties unchanged.

So after Stop(), calling Play() will start from StartTimePosition.

Only works when a valid sound asset is set. If called on a sound that is already in the Ended or Stopped state, the Stopped event does not fire.

Parameters

Return

void

Code Samples

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

Sound.StartTimePosition = 10
Sound:Play()
wait(2)
Sound:Stop()

Sound:Play()

Events

DidLoop

Fires each time the sound loops. Calling Stop() resets the loop counter to 0.

Parameters

string SoundId	SoundId of the sound that looped
number numOfTimesLooped	Number of times the sound has looped

Code Samples

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

Sound.DidLoop:Connect(function(soundId, numOfTimesLooped)
    print("Loop count:", numOfTimesLooped)
    if numOfTimesLooped >= 3 then
        Sound:Stop()
    end
end)

Sound.Looped = true
Sound:Play()

Ended

Fires when the sound has played to the end and stopped.

It does not fire in these cases:

• When Looped = true

• When stopped with Stop() before the end (use the Stopped event instead)

Parameters

string SoundId	SoundId of the sound that finished playing

Code Samples

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

Sound.Ended:Connect(function(soundId)
    print("Playback finished:", soundId)
    Sound:Destroy()
end)

Sound:Play()

Loaded

Fires when the sound is loaded. It does not fire if the sound is already loaded, so it is best to check IsLoaded first.

Parameters

string SoundId	SoundId of the loaded sound

Code Samples

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

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

Paused

Fires when the sound is paused via the Pause() method.

Parameters

string SoundId	SoundId of the paused sound

Code Samples

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

Sound.Paused:Connect(function(soundId)
    print("Paused:", soundId)
end)

Sound:Play()
wait(1)
Sound:Pause()

Played

Fires when the sound starts playing via the Play() method.

Does not fire when playback starts due to PlayOnRemove = true.

If Play() is called on a sound that is already playing and only seeks back to the start position, this event does not fire.

Parameters

string SoundId	SoundId of the sound that played

Code Samples

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

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

Resumed

Fires when the sound is resumed via the Resume() method.

Parameters

string SoundId	SoundId of the resumed sound

Code Samples

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

Sound.Resumed:Connect(function(soundId)
    print("Resumed:", soundId)
end)

Sound:Play()
wait(1)
Sound:Pause()
wait(1)
Sound:Resume()

Stopped

Fires when a playing sound is stopped with the Stop() method.

It does not fire when the sound is destroyed with Destroy() or when SoundId is changed during playback.

Parameters

string SoundId	SoundId of the stopped sound

Code Samples

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

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

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