roblox-audio

Roblox 音频

有两套系统并存：

• Audio API（模块化的当前方案）：AudioPlayer → Wire →（AudioEmitter … AudioListener）→ Wire → AudioDeviceOutput，可在链路中插入效果对象。语音聊天处理、混音图、分析器、文本转语音/语音转文本都需要使用此方案。
• Sound（经典方案，仍受支持）：单个对象，设为部件的子对象即可用于 3D 音频，设为 SoundService/UI 的子对象即可用于 2D 音频； 通过带有 SoundEffect 子对象的 SoundGroup 进行路由。适用于简单游戏和现有代码。

不要在同一项功能中混用两种方案；请遵循项目当前使用的方案。

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

--!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()

使用 Audio API 播放 3D 音频

• 在声音所在的部件/附件上放置 AudioEmitter；连接 AudioPlayer → AudioEmitter。
• 监听：SoundService.ListenerLocation 控制默认的 AudioListener（摄像机或角色）； 连接 AudioListener → AudioDeviceOutput（默认配置会自动完成）。
• 距离衰减和方向性由发射器/监听器设置（AudioEmitter:SetDistanceAttenuation； 发射器和监听器上的 AudioInteractionGroup 字符串属性用于限定谁能听到什么）。
• 声学模拟（已全面发布；目前仅支持 Audio API，尚不支持 Sound）：在 Studio 中设置 SoundService.AcousticSimulationEnabled = true，3D 音频就会被墙壁削弱、绕过拐角，并在房间中产生混响。对于每个部件：BasePart.AudioCanCollide（false = 不阻挡声音）；部件越厚、密度越大，声音削弱越明显。对于每个发射器/监听器：设置 AcousticSimulationEnabled。设置 SoundService.CharacterSoundsUseNewApi，角色声音也会进行模拟。性能较弱的设备会降低音质。

经典 Sound 快速参考

--!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 })（不要预加载所有声音，否则会拖慢玩家加入游戏的速度）。
• 将频繁播放的声音放入对象池，而不是每次播放都创建一个。

播放位置

• 在客户端启动的声音只有该客户端能听到（UI、本地反馈、玩家选择的音乐曲目）。在服务器启动的声音会复制给所有人（请谨慎使用；更推荐通过远程调用通知客户端在本地播放，这样每个客户端也能应用自己的音量设置）。
• 当 SoundService.RespectFilteringEnabled = true（默认值）时，客户端播放的声音不会复制。
• 流式加载：部件流出时，该部件中的声音或发射器会停止工作。请将环境音频放在持久模型或 SoundService 中。

资源和权限

• 使用你拥有的音频、上传至与体验相同所有者（用户/群组）的音频，或 Creator Store 中标记为可免费使用的音频。除非与体验共享（资源权限），否则其他创作者的私有音频无法播放。检查 Output 中是否有“failed to load”或权限错误。
• 上传的音频会自动分类为音效或歌曲；符合条件的歌曲可能会显示在游戏页面上。

附加内容

• 效果：AudioEqualizer、AudioCompressor、AudioReverb、AudioEcho、AudioChorus、AudioDistortion、 AudioFlanger、AudioPitchShifter、AudioTremolo、AudioFilter、AudioLimiter、AudioAnalyzer（读取响度/频谱以制作可视化效果）。
• AudioTextToSpeech（人工语音）和 AudioSpeechToText（转录）。AudioTextToSpeech.AutoLocalize （默认值为 true）会将文本翻译成每位玩家使用的语言（11 种语言），并选择匹配的语音；对于必须保持原样的文本（名称、口号），请将其设为 false。上传的 TTS 资源不会翻译。
• 语音聊天：每位玩家的 AudioDeviceInput 都可以通过效果对象连接（收音机、对讲机、近距离语音）——请参阅语音聊天文档；尊重玩家的语音设置。
• 为玩家提供单独的音乐/音效音量滑块（推子或 SoundGroup）和静音选项。

相关技能

roblox-ui（设置菜单）、roblox-architecture（客户端与服务器）、roblox-performance（音频内存）。