Back to Details

roblox-audio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Roblox Audio

Roblox 音频系统

Roblox has two audio systems. The legacy system uses 
Sound
, 
SoundGroup
, and 
SoundEffect
objects. The new modular system uses 
AudioPlayer
, 
AudioEmitter
, 
AudioListener
, 
Wire
, and 
AudioDeviceOutput
. The new system is preferred for new projects but the legacy system still works and is simpler for basic use cases.
Roblox拥有两套音频系统：传统系统使用
Sound
、
SoundGroup
和
SoundEffect
对象；新型模块化系统则采用
AudioPlayer
、
AudioEmitter
、
AudioListener
、
Wire
和
AudioDeviceOutput
。新项目优先推荐使用新型系统，但传统系统仍可正常运行，且在基础场景下更简便。

Legacy System (Sound Objects)

传统系统（Sound对象）

Where to Place Sounds

音效放置位置

LocationBehaviorUse for
Child of block/sphere/cylinder BasePartVolumetric: emits from entire surface, volume changes with distance AND part sizeAmbient zones, large area sounds
Child of Attachment, MeshPart, TrussPart, WedgePartPoint source: emits from single point, volume changes with distanceFootsteps, impacts, small objects
Within SoundService or WorkspaceGlobal: same volume everywhere regardless of positionBackground music, UI sounds
位置行为适用场景
作为BasePart（方块/球体/圆柱体）的子对象体积声源：从整个表面发声，音量随距离和部件大小变化环境区域音效、大范围场景音效
作为Attachment、MeshPart、TrussPart、WedgePart的子对象点声源：从单点发声，音量随距离变化脚步声、碰撞声、小型物体音效
位于SoundService或Workspace中全局声源：音量不随位置变化，全场一致背景音乐、UI音效

Basic Playback

基础播放示例

luau
-- Background music (global, in SoundService)
local SoundService = game:GetService("SoundService")
local bgMusic = Instance.new("Sound")
bgMusic.Name = "BackgroundMusic"
bgMusic.SoundId = "rbxassetid://1843463175"
bgMusic.Looped = true
bgMusic.Volume = 0.25
bgMusic.Parent = SoundService
bgMusic:Play()
luau
-- Positional sound (3D, on a part)
local waterfall = Instance.new("Sound")
waterfall.SoundId = "rbxassetid://ASSET_ID"
waterfall.Looped = true
waterfall.Volume = 0.5
waterfall.RollOffMode = Enum.RollOffMode.InverseTapered
waterfall.RollOffMinDistance = 10  -- full volume within this range
waterfall.RollOffMaxDistance = 100 -- silent beyond this range
waterfall.Parent = workspace.WaterfallPart
waterfall:Play()
luau
-- 背景音乐（全局声源，置于SoundService）
local SoundService = game:GetService("SoundService")
local bgMusic = Instance.new("Sound")
bgMusic.Name = "BackgroundMusic"
bgMusic.SoundId = "rbxassetid://1843463175"
bgMusic.Looped = true
bgMusic.Volume = 0.25
bgMusic.Parent = SoundService
bgMusic:Play()
luau
-- 3D定位音效（挂载在部件上）
local waterfall = Instance.new("Sound")
waterfall.SoundId = "rbxassetid://ASSET_ID"
waterfall.Looped = true
waterfall.Volume = 0.5
waterfall.RollOffMode = Enum.RollOffMode.InverseTapered
waterfall.RollOffMinDistance = 10  -- 此范围内保持最大音量
waterfall.RollOffMaxDistance = 100 -- 超出此范围音量降至0
waterfall.Parent = workspace.WaterfallPart
waterfall:Play()

RollOff Modes

音量衰减模式

ModeBehavior
Inverse
Realistic falloff (1/distance). Drops quickly near source, slowly far away.
Linear
Linear falloff between min and max distance.
InverseTapered
Inverse near the source, tapers to silence at max. Most natural for games.
LinearSquare
Attempt at realistic with linear square curve.
  • RollOffMinDistance
    : distance (studs) where volume starts decreasing. Default 10.
  • RollOffMaxDistance
    : distance where volume reaches zero. Default 10000 (effectively infinite).
模式行为
Inverse
真实物理衰减（1/距离）：声源附近音量快速下降，远距离下降缓慢
Linear
最小与最大距离间线性衰减
InverseTapered
声源附近为逆衰减，在最大距离处渐变为静音，是游戏中最自然的模式
LinearSquare
模拟真实物理的线性平方曲线衰减
  • RollOffMinDistance
    ：音量开始衰减的距离（单位： studs），默认值10
  • RollOffMaxDistance
    ：音量降至0的距离，默认值10000（几乎无限制）

SoundGroups (Audio Mixer)

SoundGroups（音频混音器）

SoundGroups let you control volume of multiple sounds at once. Nest them for a mix tree.
luau
-- Create mix hierarchy in SoundService
local master = Instance.new("SoundGroup")
master.Name = "Master"
master.Volume = 1
master.Parent = SoundService

local music = Instance.new("SoundGroup")
music.Name = "Music"
music.Volume = 0.5
music.Parent = master  -- nested under Master

local sfx = Instance.new("SoundGroup")
sfx.Name = "SFX"
sfx.Volume = 0.8
sfx.Parent = master

-- Assign a sound to a group
bgMusic.SoundGroup = music
Adjusting 
master.Volume
affects ALL nested groups. Players can control Music vs SFX independently.
SoundGroups可同时控制多个音效的音量，还可嵌套形成混音层级。
luau
-- 在SoundService中创建混音层级
local master = Instance.new("SoundGroup")
master.Name = "Master"
master.Volume = 1
master.Parent = SoundService

local music = Instance.new("SoundGroup")
music.Name = "Music"
music.Volume = 0.5
music.Parent = master  -- 嵌套在Master组下

local sfx = Instance.new("SoundGroup")
sfx.Name = "SFX"
sfx.Volume = 0.8
sfx.Parent = master

-- 将音效分配到对应组
bgMusic.SoundGroup = music
调整
master.Volume
会影响所有嵌套组的音量，玩家可独立控制音乐与音效的音量。

Dynamic Effects

动态音效效果

Parent these to a Sound or SoundGroup to modify audio:
EffectWhat it doesUse for
ReverbSoundEffect
Simulates room reflectionsCaves, large halls, bathrooms
EqualizerSoundEffect
Control volume of frequency bandsMuffled underwater, radio effect
CompressorSoundEffect
Reduces dynamic rangeConsistent volume, ducking
ChorusSoundEffect
Thickens sound with copiesEthereal voices, dream sequences
DistortionSoundEffect
Adds distortion/overdriveDamaged radio, horror
FlangeSoundEffect
Sweeping comb filterSci-fi, psychedelic
PitchShiftSoundEffect
Changes pitch without speedChipmunk voice, deep voice
TremoloSoundEffect
Periodic volume modulationVibrato, pulsing
luau
-- Add reverb to all sounds in a cave zone
local caveGroup = Instance.new("SoundGroup")
caveGroup.Name = "Cave"
caveGroup.Parent = master

local reverb = Instance.new("ReverbSoundEffect")
reverb.DecayTime = 3.0
reverb.Density = 1.0
reverb.Diffusion = 1.0
reverb.WetLevel = -6  -- dB, how much reverb vs dry signal
reverb.Parent = caveGroup
将以下效果挂载到Sound或SoundGroup上可修改音频：
效果功能适用场景
ReverbSoundEffect
模拟房间反射效果洞穴、大厅、浴室
EqualizerSoundEffect
控制不同频段音量水下模糊音效、收音机效果
CompressorSoundEffect
压缩动态范围保持音量一致、音效闪避
ChorusSoundEffect
通过复制音频增厚音效空灵人声、梦境场景
DistortionSoundEffect
添加失真/过载效果损坏的收音机、恐怖场景
FlangeSoundEffect
扫频梳状滤波效果科幻、迷幻场景
PitchShiftSoundEffect
不改变速度的前提下调整音调花栗鼠音、低沉嗓音
TremoloSoundEffect
周期性音量调制颤音、脉冲音效
luau
-- 为洞穴区域的所有音效添加混响
local caveGroup = Instance.new("SoundGroup")
caveGroup.Name = "Cave"
caveGroup.Parent = master

local reverb = Instance.new("ReverbSoundEffect")
reverb.DecayTime = 3.0
reverb.Density = 1.0
reverb.Diffusion = 1.0
reverb.WetLevel = -6  -- 混响信号与干信号的比例（单位：dB）
reverb.Parent = caveGroup

Ducking (Lower music when SFX plays)

音效闪避（播放音效时降低音乐音量）

Use CompressorSoundEffect with a SideChain:
luau
-- Music ducks when SFX plays
local compressor = Instance.new("CompressorSoundEffect")
compressor.Threshold = -20
compressor.Ratio = 4
compressor.Attack = 0.01
compressor.Release = 0.2
compressor.SideChain = sfx  -- SFX group triggers the compression
compressor.Parent = music   -- Music group gets compressed
使用带侧链的CompressorSoundEffect实现：
luau
-- 播放音效时自动降低音乐音量
local compressor = Instance.new("CompressorSoundEffect")
compressor.Threshold = -20
compressor.Ratio = 4
compressor.Attack = 0.01
compressor.Release = 0.2
compressor.SideChain = sfx  -- 以SFX组作为触发源
compressor.Parent = music   -- 对Music组应用压缩

New Modular System (Audio Objects)

新型模块化系统（Audio对象）

The new system uses explicit wiring between audio components. Each object maps to a real-world audio device:
ObjectReal-world equivalentRole
AudioPlayer
Media player / turntableProduces audio from an asset
AudioEmitter
Speaker in 3D spaceEmits audio positionally
AudioListener
MicrophonePicks up audio from 3D space
AudioDeviceOutput
Headphones/speakersPlays to the real player
AudioDeviceInput
Physical microphoneCaptures real player voice
Wire
Audio cableCarries stream between objects
AudioTextToSpeech
TTS engineConverts text to speech
AudioEqualizer
EQ pedalModifies frequency response
AudioCompressor
Compressor pedalControls dynamic range
AudioReverb
Reverb unitAdds room reflections
新型系统通过显式连接音频组件实现功能，每个对象对应现实中的音频设备：
对象现实设备对应角色
AudioPlayer
媒体播放器/唱片机从资源生成音频
AudioEmitter
3D空间扬声器播放定位音频
AudioListener
麦克风拾取3D空间音频
AudioDeviceOutput
耳机/扬声器向玩家输出音频
AudioDeviceInput
物理麦克风采集玩家语音
Wire
音频线缆在对象间传输音频流
AudioTextToSpeech
TTS引擎将文本转换为语音
AudioEqualizer
EQ效果器调整频率响应
AudioCompressor
压缩效果器控制动态范围
AudioReverb
混响器添加房间反射效果

2D Audio (non-positional)

2D音频（非定位）

AudioPlayer → Wire → AudioDeviceOutput
luau
-- In SoundService:
local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://MUSIC_ID"
player.Looping = true
player.Volume = 0.5
player.Parent = SoundService

local output = Instance.new("AudioDeviceOutput")
output.Parent = SoundService

local wire = Instance.new("Wire")
wire.SourceInstance = player
wire.TargetInstance = output
wire.Parent = SoundService

player:Play()
AudioPlayer → Wire → AudioDeviceOutput
luau
-- 在SoundService中创建：
local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://MUSIC_ID"
player.Looping = true
player.Volume = 0.5
player.Parent = SoundService

local output = Instance.new("AudioDeviceOutput")
output.Parent = SoundService

local wire = Instance.new("Wire")
wire.SourceInstance = player
wire.TargetInstance = output
wire.Parent = SoundService

player:Play()

3D Audio (positional)

3D音频（定位）

AudioPlayer → Wire → AudioEmitter (on Part)
AudioListener (on Camera/Character) → Wire → AudioDeviceOutput
luau
-- On the part that emits sound:
local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://SFX_ID"
player.Parent = workspace.CampfirePart

local emitter = Instance.new("AudioEmitter")
emitter.Parent = workspace.CampfirePart

local wire = Instance.new("Wire")
wire.SourceInstance = player
wire.TargetInstance = emitter
wire.Parent = workspace.CampfirePart

-- AudioListener is auto-created by SoundService.ListenerLocation setting
-- AudioDeviceOutput is auto-created when ListenerLocation is Character or Camera

player:Play()
AudioEmitter.DistanceAttenuation
controls the volume-over-distance curve.
AudioPlayer → Wire → AudioEmitter（挂载在部件上）
AudioListener（挂载在相机/角色上） → Wire → AudioDeviceOutput
luau
-- 在发声部件上创建：
local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://SFX_ID"
player.Parent = workspace.CampfirePart

local emitter = Instance.new("AudioEmitter")
emitter.Parent = workspace.CampfirePart

local wire = Instance.new("Wire")
wire.SourceInstance = player
wire.TargetInstance = emitter
wire.Parent = workspace.CampfirePart

-- AudioListener由SoundService.ListenerLocation设置自动创建
-- 当ListenerLocation设为Character或Camera时，AudioDeviceOutput会自动创建

player:Play()
AudioEmitter.DistanceAttenuation
用于控制音量随距离变化的曲线。

Triggering Audio from Scripts

通过脚本触发音频

luau
-- Basic trigger pattern
local audioPlayer = script.Parent -- AudioPlayer
local part = audioPlayer.Parent

part.Touched:Connect(function(hit)
    if hit.Parent:FindFirstChildOfClass("Humanoid") then
        audioPlayer:Play()
    end
end)
luau
-- 基础触发模式
local audioPlayer = script.Parent -- AudioPlayer对象
local part = audioPlayer.Parent

part.Touched:Connect(function(hit)
    if hit.Parent:FindFirstChildOfClass("Humanoid") then
        audioPlayer:Play()
    end
end)

Patterns

实用模式

Preloading Critical Audio

预加载关键音频

luau
local ContentProvider = game:GetService("ContentProvider")

local criticalSounds = {
    Instance.new("Sound"), -- temp instances for preloading
    Instance.new("Sound"),
}
criticalSounds[1].SoundId = "rbxassetid://HIT_SOUND"
criticalSounds[2].SoundId = "rbxassetid://JUMP_SOUND"

ContentProvider:PreloadAsync(criticalSounds)
-- Now these assets are cached and play instantly
luau
local ContentProvider = game:GetService("ContentProvider")

local criticalSounds = {
    Instance.new("Sound"), -- 用于预加载的临时对象
    Instance.new("Sound"),
}
criticalSounds[1].SoundId = "rbxassetid://HIT_SOUND"
criticalSounds[2].SoundId = "rbxassetid://JUMP_SOUND"

ContentProvider:PreloadAsync(criticalSounds)
-- 现在这些资源已缓存，可立即播放

One-Shot SFX (auto-cleanup)

一次性音效（自动清理）

luau
local function playSFX(parent: BasePart, soundId: string)
    local sound = Instance.new("Sound")
    sound.SoundId = soundId
    sound.RollOffMode = Enum.RollOffMode.InverseTapered
    sound.RollOffMinDistance = 10
    sound.RollOffMaxDistance = 80
    sound.Parent = parent
    sound:Play()
    sound.Ended:Once(function()
        sound:Destroy()
    end)
end
luau
local function playSFX(parent: BasePart, soundId: string)
    local sound = Instance.new("Sound")
    sound.SoundId = soundId
    sound.RollOffMode = Enum.RollOffMode.InverseTapered
    sound.RollOffMinDistance = 10
    sound.RollOffMaxDistance = 80
    sound.Parent = parent
    sound:Play()
    sound.Ended:Once(function()
        sound:Destroy()
    end)
end

Client-Side Playback

客户端播放

Play sounds on the client for zero-latency feedback. Server tells client WHAT to play:
luau
-- Server
SFXRemote:FireClient(player, "hit", workspace.Enemy.HumanoidRootPart.Position)

-- Client
SFXRemote.OnClientEvent:Connect(function(sfxName: string, position: Vector3)
    local part = Instance.new("Part")
    part.Position = position
    part.Anchored = true
    part.Transparency = 1
    part.CanCollide = false
    part.Parent = workspace
    playSFX(part, SFX_IDS[sfxName])
    task.delay(3, function() part:Destroy() end)
end)
在客户端播放音效可实现零延迟反馈，服务器仅告知客户端需要播放的内容：
luau
-- 服务器端
SFXRemote:FireClient(player, "hit", workspace.Enemy.HumanoidRootPart.Position)

-- 客户端
SFXRemote.OnClientEvent:Connect(function(sfxName: string, position: Vector3)
    local part = Instance.new("Part")
    part.Position = position
    part.Anchored = true
    part.Transparency = 1
    part.CanCollide = false
    part.Parent = workspace
    playSFX(part, SFX_IDS[sfxName])
    task.delay(3, function() part:Destroy() end)
end)

Common Mistakes

常见错误

  • Playing sounds on the server for feedback: Server sounds have network latency. Play on client for responsive SFX. Server only for sounds ALL players must hear identically.
  • No RollOff configuration: Default RollOffMaxDistance is 10000 studs (basically infinite). Set it explicitly or sounds bleed across the entire map.
  • Stacking rapid sounds: Playing the same sound 10x in 0.1s creates ear-splitting overlap. Check 
    sound.IsPlaying
    or use a cooldown.
  • Forgetting Looped = false on one-shots: Default is false, but if you clone from a template that has Looped = true, your SFX plays forever.
  • Not destroying one-shot sounds: Sounds parented to destroyed parts get GC'd, but sounds in SoundService accumulate. Always Destroy() after Ended.
  • Volume > 1: Causes clipping/distortion. Keep ≤ 1. Use SoundGroup volume for amplification.
  • Using legacy system for voice chat integration: The new AudioPlayer/Wire system is required for voice chat features (AudioDeviceInput, AudioSpeechToText).
  • No SoundGroup hierarchy: Without groups, players can't independently control music vs SFX volume in settings.
  • 在服务器播放反馈类音效：服务器音效存在网络延迟，应在客户端播放以获得响应迅速的音效，仅在所有玩家需听到完全一致的音效时使用服务器播放。
  • 未配置RollOff参数：默认RollOffMaxDistance为10000 studs（几乎无限制），需显式设置，否则音效会传遍整个地图。
  • 快速重复播放同一音效：0.1秒内播放10次同一音效会产生刺耳的重叠，应检查
    sound.IsPlaying
    或使用冷却机制。
  • 一次性音效未关闭Looped：默认Looped为false，但如果从设置了Looped=true的模板克隆音效，会导致音效无限播放。
  • 未销毁一次性音效：挂载在已销毁部件上的音效会被垃圾回收，但位于SoundService中的音效会不断累积，播放结束后务必调用Destroy()。
  • 音量设置>1：会导致音频削波/失真，音量应保持≤1，可通过SoundGroup的音量实现放大。
  • 使用传统系统集成语音聊天：语音聊天功能（AudioDeviceInput、AudioSpeechToText）需使用新型AudioPlayer/Wire系统。
  • 未创建SoundGroup层级：没有分组的话，玩家无法在设置中独立控制音乐与音效的音量。