roblox-audio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox audio

Roblox 音频

Two systems coexist:

Audio API (modular, current):
```
AudioPlayer
```
→
```
Wire
```
→ (
```
AudioEmitter
```
…
```
AudioListener
```
) →
```
Wire
```
→
```
AudioDeviceOutput
```
, with effect objects inserted in the chain. Required for voice-chat processing, mixing graphs, analyzers, text-to-speech/speech-to-text.
Sound
(classic, still supported): one object, parented to a part for 3D or to
```
SoundService
```
/UI for 2D; routed through
```
SoundGroup
```
s with
```
SoundEffect
```
children. Fine for simple games and existing code.

Don't mix both for the same feature; follow what the project uses.

两套系统并存：

Audio API（模块化，当前系统）：
```
AudioPlayer
```
→
```
Wire
```
→ (
```
AudioEmitter
```
…
```
AudioListener
```
) →
```
Wire
```
→
```
AudioDeviceOutput
```
，并在链路中插入 effect 对象。语音聊天处理、混音图、分析器以及 text-to-speech/speech-to-text 都需要使用该系统。
Sound
（经典系统，仍受支持）：单个对象；进行 3D 播放时父级设为 part，进行 2D 播放时父级设为
```
SoundService
```
/UI；通过带有
```
SoundEffect
```
子对象的
```
SoundGroup
```
进行路由。适用于简单游戏和现有代码。

不要为同一功能混用这两套系统；应遵循项目所使用的系统。

2D audio (music, UI) with the Audio API

使用 Audio API 播放 2D 音频（音乐、UI）

luau

--!strict
-- Client: build a music player once.
local SoundService = game:GetService("SoundService")

local player = Instance.new("AudioPlayer")
player.Name = "Music"
player.Asset = "rbxassetid://1843463175" -- AudioPlayer.AssetId is deprecated; use Asset
player.Looping = true
player.Volume = 0.5
player.Parent = SoundService

local fader = Instance.new("AudioFader") -- one place to control music volume (settings menu)
fader.Name = "MusicVolume"
fader.Parent = SoundService

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

local function wire(source: Instance, target: Instance)
	local w = Instance.new("Wire")
	w.SourceInstance = source
	w.TargetInstance = target
	w.Parent = target
end

wire(player, fader)
wire(fader, output)
player:Play()

luau

--!strict
-- Client: build a music player once.
local SoundService = game:GetService("SoundService")

local player = Instance.new("AudioPlayer")
player.Name = "Music"
player.Asset = "rbxassetid://1843463175" -- AudioPlayer.AssetId is deprecated; use Asset
player.Looping = true
player.Volume = 0.5
player.Parent = SoundService

local fader = Instance.new("AudioFader") -- one place to control music volume (settings menu)
fader.Name = "MusicVolume"
fader.Parent = SoundService

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

local function wire(source: Instance, target: Instance)
	local w = Instance.new("Wire")
	w.SourceInstance = source
	w.TargetInstance = target
	w.Parent = target
end

wire(player, fader)
wire(fader, output)
player:Play()

3D audio with the Audio API

使用 Audio API 播放 3D 音频

Put an
```
AudioEmitter
```
on the sound's part/attachment; wire
```
AudioPlayer → AudioEmitter
```
.
Listening:
```
SoundService.ListenerLocation
```
controls the default
```
AudioListener
```
(camera or character); wire
```
AudioListener → AudioDeviceOutput
```
(done automatically in default setups).
Distance falloff and directionality are set on the emitter/listener (
```
AudioEmitter:SetDistanceAttenuation
```
, the
```
AudioInteractionGroup
```
string property on emitters and listeners scopes who hears what).

将
```
AudioEmitter
```
放在声音的 part/attachment 上；连接
```
AudioPlayer → AudioEmitter
```
。
监听：
```
SoundService.ListenerLocation
```
控制默认的
```
AudioListener
```
（摄像机或角色）；连接
```
AudioListener → AudioDeviceOutput
```
（默认配置会自动完成此操作）。
距离衰减和方向性在 emitter/listener 上设置（
```
AudioEmitter:SetDistanceAttenuation
```
）； emitter 和 listener 上的
```
AudioInteractionGroup
```
字符串属性用于限定谁能听到哪些声音。

Classic Sound quick reference

经典 Sound 快速参考

luau

--!strict
local SoundService = game:GetService("SoundService")

local sfxGroup = Instance.new("SoundGroup")
sfxGroup.Name = "SFX"
sfxGroup.Volume = 0.8
sfxGroup.Parent = SoundService

local function playAt(part: BasePart, soundId: string)
	local sound = Instance.new("Sound")
	sound.SoundId = soundId
	sound.SoundGroup = sfxGroup
	sound.RollOffMaxDistance = 80
	sound.Parent = part -- 3D: plays from the part; parent to SoundService/UI for 2D
	sound:Play()
	sound.Ended:Once(function()
		sound:Destroy()
	end)
end

return playAt

```
SoundService:PlayLocalSound(sound)
```
for client-only UI clicks.
Preload critical sounds:
```
ContentProvider:PreloadAsync({ sound })
```
(not everything — slows joins).
Pool frequently played sounds instead of creating one per shot.

luau

--!strict
local SoundService = game:GetService("SoundService")

local sfxGroup = Instance.new("SoundGroup")
sfxGroup.Name = "SFX"
sfxGroup.Volume = 0.8
sfxGroup.Parent = SoundService

local function playAt(part: BasePart, soundId: string)
	local sound = Instance.new("Sound")
	sound.SoundId = soundId
	sound.SoundGroup = sfxGroup
	sound.RollOffMaxDistance = 80
	sound.Parent = part -- 3D: plays from the part; parent to SoundService/UI for 2D
	sound:Play()
	sound.Ended:Once(function()
		sound:Destroy()
	end)
end

return playAt

```
SoundService:PlayLocalSound(sound)
```
用于仅在客户端播放的 UI 点击音效。
预加载关键声音：
```
ContentProvider:PreloadAsync({ sound })
```
（不要预加载所有声音——会拖慢玩家加入速度）。
对频繁播放的声音使用对象池，而不是每次触发都创建一个新对象。

Where to play

播放位置

Sounds started on the client are heard only by that client (UI, local feedback, music tracks the player chose). Sounds started on the server replicate to everyone (use sparingly; prefer a remote telling clients to play locally, which also lets each client apply its own volume settings).
With
```
SoundService.RespectFilteringEnabled = true
```
(default), client-played sounds don't replicate.
Streaming: a sound or emitter in a part that streams out stops. Keep ambient audio in persistent models or
```
SoundService
```
.

在客户端启动的声音只有该客户端能听到（UI、本地反馈、玩家选择的音乐曲目）。在服务端启动的声音会同步给所有玩家（应谨慎使用；更适合通过 Remote 通知客户端在本地播放，这样每个客户端还可以应用自己的音量设置）。
当
```
SoundService.RespectFilteringEnabled = true
```
时（默认值），客户端播放的声音不会同步。
Streaming：声音或 emitter 所在的 part 一旦被流出，播放就会停止。应将环境音频放在持久化 model 或
```
SoundService
```
中。

Assets and permissions

资产与权限

Use audio you own, uploaded to the same owner (user/group) as the experience, or Creator Store audio marked free-to-use. Private audio from other creators won't play unless shared with your experience (asset permissions). Check the Output for "failed to load" / permission errors.
Uploads are auto-classified as sound effects or songs; eligible songs can show on the game page.

使用你拥有且以与 experience 相同的 owner（user/group）身份上传的音频，或 Creator Store 中标记为可免费使用的音频。其他创作者的私有音频，除非已共享给你的 experience（资产权限），否则无法播放。检查
```
Output
```
中是否有“failed to load”/权限错误。
上传的音频会被自动分类为 sound effects 或 songs；符合条件的歌曲可以显示在游戏页面中。

Extras

附加功能

Effects:

AudioEqualizer

AudioCompressor

AudioReverb

AudioEcho

AudioChorus

AudioDistortion

AudioFlanger

AudioPitchShifter

AudioTremolo

AudioFilter

AudioLimiter

AudioAnalyzer

(read loudness/spectrum for visualizers).

```
AudioTextToSpeech
```
(artificial voices) and
```
AudioSpeechToText
```
(transcription).
Voice chat: each player's
```
AudioDeviceInput
```
can be wired through effects (radios, walkie-talkies, proximity) — see the voice chat docs; respect players' voice settings.
Give players separate Music/SFX volume sliders (faders or SoundGroups) and a mute option.

Effects：

AudioEqualizer

、

AudioCompressor

、

AudioReverb

、

AudioEcho

、

AudioChorus

、

AudioDistortion

、

AudioFlanger

、

AudioPitchShifter

、

AudioTremolo

、

AudioFilter

、

AudioLimiter

、

AudioAnalyzer

（读取响度/频谱以制作可视化效果）。

```
AudioTextToSpeech
```
（人工合成语音）和
```
AudioSpeechToText
```
（转录）。
语音聊天：每位玩家的
```
AudioDeviceInput
```
都可以通过 effects 进行连接（无线电、对讲机、邻近通信）——请参阅语音聊天文档，并尊重玩家的语音设置。
为玩家提供独立的 Music/SFX 音量滑块（faders 或 SoundGroups）以及静音选项。

roblox-audio

Original

Translation

Roblox audio

Roblox 音频

2D audio (music, UI) with the Audio API

使用 Audio API 播放 2D 音频（音乐、UI）

3D audio with the Audio API

使用 Audio API 播放 3D 音频

Classic Sound quick reference

经典 Sound 快速参考

Where to play

播放位置

Assets and permissions

资产与权限

Extras

附加功能

Related skills

相关 skill