Skip to content

SmartAudio

SmartAudio objects are SmartObjects that wrap sound files. Similar to Audio objects, they have many of the same properties and functions.

Properties

Property Name Return Type Description Tags
isPlaying boolean Returns if the sound is currently playing. Read-Only
isSpatializationEnabled boolean Default true. Set to false to play sound without 3D positioning. Read-Write
isAttenuationEnabled boolean Default true, meaning sounds will fade with distance. Read-Write
isOcclusionEnabled boolean Default true. Changes attenuation if there is geometry between the player and the audio source. Read-Write
isAutoPlayEnabled boolean Default false. If set to true when placed in the editor (or included in a template), the sound will be automatically played when loaded. Read-Only
isTransient boolean Default false. If set to true, the sound will automatically destroy itself after it finishes playing. Read-Write
isAutoRepeatEnabled boolean Loops when playback has finished. Some sounds are designed to automatically loop, this flag will force others that don't. Useful for looping music. Read-Write
pitch number Default 1. Multiplies the playback pitch of a sound. Note that some sounds have clamped pitch ranges (0.2 to 1). Read-Write
volume number Default 1. Multiplies the playback volume of a sound. Note that values above 1 can distort sound, so if you're trying to balance sounds, experiment to see if scaling down works better than scaling up. Read-Write
radius number Default 0. If non-zero, will override default 3D spatial parameters of the sound. Radius is the distance away from the sound position that will be played at 100% volume. Read-Write
falloff number Default 0. If non-zero, will override default 3D spatial parameters of the sound. Falloff is the distance outside the radius over which the sound volume will gradually fall to zero. Read-Write
fadeInTime number Sets the fade in time for the audio. When the audio is played, it will start at zero volume, and fade in over this many seconds. Read-Write
fadeOutTime number Sets the fadeout time of the audio. When the audio is stopped, it will keep playing for this many seconds, as it fades out. Read-Write
startTime number The start time of the audio track. Default is 0. Setting this to anything else means that the audio will skip ahead that many seconds when played. Read-Write
stopTime number The stop time of the audio track. Default is 0. A positive value means that the audio will stop that many seconds from the start of the track, including any fade out time. Read-Write

Functions

Function Name Return Type Description Tags
Play() None Begins sound playback. None
Stop() None Stops sound playback. None
FadeIn(number time) None Starts playing and fades in the sound over the given time. None
FadeOut(number time) None Fades the sound out and stops over time seconds. None

Examples

Example using:

Play

In this example, a small script is placed as the child of an audio object in the hierarchy. Play() is called as soon as the client connects. If the audio object has any smart properties, those are printed out to the Event Log. For best results place audio objects inside a client context.

local AUDIO = script.parent

AUDIO:Play()

if AUDIO:IsA("SmartAudio") then
    print("Smart properties for " .. AUDIO.name)
    local properties = AUDIO:GetSmartProperties()
    for key,value in pairs(properties) do
        print(key .. " = " .. value)
    end
else
    print(AUDIO.name .. " is not a Smart Audio object.")
end

See also: SmartObject.GetSmartProperties | CoreObject.parent | Other.IsA

Example using:

Play

Stop

FadeIn

FadeOut

isPlaying

In this example, a random song from a folder containing a list of songs is picked and played for 10 seconds before another song is picked at random.

-- Client script

-- The folder containing a list of songs to pick from.
local musicFolder = script:GetCustomProperty("music"):WaitForObject()

-- The time a song is allowed to player for.
local allowedPlayTime = 10

-- If the song should fade in and out.
local fadeInOut = true

-- Duration of the fade in and out.
local fadeInTime = 1
local fadeOutTime = 1

local songs = musicFolder:GetChildren()
local current

local totalPlayTime = 0

-- Attempt to find a song that wasn't played previously.
local function GetRandomSong()
    local song

    if current == nil then
        song = songs[math.random(1, #songs)]
    else
        if #songs == 1 then
            song = songs[1]
        else
            repeat
                song = songs[math.random(1, #songs)]
            until song ~= current
        end
    end

    return song
end

local function PlaySong()
    if current ~= nil then
        if fadeInOut then
            current:FadeOut(fadeOutTime)
        else
            current:Stop()
        end
    end

    totalPlayTime = 0
    current = GetRandomSong()

    if fadeInOut then
        current:FadeIn(fadeInTime)
    else
        current:Play()
    end
end

-- Keep track of how long the song has been playing for.
function Tick(dt)
    if current ~= nil then
        if totalPlayTime > allowedPlayTime then
            PlaySong()
        else
            if not current.isPlaying then
                totalPlayTime = 0
            else
                totalPlayTime = totalPlayTime + dt
            end
        end
    end
end

PlaySong()

See also: CoreObject.GetCustomProperty | CoreLua.Tick

Example using:

pitch

isPlaying

Play

In this client script the pitch of a piano note is modified over time to give it a vibrato-like effect.

local SFX = script:GetCustomProperty("PianoSampledInstrument01"):WaitForObject()
local PITCH_CHANGE = 200
local DURATION = 0.25
local elapsedTime = 0

function PlayWithLinearVibrato()
    SFX.pitch = 0
    SFX:Play()
    elapsedTime = 0
end

function Tick(deltaTime)
    if SFX.isPlaying and elapsedTime < DURATION then
        elapsedTime = elapsedTime + deltaTime
        if elapsedTime > DURATION then
            elapsedTime = DURATION
        end
        -- Linear modification of pitch over time
        SFX.pitch = PITCH_CHANGE * elapsedTime / DURATION
        print("pitch = " .. SFX.pitch)
    end
end

Task.Wait(1)
PlayWithLinearVibrato()

See also: CoreObject.GetCustomProperty | CoreObjectReference.WaitForObject | CoreLua.Tick | Task.Wait

Example using:

volume

In this example, two UI buttons are setup to control the volume of a music object. The script is placed as a child of the music object and the buttons are added to the script as custom properties.

local MUSIC = script.parent
local PLUS_BUTTON = script:GetCustomProperty("PlusButton"):WaitForObject()
local MINUS_BUTTON = script:GetCustomProperty("MinusButton"):WaitForObject()

MUSIC:Play()

function IncreaseVolume()
    MUSIC.volume = MUSIC.volume + 0.1
end

function DecreaseVolume()
    MUSIC.volume = MUSIC.volume - 0.1
end

PLUS_BUTTON.clickedEvent:Connect(IncreaseVolume)
MINUS_BUTTON.clickedEvent:Connect(DecreaseVolume)

See also: UIButton.clickedEvent | CoreObject.parent

Tutorials

Audio in Core

Last update: December 23, 2021