Sound
Load and play audio, control looping and volume, and react when playback ends.
Sound is an audio source you place in the hierarchy. Give it a SoundId, call Play(), and it plays from the listener's position unless you attach it to a part for 3D positioning.
A Sound is created like any other instance:
local sound = Instance.new("Sound")
sound.SoundId = "sounds/click.wav"
sound.Parent = part
sound:Play()Parent a sound to a Part when you want it positioned in the world. The roll-off distances control how quickly it fades as the listener moves away.
Playing audio
local function playOnce(template, parent)
local sound = template:Clone()
sound.Parent = parent
sound.Looped = false
sound:Play()
endPlay() loads the audio the first time it's called if it isn't loaded already, then starts playback. It returns nothing; check IsPlaying afterward if you need to know whether playback actually started.
Playing is a read/write property that does the same thing declaratively:
sound.Playing = true
sound.Playing = falseProperties
| Property | Type | Access | Default | Description |
|---|---|---|---|---|
SoundId | string | Read/write | "" | Asset path of the audio to play. Changing it reloads the sound. |
AudioContent | Content | Read/write | Empty | Inline audio content, used when SoundId is empty. |
IsLoaded | boolean | Read-only | false | Whether the audio stream has loaded. |
IsPlaying | boolean | Read-only | false | Whether the stream is actively playing. |
IsPaused | boolean | Read-only | true | Whether playback is paused. |
Playing | boolean | Read/write | false | Requested playback state. Setting it starts or stops the sound. |
Looped | boolean | Read/write | false | Whether playback repeats. |
Volume | number | Read/write | 0.5 | Playback volume. Negative values clamp to 0. |
PlaybackSpeed | number | Read/write | 1 | Playback rate and pitch. Values at or below 0 are ignored. |
PlaybackLoudness | number | Read-only | 0 | Current output loudness. |
TimePosition | number | Read/write | 0 | Playback position. Negative values clamp to 0. |
TimeLength | number | Read-only | 0 | Length of the loaded audio in seconds. |
LoopRegion | NumberRange | Read/write | Unset | The portion of the audio used for looping. |
PlaybackRegion | NumberRange | Read/write | Unset | The portion of the audio that plays. |
PlaybackRegionsEnabled | boolean | Read/write | false | Whether PlaybackRegion and LoopRegion are applied. |
PlayOnRemove | boolean | Read/write | false | Stored flag for playing when the sound is removed. |
RollOffMinDistance | number | Read/write | 10 | Distance at which 3D attenuation starts. |
RollOffMaxDistance | number | Read/write | 10000 | Distance at which 3D attenuation ends. |
IsPlaying and Playing aren't the same thing. Playing is the state you asked for; IsPlaying reports whether the audio stream is actually running. They can disagree briefly, for example while a stream loads.
PlaybackSpeed values at or below zero are ignored rather than raising an error, so an invalid assignment leaves the previous speed in place. Volume, RollOffMinDistance, and RollOffMaxDistance clamp negative values to zero.
Loading
SoundId accepts an asset path. Assigning a new path unloads the current stream and loads the new one, so IsLoaded can be false immediately after a change.
If loading fails, Play() returns without starting playback and IsPlaying stays false. Treat a silent sound as a missing or unreadable asset rather than assuming the call worked.
AudioContent is an alternative for audio that ships inline. It's only consulted when SoundId is empty.
Methods
| Signature | Description |
|---|---|
Play(): () | Loads the audio if needed and starts playback. |
Pause(): () | Pauses playback, keeping the current position. |
Resume(): () | Resumes a paused sound. |
Stop(): () | Stops playback and resets the stored position to 0. |
local function restart(sound)
sound:Stop()
sound:Play()
endPause() only affects a sound that's actually playing, and Resume() only affects a paused one. Calling either in the wrong state does nothing. Stop() does nothing to the stream if it isn't loaded, but still resets the stored position.
None of these methods return a value, so check IsPlaying if you need to confirm the result.
Events
Ended
Fires when a non-looped sound reaches the end of its audio. The callback receives no arguments.
sound.Ended:Connect(function()
sound:Destroy()
end)Looped sounds don't fire Ended when they wrap around; they keep playing until you stop them. A sound that's stopped manually doesn't fire Ended either.
Notes
- The class metadata also lists
DidLoop,Loaded,Paused,Played,Resumed, andStopped, but those signals aren't exposed by the current implementation. RollOffModeappears in the property metadata but isn't readable or writable through the current property accessors.- Assigning
TimePositionstores a new position but doesn't seek the loaded stream in this implementation. Restart the sound instead if you need to jump. PlayOnRemoveis stored and readable, but nothing acts on it when the sound is removed in the current implementation.- Cloning a sound copies its path, volume, speed, looping, and region settings, and it starts in the same playback state as the original.
See also
Instance, parenting and cloning behavior.SoundService, the audio service, which currently exposes no Luau members.
