---
name: roblox-audio
description: "Build or debug Roblox music, spatial audio, effects, text-to-speech, and speech-to-text. Use for audio graphs, asset permissions, playback problems, or migration from Sound."
last_reviewed: 2026-08-18
---

# roblox-audio

**Official sources:**
- https://create.roblox.com/docs/en-us/audio/objects (audio graph overview)
- https://create.roblox.com/docs/en-us/audio/effects (audio effects)
- https://create.roblox.com/docs/en-us/reference/engine/classes/Sound (legacy `Sound`)
- https://create.roblox.com/docs/en-us/reference/engine/classes/SoundService
- Engine classes: `AudioPlayer`, `AudioEmitter`, `AudioListener`, `AudioDeviceOutput`, `AudioDeviceInput`, `AudioTextToSpeech`, `AudioSpeechToText`, `Wire`, `AudioEqualizer`, `AudioCompressor`, `AudioReverb`, `AudioChorus`, `AudioDistortion`, `AudioEcho`, `AudioFlanger`, `AudioPitchShifter`, `AudioTremolo`, `AudioFader`, `AudioAnalyzer`
- Full reference: https://create.roblox.com/docs/en-us/reference/engine

Roblox recommends audio objects over `Sound`, `SoundGroup`, and `SoundEffect`. New work should use the graph; legacy code can keep using `Sound` where the graph offers no advantage.

Cross-reference:
- [roblox-core/SKILL.md](../roblox-core/SKILL.md) for services and script locations.
- [roblox-animation/SKILL.md](../roblox-animation/SKILL.md) for driving audio from animation markers (footsteps, impact sounds).
- [roblox-user-interfaces/SKILL.md](../roblox-user-interfaces/SKILL.md) for UI-triggered sound feedback.
- [roblox-networking/SKILL.md](../roblox-networking/SKILL.md) for client-authoritative cosmetic audio vs server-authoritative gameplay audio.

## The two systems

### Modern audio graph (recommended for new work)

Modular instances that mirror real-world audio devices. Each object **produces**, **consumes**, **modifies**, or **carries** an audio stream. You wire them together with `Wire` instances (`SourceInstance` → `TargetInstance`).

| Object | Role | Real-world analog |
| --- | --- | --- |
| `AudioPlayer` | Produces a stream from an audio asset ID | A audio file player |
| `AudioEmitter` | Emits a stream into the 3D environment (parent position = emission point) | A speaker in the world |
| `AudioListener` | Picks up streams from the environment (parent = camera or character) | A microphone in the world |
| `AudioDeviceOutput` | Plays a stream to the player's physical speaker/headphones | The player's hardware output |
| `AudioDeviceInput` | Captures audio from the player's physical microphone | The player's hardware mic |
| `AudioTextToSpeech` | Converts text to audio with an artificial voice | A TTS engine |
| `AudioSpeechToText` | Converts spoken audio to text | A transcription engine |
| `Wire` | Carries a stream from `SourceInstance` to `TargetInstance` | An audio cable |

Effects (all "modify" category): `AudioEqualizer`, `AudioCompressor`, `AudioReverb`, `AudioChorus`, `AudioDistortion`, `AudioEcho`, `AudioFlanger`, `AudioPitchShifter`, `AudioTremolo`, `AudioFader`, `AudioAnalyzer`. See [references/audio-effects.md](references/audio-effects.md).

### Legacy `Sound` system (still works, discouraged)

`Sound` parented to a `BasePart` or `Attachment` emits from that position with built-in Doppler and distance rolloff (`RollOffMode`, `RollOffMaxDistance`, `RollOffMinDistance`, `EmitterSize`). A "global" `Sound` (not parented to a part/attachment) plays at constant volume everywhere. `SoundGroup` controls group volume and effects; `SoundEffect` subclasses (`EqualizerSoundEffect`, `ReverbSoundEffect`, etc.) apply per-group effects. `SoundService` exposes global properties (`AmbientReverb`, `DistanceFactor`, `DopplerScale`, `RespectFilteringEnabled`) that affect `Sound` playback.

`SoundService.AmbientReverb` and the Doppler/distance properties affect **only legacy `Sound`**, not the audio graph. The graph has its own effect objects and per-emitter `DistanceAttenuation` curves.

## Decision tree: which system?

- **New experience, greenfield audio** → audio graph. It supports TTS, STT, acoustic simulation, and routing.
- **Simple 2D SFX or music with no routing/effects** → `Sound` is acceptable and simpler. Don't rewrite working legacy code just to migrate.
- **3D positional audio with custom attenuation curves** → audio graph (`AudioEmitter.DistanceAttenuation`).
- **Multiple sources through one effect (e.g. all gunfire through one compressor)** → audio graph (one effect, many players wired in).
- **Text-to-speech or speech-to-text** → audio graph (only the graph has `AudioTextToSpeech` / `AudioSpeechToText`).
- **Voice chat / spatial voice** → `VoiceChatService` (separate from in-experience audio; uses `AudioDeviceInput` under the hood when `UseAudioApi` is enabled).
- **Acoustic simulation (occlusion, diffraction, reverb)** → audio graph with `SoundService.AcousticSimulationEnabled = true` and per-instance `AcousticSimulationEnabled` on emitters/listeners.
- **Quick prototype / one-shot UI click sound** → `Sound` is fine.

See [references/audio-graph-vs-sound.md](references/audio-graph-vs-sound.md) for a side-by-side property map and migration notes.

## 2D audio (non-directional)

Same volume everywhere. Requires: `AudioPlayer` → `Wire` → `AudioDeviceOutput`, all parented under `SoundService`.

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

local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://YOUR_AUDIO_ID"
player.Looping = true
player.Volume = 1
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)

Volume changes with the listener's distance to the emitter. Requires six objects: `AudioPlayer` → `Wire` → `AudioEmitter` (parented to the 3D part), and `AudioListener` → `Wire` → `AudioDeviceOutput` (under `SoundService`). Set `SoundService.ListenerLocation` to `Character` or `Camera` (the engine auto-creates the `AudioDeviceOutput` under `SoundService` at runtime when you do).

```lua
--!strict
local SoundService = game:GetService("SoundService")
SoundService.ListenerLocation = Enum.ListenerLocation.Camera -- or Character

-- On the 3D part that should emit audio:
local part = workspace:WaitForChild("NoisyPart")
local player = Instance.new("AudioPlayer")
player.AssetId = "rbxassetid://YOUR_AUDIO_ID"
player.Looping = true
player.Parent = part

local emitter = Instance.new("AudioEmitter")
-- Custom curve: DistanceAttenuation is a NumberSequence (x = distance studs, y = volume 0..1).
-- This curve is only used when DistanceAttenuationMode == Custom (the default).
emitter.DistanceAttenuation = NumberSequence.new({
    NumberSequenceKeypoint.new(0, 1),    -- full volume at 0 studs
    NumberSequenceKeypoint.new(50, 0.5), -- half volume at 50 studs
    NumberSequenceKeypoint.new(70, 0),   -- silent at 70 studs
})
-- Preset alternative (no custom curve needed):
-- emitter.DistanceAttenuationMode = Enum.DistanceAttenuationMode.Inverse
-- emitter.DistanceAttenuationBounds = NumberRange.new(4, 10000) -- [min,max] for the preset rolloff
emitter.Parent = part

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

player:Play()
```

The emitter's **parent position** determines where audio emits from. `AudioEmitter` ignores its own orientation; rotate the parent part/attachment to steer emission.

**Distance model:** `AudioEmitter.DistanceAttenuationMode` selects the rolloff formula (`Custom` by default; uses your `DistanceAttenuation` curve; other presets use `DistanceAttenuationBounds` which defaults to `[4, 10000]` and ignore the custom curve). `GetDistanceAttenuation()` always returns the custom curve even when a preset is active. Don't assume it reflects the audible rolloff unless `Mode == Custom`. `SetDistanceAttenuation(curve)` only affects playback when `Mode == Custom`. Angle attenuation is set via `SetAngleAttenuation({[angle]=volume})` (0–180° → 0–1); use for directional sources (e.g. avatar voice projects forward).

**Acoustic simulation (occlusion/diffraction/reverb):** Enable `SoundService.AcousticSimulationEnabled` and `AcousticSimulationEnabled` on both the emitter and listener. The current reference no longer exposes the separate per-instance `OcclusionEnabled`, `DiffractionEnabled`, and `ReverbEnabled` toggles; do not generate calls to them. Use `emitter:GetAudibilityFor(listener)` or `listener:GetAudibilityFor(emitter)` for combined distance and angle attenuation (0–1).

## Listener location

`SoundService.ListenerLocation` (a `ListenerLocation` enum) controls where the `AudioListener` is auto-created:
- **Default**: camera in experiences with voice chat.
- **None**: no auto-listener; create one via script.
- **Character**: parented to the local player's character (`Humanoid.RootPart`).
- **Camera**: parented to `workspace.CurrentCamera`.

When set to `Character` or `Camera`, the engine auto-creates an `AudioDeviceOutput` under `SoundService` at runtime. The `AudioListener` picks up audio from `AudioEmitter`s based on distance and the emitter's `DistanceAttenuation` curve.

## Triggering audio from scripts

```lua
local audio = script.Parent :: AudioPlayer
someEvent:Connect(function()
    audio:Play()
end)
```

`AudioPlayer:Play(atTime?)`, `:Stop(atTime?)`. When `atTime` is supplied the action is scheduled against `SoundService:GetMixerTime()` for sample-accurate, framerate-independent timing (rhythm games / beat sync). `:Cancel(actionId)` cancels a future-scheduled Play/Stop (returns true if cancelled). `:Pause()`, `:SeekTime(...)`, `:GetWaveform(timeRange)` (samples volume without playing; useful for waveform visualization vs live `AudioAnalyzer`). `AudioPlayer.TimeVolume` is tweenable. See [references/audio-effects.md](references/audio-effects.md) for tweening volume and effect parameters.

## Preloading audio

Preload prominent audio assets before they're needed (loading screen, round start) to avoid first-play hitches on lower-end devices:

```lua
--!strict
local ContentProvider = game:GetService("ContentProvider")
local audioPlayer = workspace:WaitForChild("MusicPlayer") :: AudioPlayer
ContentProvider:PreloadAsync({ audioPlayer })
```

For the legacy `Sound` system, preload the `Sound` instance the same way.

## Performance limits

- **Concurrent voices** (simultaneously playing audio streams) are capped; the cap varies by device. Mobile is significantly lower than desktop.
- **Effects cost CPU** per active stream routed through them. Reverb and acoustic simulation are the heaviest.
- **Acoustic simulation** (`SoundService.AcousticSimulationEnabled`) adds per-emitter occlusion/diffraction/reverb cost; disable on low-end clients or when not needed.
- **Mobile throttling:** the engine may drop or degrade audio effects on low-memory clients (e.g. flipbooks were dropped on older phones; the same applies to some audio effects). Test at low quality levels.
- **`AudioAnalyzer`** is for inspection only; don't chain it into audible paths unnecessarily.

Profile audio with the MicroProfiler (audio appears under worker threads) and the Developer Console Memory tab.

## Script context (client vs server)

- **Playback** of `AudioPlayer`, `Sound`, and effects is **client-side**. Each client plays its own audio. The server does not mix audio for clients.
- **Replication:** `AudioPlayer` state (playing/paused/stopped) replicates from server to clients if the instance is in a replicated location, but per-client volume/effects are local. For one-shot SFX, prefer **client-authoritative emission**: server signals "this event happened" via RemoteEvent, each affected client plays the sound locally. This avoids replicating per-burst timing and respects each client's quality settings (same pattern as VFX; see roblox-vfx skill).
- **Music/ambience** that should be synchronized across all clients can be server-driven (the `AudioPlayer` lives in `ReplicatedStorage` or `SoundService` and the server calls `:Play()`), but be aware each client still renders locally and may drift.
- **`AudioDeviceInput`** (microphone) is client-only. It captures the local player's mic. Pair with `VoiceChatService` for spatial voice. Access control: `SetUserIdAccessList(userIds)` + `AccessType` (`Allow` = only listed users hear the input, `Deny` = all except listed; default `Deny`), `GetUserIdAccessList()` returns the allow/deny list.
- **Never trust client audio state for gameplay.** A client claiming "I played the reload sound" tells you nothing authoritative; validate gameplay effects on the server (see roblox-networking).

## Audio asset permissions

- Audio assets uploaded before the **2022 audio privacy changes** may be private or have restricted use. Assets you upload to your own experience are usable by that experience.
- The **Creator Store** has a library of free-to-use audio assets. These are safe to reference by asset ID in any experience.
- Audio uploaded by other creators may be unusable in your experience unless they've marked it for public use. If you reference a third-party audio asset ID and it doesn't play, permissions are the usual cause.
- For new audio, upload through the Creator Dashboard's asset manager or the Open Cloud Assets API (see roblox-open-cloud skill for programmatic upload).

## Text-to-speech (TTS)

`AudioTextToSpeech` converts text (≤300 chars per request) to audio with an artificial voice. The available `VoiceId` values are 1–11 (English variants), 101–102 (Spanish), 201–202 (German), 301–302 (Italian), 401–402 (French), 501–502 (Mandarin Chinese), 601–602 (Hindi), 701–702 (Japanese), 801–802 (Arabic), 901–902 (Korean), and 1001–1002 (Portuguese); odd IDs are male and even IDs are female for the locale-specific pairs. Wire it like an `AudioPlayer`: for 2D, `AudioTextToSpeech` → `Wire` → `AudioDeviceOutput`; for 3D, `AudioTextToSpeech` → `Wire` → `AudioEmitter` (plus the listener→output wire). Set `Text`, `VoiceId`, `Volume` on the `AudioTextToSpeech`. `:WaitForSpeechReady()` yields until `AssetFetchStatus` is `Success` (or `Failure`). All text must comply with Roblox Community Standards and Terms of Use.

**Audio analysis:** `AudioAnalyzer` window is controlled by `AudioWindowSize`. `Small` (lowest latency, low frequency resolution), `Medium` (balanced), `Large` (highest resolution, more latency).

Use cases: accessibility (reading UI text aloud), NPC voiceover without recorded audio, dynamic announcements.

## Speech-to-text (STT)

`AudioSpeechToText` converts speech captured by `AudioDeviceInput` into text. Requires `VoiceChatService.UseAudioApi = Enabled`. Wire: `AudioDeviceInput` → `Wire` → `AudioSpeechToText`. Set `audioDeviceInput.Player = Players.LocalPlayer` at runtime to target the local player's mic. Roblox auto-detects the spoken language (17 supported: Arabic, Chinese Simplified/Traditional, English, French, German, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Spanish, Russian, Turkish, Thai, Vietnamese).

To use STT without broadcasting voice to other players, disable `VoiceChatService.EnableDefaultVoice`. All audio for `AudioSpeechToText` must comply with Community Standards and Terms of Use.

## Best practices

- **Preload** prominent audio (music, common SFX) during loading. One-shot UI sounds can lazy-load.
- **Loop** ambient/music with `Looping = true` (graph) or `Looped = true` (legacy). For finite loops N times, use the `DidLoop` event (legacy `Sound`) or count plays on the graph.
- **Fade in/out** by tweening `AudioPlayer.Volume` (graph) or `Sound.Volume` (legacy). `AudioFader` is the graph-native way to control multiple streams' volume at once.
- **Music vs SFX:** route music and SFX through separate `AudioFader` or `SoundGroup` so you can mute music independently and apply ducking (SFX ducks music via `AudioCompressor` sidechain).
- **3D vs 2D:** if the sound has a world position, use 3D (`AudioEmitter`); if it's UI/global, use 2D (`AudioDeviceOutput` direct).
- **Accessibility:** offer TTS for important text, provide subtitle/caption options for VO, and never make audio the only cue for gameplay-critical info.
- **Mobile:** test at low quality. The engine may drop effects; design so the experience still works without them.
- **Concurrency:** pool `AudioPlayer`/`Sound` instances for frequent one-shots rather than creating/destroying per shot.

## Common mistakes

- Using `Sound`/`SoundGroup`/`SoundEffect` for new work when the graph is the recommended path.
- Parenting an `AudioEmitter` to `SoundService` (it must be parented to a 3D part/attachment for 3D audio).
- Forgetting the `Wire` (audio won't flow from player to output/emitter).
- Expecting `SoundService.AmbientReverb` to affect the audio graph (it only affects legacy `Sound`).
- Setting `DistanceAttenuation` as a single number instead of a `NumberSequence` (it's a curve, not a scalar).
- Trusting client audio state for gameplay (reload sounds, hit sounds) instead of server validation.
- Not preloading, causing first-play hitches on mobile.
- Hardcoding asset IDs for third-party audio that may be permission-restricted.

## Scripts

- `scripts/AudioBus.lua`: a small music/SFX bus helper using `AudioFader` to control group volume and duck music when SFX play. Adapt for your mix.

## How to proceed

1. Pick the system: graph for new/complex work, `Sound` for simple/legacy.
2. Lay out your buses (music, SFX, VO) and route through `AudioFader` or `SoundGroup`.
3. Place 3D emitters on the parts that should make sound; set `DistanceAttenuation` per emitter.
4. Add effects where they add value (reverb in caves, muffling underwater, ducking).
5. Preload, then trigger from events (animation markers, UI, gameplay).
6. Profile concurrent voices and effect cost on the lowest target device.
7. Verify asset permissions for any third-party audio.

<!-- catalog:references:start -->
## Reference index

- [audio-effects.md](references/audio-effects.md): Route effects, mix audio buses, duck music, or tune attenuation.
- [audio-graph-vs-sound.md](references/audio-graph-vs-sound.md): Choose an audio system or migrate legacy Sound code.
<!-- catalog:references:end -->


Acoustic API references: https://create.roblox.com/docs/reference/engine/classes/AudioEmitter and https://create.roblox.com/docs/reference/engine/classes/AudioListener.