Sound | 文档 - Roblox 创作者中心

local part = Instance.new("Part")
part.Anchored = true
part.Position = Vector3.new(0, 3, 0)
part.BrickColor = BrickColor.new("Bright red")
part.Name = "MusicBox"
part.Parent = workspace

-- 创建一个声音
local sound = Instance.new("Sound", part)
sound.SoundId = "rbxassetid://9120386436"
sound.EmitterSize = 5 -- 减小发射器大小（以便更早音量降低）
sound.Looped = true
sound.Parent = part

local clickDetector = Instance.new("ClickDetector")
clickDetector.Parent = part

-- 切换声音播放与停止
clickDetector.MouseClick:Connect(function()
	if not sound.IsPlaying then
		part.BrickColor = BrickColor.new("Bright green")
		sound:Play()
	else
		part.BrickColor = BrickColor.new("Bright red")
		sound:Stop()
	end
end)

API 参考

属性

AcousticSimulationEnabled

读取并联

功能： LegacySound

Sound.AcousticSimulationEnabled:boolean

AudioContent

隐藏

读取并联

功能： LegacySound

Sound.AudioContent:Content

EmitterSize

已弃用

IsLoaded

只读

未复制

读取并联

功能： LegacySound

Sound.IsLoaded:boolean

代码示例

加载声音

local sound = script.Parent.Sound

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

print("声音已加载！")

IsPaused

隐藏

只读

未复制

读取并联

功能： LegacySound

Sound.IsPaused:boolean

代码示例

声音正在播放和声音已暂停

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = workspace

if not sound.isLoaded then
	sound.Loaded:Wait()
end

sound:Play()
print(sound.IsPlaying, sound.IsPaused) -- true, false

task.wait(2)
sound:Pause()
print(sound.IsPlaying, sound.IsPaused) -- false, true

task.wait(2)
sound:Play()
print(sound.IsPlaying, sound.IsPaused) -- true, false

task.wait(2)
sound:Stop()
print(sound.IsPlaying, sound.IsPaused) -- false, true

IsPlaying

隐藏

只读

未复制

读取并联

功能： LegacySound

Sound.IsPlaying:boolean

代码示例

声音正在播放和声音已暂停

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = workspace

if not sound.isLoaded then
	sound.Loaded:Wait()
end

sound:Play()
print(sound.IsPlaying, sound.IsPaused) -- true, false

task.wait(2)
sound:Pause()
print(sound.IsPlaying, sound.IsPaused) -- false, true

task.wait(2)
sound:Play()
print(sound.IsPlaying, sound.IsPaused) -- true, false

task.wait(2)
sound:Stop()
print(sound.IsPlaying, sound.IsPaused) -- false, true

isPlaying

已弃用

Looped

读取并联

功能： LegacySound

Sound.Looped:boolean

代码示例

循环指定次数

local function loopNTimes(sound, numberOfLoops)
	if not sound.IsPlaying then
		sound.Looped = true
		local connection = nil
		connection = sound.DidLoop:Connect(function(_soundId, numOfTimesLooped)
			print(numOfTimesLooped)
			if numOfTimesLooped >= numberOfLoops then
				-- 断开连接
				connection:Disconnect()
				-- 停止声音
				sound:Stop()
			end
		end)
		sound:Play()
	end
end

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://0"

loopNTimes(sound, 5)

LoopRegion

读取并联

功能： LegacySound

Sound.LoopRegion:NumberRange

MaxDistance

已弃用

MinDistance

已弃用

Pitch

已弃用

PlaybackLoudness

只读

未复制

读取并联

功能： LegacySound

Sound.PlaybackLoudness:number

代码示例

音量振幅条

-- 应放置在 StarterPlayer > StarterPlayerScripts

local Players = game:GetService("Players")

-- 等待本地玩家 PlayerGui
local LocalPlayer = Players.LocalPlayer
local playerGui = LocalPlayer:WaitForChild("PlayerGui")

-- 创建一个 ScreenGui
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = playerGui

-- 创建我们的条的持有框
local frame = Instance.new("Frame")
frame.AnchorPoint = Vector2.new(0.5, 0.5)
frame.Position = UDim2.new(0.5, 0, 0.5, 0)
frame.Size = UDim2.new(0.3, 0, 0.05, 0)
frame.Parent = screenGui

-- 创建一个条
local bar = Instance.new("Frame")
bar.Position = UDim2.new(0, 0, 0, 0)
bar.Size = UDim2.new(1, 0, 1, 0)
bar.BackgroundColor3 = Color3.new(0, 1, 0)
bar.Parent = frame

-- 创建一个声音
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = screenGui
sound:Play()

-- 定义一个最大响度
local maxLoudness = 30

-- 动画振幅条
while true do
	local amplitude = math.clamp(sound.PlaybackLoudness / maxLoudness, 0, 1)
	bar.Size = UDim2.new(amplitude, 0, 1, 0)
	wait(0.05)
end

PlaybackRegion

读取并联

功能： LegacySound

Sound.PlaybackRegion:NumberRange

PlaybackRegionsEnabled

读取并联

功能： LegacySound

Sound.PlaybackRegionsEnabled:boolean

PlaybackSpeed

未复制

读取并联

功能： LegacySound

Sound.PlaybackSpeed:number

代码示例

声音播放速度

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = workspace

sound:Play()
task.wait(10)
sound.PlaybackSpeed = 3 -- 3倍快
task.wait(5)
sound.PlaybackSpeed = 0.5 -- 2倍慢
task.wait(5)
sound.PlaybackSpeed = 1 -- 默认

Playing

未复制

读取并联

功能： LegacySound

Sound.Playing:boolean

代码示例

声音播放

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = workspace

print("播放声音")
sound.Playing = true

task.wait(10)

print("停止声音")
sound.Playing = false

task.wait(5)

sound.Playing = true
local timePosition = sound.TimePosition
print("在时间位置恢复: " .. tostring(timePosition)) -- 大约 10 秒

PlayOnRemove

读取并联

功能： LegacySound

Sound.PlayOnRemove:boolean

RollOffMaxDistance

读取并联

功能： LegacySound

Sound.RollOffMaxDistance:number

RollOffMinDistance

读取并联

功能： LegacySound

Sound.RollOffMinDistance:number

RollOffMode

读取并联

功能： LegacySound

Sound.RollOffMode:Enum.RollOffMode

SoundGroup

读取并联

功能： LegacySound

Sound.SoundGroup:SoundGroup

SoundId

读取并联

功能： LegacySound

Sound.SoundId:ContentId

TimeLength

只读

未复制

读取并联

功能： LegacySound

Sound.TimeLength:number

代码示例

播放特定时长的声音

local function playForDuration(sound, duration)
	if not sound.IsLoaded then
		sound.Loaded:wait()
	end
	local speed = sound.TimeLength / duration
	sound.PlaybackSpeed = speed
	sound:Play()
end

local sound = script.Parent
playForDuration(sound, 5)

TimePosition

未复制

读取并联

功能： LegacySound

Sound.TimePosition:number

代码示例

声音时间位置

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Parent = workspace

sound.TimePosition = 30

sound:Play()

task.wait(5)

sound.TimePosition = 100

task.wait(5)

sound.TimePosition = 0

Volume

读取并联

功能： LegacySound

Sound.Volume:number

方法

Pause

功能： LegacySound

Sound:Pause():()

()

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

pause

已弃用

Play

功能： LegacySound

Sound:Play():()

()

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

play

已弃用

Resume

功能： LegacySound

Sound:Resume():()

()

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

Stop

功能： LegacySound

Sound:Stop():()

()

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

stop

已弃用

活动

DidLoop

功能： LegacySound

Sound.DidLoop(

soundId:string, numOfTimesLooped:number

):RBXScriptSignal

参数

soundId:string

numOfTimesLooped:number

代码示例

循环指定次数

local function loopNTimes(sound, numberOfLoops)
	if not sound.IsPlaying then
		sound.Looped = true
		local connection = nil
		connection = sound.DidLoop:Connect(function(_soundId, numOfTimesLooped)
			print(numOfTimesLooped)
			if numOfTimesLooped >= numberOfLoops then
				-- 断开连接
				connection:Disconnect()
				-- 停止声音
				sound:Stop()
			end
		end)
		sound:Play()
	end
end

local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://0"

loopNTimes(sound, 5)

Ended

功能： LegacySound

Sound.Ended(soundId:string):RBXScriptSignal

参数

soundId:string

Loaded

功能： LegacySound

Sound.Loaded(soundId:string):RBXScriptSignal

参数

soundId:string

代码示例

加载声音

local sound = script.Parent.Sound

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

print("声音已加载！")

Paused

功能： LegacySound

Sound.Paused(soundId:string):RBXScriptSignal

参数

soundId:string

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

Played

功能： LegacySound

Sound.Played(soundId:string):RBXScriptSignal

参数

soundId:string

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

Resumed

功能： LegacySound

Sound.Resumed(soundId:string):RBXScriptSignal

参数

soundId:string

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

Stopped

功能： LegacySound

Sound.Stopped(soundId:string):RBXScriptSignal

参数

soundId:string

代码示例

声音函数

-- 创建声音
local sound = Instance.new("Sound", game.Workspace)
sound.SoundId = "rbxassetid://9120386436"

if not sound.IsLoaded then
	sound.Loaded:Wait()
end

-- 监听事件
sound.Played:Connect(function(_soundId)
	print("Sound.Played 事件")
end)

sound.Paused:Connect(function(_soundId)
	print("Sound.Paused 事件")
end)

sound.Resumed:Connect(function(_soundId)
	print("Sound.Resumed 事件")
end)

sound.Stopped:Connect(function(_soundId)
	print("Sound.Stopped 事件")
end)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0

task.wait(10)

sound:Pause()
print("暂停", sound.Playing, sound.TimePosition) -- pause false 10

task.wait(3)

sound:Resume()
print("播放", sound.Playing, sound.TimePosition) -- play true 10

task.wait(3)

sound:Stop()
print("停止", sound.Playing, sound.TimePosition) -- stop false 0

task.wait(3)

sound:Play()
print("播放", sound.Playing, sound.TimePosition) -- play true 0