Sound

Sound : Instance

Overview

Sound는 사운드를 발생시키는 객체입니다.

Sound가 BasePart 또는 Attachment의 자식으로 배치되면 해당 위치에서 사운드가 발생하며, 청취자와의 거리에 따라 볼륨이 변화합니다. 그 외의 경우 플레이스 전체에서 동일한 볼륨으로 재생됩니다.

Properties

IsLoaded

bool

사운드가 서버에서 로드되어 재생할 준비가 되었는지를 나타냅니다. 이 속성이 true이면 사운드가 성공적으로 로드되어 재생 가능한 상태입니다.

Loaded 이벤트와 함께 사용하여 사운드를 재생하기 전에 로드 여부를 확인할 수 있습니다.

Code Samples

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

print(Sound.IsLoaded)

IsPaused

bool

사운드가 재생 중이지 않을 때 true를 반환합니다.

Pause() 메서드로 일시 정지된 경우, Stop() 메서드로 중지된 경우, 또는 한 번도 재생되지 않은 경우 모두 true를 반환합니다. 이 속성으로 사운드를 중지할 수는 없으며, Stop() 또는 Pause() 메서드를 사용해야 합니다.

Code Samples

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

print(Sound.IsPaused)

IsPlaying

bool

사운드가 현재 재생 중일 때 true를 반환합니다. 이 속성으로 사운드를 재생할 수는 없으며, Play() 메서드를 사용해야 합니다.

이 속성은 Playing 속성과 달리 읽기 전용입니다.

Code Samples

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

print(Sound.IsPlaying)

LoopRegion

NumberRange

현재 지원되지 않습니다.

Code Samples

Looped

bool

사운드가 재생을 완료한 후 반복할지 여부를 설정합니다.

true로 설정하면 사운드가 중지되거나 일시 정지될 때까지 계속 반복됩니다. 배경 음악, 주변 사운드 또는 지속적인 재생이 필요한 사운드 효과에 적합합니다.

Code Samples

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

Sound.Looped = true

PlayOnRemove

bool

true로 설정하면 사운드가 경험에서 제거될 때 재생됩니다. 다음의 경우 사운드가 재생됩니다:

• sound:Destroy()

• sound.Parent = nil

• sound.Parent.Parent = nil

폭발과 같이 삭제되는 객체에 대한 사운드 효과를 만드는 데 유용합니다.

Code Samples

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

print(Sound.PlayOnRemove)

PlaybackLoudness

number

사운드가 현재 재생 중인 음량을 나타내는 0에서 1000 사이의 숫자입니다.

이 속성은 사운드의 진폭을 실시간으로 반영하며, 오디오 이퀄라이저나 사운드에 반응하는 시각 효과를 만드는 데 유용합니다.

Code Samples

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

print(Sound.PlaybackLoudness)

PlaybackRegion

NumberRange

현재 지원되지 않습니다.

Code Samples

PlaybackRegionsEnabled

bool

현재 지원되지 않습니다.

Code Samples

PlaybackSpeed

number

PlaybackSpeed 속성은 오디오 트랙이 재생되는 속도를 결정하는 숫자 값입니다.

1.0 값은 정상 재생 속도를 나타내며, 1.0보다 큰 값은 재생 속도를 높이고, 1.0보다 작은 값은 속도를 낮춥니다.

이 속성은 시간 조작 효과, 슬로우 모션 또는 빨리 감기 오디오 디자인 생성, 또는 오디오 재생 속도를 다른 게임플레이 요소나 애니메이션과 동기화하는 것과 같은 시나리오에서 유용합니다.

Code Samples

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

print(Sound.PlaybackSpeed)

Playing

bool

사운드가 현재 재생 중인지 여부를 나타냅니다. 이 속성은 토글 가능하며 항상 복제됩니다.

Playing을 false로 설정하면 사운드가 중지되지만 TimePosition은 리셋되지 않습니다. 따라서 Playing을 다시 true로 설정하면 현재 TimePosition 위치부터 재생이 계속됩니다. 반면 Play() 메서드를 사용하면 StartTimePosition부터 재생됩니다.

이 속성은 읽기 전용인 IsPlaying 속성과 다릅니다.

Code Samples

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

Sound.Playing = false

RollOffMaxDistance

number

RollOffMaxDistance는 게임 개발 플랫폼의 Lua Sound 클래스 내의 숫자 속성입니다.

3D 사운드가 부모 객체(BasePart 또는 Attachment)에서 멀어질 때 감쇠되거나 볼륨이 감소하기 시작하는 최대 거리를 나타냅니다(cm 단위로 측정).

이 속성을 통해 개발자는 게임 내에서 3D 사운드의 범위와 강도를 제어할 수 있습니다.

Code Samples

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

print(Sound.RollOffMaxDistance)

RollOffMinDistance

number

RollOffMinDistance 속성은 사운드가 최대 강도로 들리는 최소 거리를 지정하는 숫자 값입니다.

이 거리를 넘어서면 사운드는 사운드 객체에 대해 정의된 롤오프 곡선 또는 모드에 따라 감쇠되기 시작합니다.

이 속성은 게임이나 시뮬레이션과 같은 3D 환경에서 공간 오디오 경험을 정의하는 데 중요하며, 청취자가 사운드 소스에 가까워지거나 멀어질 때 사운드가 현실적으로 동작하도록 보장합니다. 이 속성을 적절히 사용하면 실제 오디오 동작을 시뮬레이션하여 몰입감을 향상시킬 수 있습니다.

Code Samples

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

print(Sound.RollOffMinDistance)

RollOffMode

Enum.RollOffMode

RollOffMode 속성은 Enum.RollOffMode 타입이며 사운드가 공간을 이동할 때 사운드 감쇠가 계산되는 방식을 결정합니다.

이 속성은 거리에 따라 사운드가 감소하는 방식을 제어하여 3D 환경의 오디오 디자인에서 다양한 사용 사례에 유연성을 제공합니다.

다양한 롤오프 모드를 통해 개발자는 원하는 현실감 또는 효과에 따라 선형, 로그 또는 사용자 정의 감쇠 곡선을 만드는 등 오디오 경험을 사용자 정의할 수 있습니다. 이 속성을 적절히 구성하면 게임이나 시뮬레이션과 같은 애플리케이션에서 몰입감이 향상됩니다.

Code Samples

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

print(Sound.RollOffMode)

SoundGroup

SoundGroup

SoundGroup 속성은 볼륨, 피치 또는 효과 필터와 같은 특정 설정이나 동작을 공유하는 사운드 객체의 그룹을 나타냅니다.

이 속성을 통해 개발자는 여러 사운드를 집합적으로 관리할 수 있으므로 개별적으로가 아닌 그룹의 오디오 경험을 더 쉽게 조정할 수 있습니다.

사운드 그룹은 동적 또는 시나리오별 조정이 필요한 게임이나 멀티미디어 애플리케이션에서 특히 고급 오디오 조작과 효율적인 관리를 가능하게 합니다.

Code Samples

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

print(Sound.SoundGroup)

SoundId

string

재생할 사운드 파일의 고유 식별자입니다. 이 속성에 사운드 에셋의 ID를 설정하면 해당 사운드를 로드하고 재생할 수 있습니다.

Code Samples

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

print(Sound.SoundId)

StartTimePosition

number

사운드가 Play() 메서드로 재생될 때 시작할 위치를 초 단위로 설정합니다.

Play() 메서드를 호출하면 사운드는 이 속성에 설정된 위치부터 재생을 시작합니다. 재생 중에 Play()를 다시 호출하면 현재 TimePosition과 관계없이 항상 StartPosition에 설정된 위치부터 재생됩니다.

Stop() 메서드를 호출하면 이 속성은 0으로 리셋됩니다. 반면 Resume() 메서드나 Playing = true는 StartTimePosition이 아닌 현재 TimePosition부터 재생을 이어갑니다.

이 속성은 재생 시작 위치만 제어하며, 재생 중인 사운드의 현재 위치를 확인하려면 TimePosition 속성을 사용하세요.

Code Samples

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

-- 50초 지점부터 재생하도록 설정
Sound.StartTimePosition = 50
Sound:Play()

-- 재생 중에 다시 Play를 호출하면 50초부터 다시 시작
wait(5)  -- TimePosition은 55초쯤이지만
Sound:Play()  -- 50초부터 다시 재생됨

TimeLength

number

사운드의 길이를 초 단위로 나타냅니다. 사운드가 로드되지 않은 경우 이 값은 0입니다.

이 속성은 PlaybackSpeed와 함께 사용하여 사운드가 특정 시간 동안 재생되도록 속도를 조정하는 데 자주 사용됩니다.

Code Samples

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

print(Sound.TimeLength)

TimePosition

number

사운드의 현재 재생 위치를 초 단위로 나타냅니다. 이 값을 변경하여 재생 중에 사운드의 재생 위치를 즉시 이동할 수 있습니다.

사운드가 재생되는 동안 TimePosition은 초당 PlaybackSpeed 비율로 증가합니다. TimePosition이 TimeLength에 도달하면 Looped가 아닌 경우 사운드가 중지됩니다.

Resume() 메서드나 Playing = true는 현재 TimePosition부터 재생을 이어가며, Stop() 메서드를 호출하면 이 속성은 0으로 리셋됩니다. 반면 Play() 메서드는 StartTimePosition에서 재생을 시작합니다.

Code Samples

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

Sound.TimePosition = 0.9

Volume

number

사운드의 볼륨입니다. 0에서 10 사이의 값으로 설정할 수 있으며 기본값은 0.5입니다.

사운드가 SoundGroup의 멤버인 경우, 재생 볼륨은 그룹의 SoundGroup.Volume 속성의 영향을 받습니다(단, 이 속성 자체의 값은 변경되지 않습니다).

Code Samples

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

Sound.Volume = 0.5

Methods

Pause

사운드가 재생 중인 경우 재생을 일시 정지합니다.

Playing 속성을 false로 설정하지만 TimePosition은 리셋하지 않으므로, Resume() 메서드나 Playing = true로 현재 TimePosition 위치부터 재생을 재개할 수 있습니다.

Parameters

Return

void

Code Samples

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

Sound:Pause()

Play

사운드를 재생합니다. 재생 위치를 StartTimePosition에 설정된 값으로 이동한 후 Playing 속성을 true로 설정합니다.

Parameters

Return

void

Code Samples

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

Sound:Play()

Resume

사운드를 재개합니다. Playing 속성을 true로 설정하지만 TimePosition은 변경하지 않으므로, 현재 TimePosition 위치부터 재생을 이어갑니다.

Pause() 메서드로 일시 정지된 사운드를 중단된 위치부터 재생하는 데 사용됩니다.

Parameters

Return

void

Code Samples

Sound:Pause()
wait(2)

Sound:Resume()

Stop

사운드를 중지합니다. Playing 속성을 false로 설정하고 TimePosition과 StartTimePosition을 모두 0으로 리셋합니다.

Parameters

Return

void

Code Samples

Sound:Stop()

Events

Ended

사운드가 재생을 완료하고 중지될 때 발생합니다. 재생이 완료된 사운드를 파괴하는 등의 작업에 자주 사용됩니다.

참고: 이 이벤트는 Looped가 true로 설정된 사운드에서는 발생하지 않습니다(재생이 끝에 도달해도 계속 재생되므로).

또한 재생이 완료되기 전에 사운드가 중지된 경우에도 발생하지 않습니다. 이 경우에는 Stopped 이벤트를 사용하세요.

Parameters

string SoundId	재생이 종료된 사운드의 SoundId

Code Samples

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

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

Loaded

사운드가 로드될 때 발생합니다.

이 이벤트는 사운드가 로드되는 시점에만 발생하므로, 이 이벤트에 연결하기 전에 사운드의 IsLoaded 속성을 먼저 확인하는 것이 좋습니다.

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

Pause() 메서드를 사용하여 사운드가 일시 정지될 때마다 발생합니다.

Parameters

string SoundId	일시 정지된 사운드의 SoundId

Code Samples

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

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

Played

Play() 메서드를 사용하여 사운드가 재생될 때마다 발생합니다.

참고: PlayOnRemove가 true로 설정되어 사운드가 파괴될 때 재생되는 경우에는 이 이벤트가 발생하지 않습니다.

Parameters

string SoundId	재생된 사운드의 SoundId

Code Samples

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

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

Resumed

Resume() 메서드를 사용하여 사운드가 재개될 때 발생합니다.

Parameters

string SoundId	재개된 사운드의 SoundId

Code Samples

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

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

Stopped

Stop() 메서드를 통해 사운드가 중지될 때 발생합니다. 사운드가 재생 중일 때 파괴되는 경우에는 이 이벤트가 발생하지 않습니다.

Parameters

string SoundId	중지된 사운드의 SoundId

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