Skip to Content
Kinemium

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()
end

Play() 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 = false

Properties

PropertyTypeAccessDefaultDescription
SoundIdstringRead/write""Asset path of the audio to play. Changing it reloads the sound.
AudioContentContentRead/writeEmptyInline audio content, used when SoundId is empty.
IsLoadedbooleanRead-onlyfalseWhether the audio stream has loaded.
IsPlayingbooleanRead-onlyfalseWhether the stream is actively playing.
IsPausedbooleanRead-onlytrueWhether playback is paused.
PlayingbooleanRead/writefalseRequested playback state. Setting it starts or stops the sound.
LoopedbooleanRead/writefalseWhether playback repeats.
VolumenumberRead/write0.5Playback volume. Negative values clamp to 0.
PlaybackSpeednumberRead/write1Playback rate and pitch. Values at or below 0 are ignored.
PlaybackLoudnessnumberRead-only0Current output loudness.
TimePositionnumberRead/write0Playback position. Negative values clamp to 0.
TimeLengthnumberRead-only0Length of the loaded audio in seconds.
LoopRegionNumberRangeRead/writeUnsetThe portion of the audio used for looping.
PlaybackRegionNumberRangeRead/writeUnsetThe portion of the audio that plays.
PlaybackRegionsEnabledbooleanRead/writefalseWhether PlaybackRegion and LoopRegion are applied.
PlayOnRemovebooleanRead/writefalseStored flag for playing when the sound is removed.
RollOffMinDistancenumberRead/write10Distance at which 3D attenuation starts.
RollOffMaxDistancenumberRead/write10000Distance 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

SignatureDescription
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()
end

Pause() 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, and Stopped, but those signals aren't exposed by the current implementation.
  • RollOffMode appears in the property metadata but isn't readable or writable through the current property accessors.
  • Assigning TimePosition stores a new position but doesn't seek the loaded stream in this implementation. Restart the sound instead if you need to jump.
  • PlayOnRemove is 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.

On this page