AudioService

Getting it

local AudioService = Engine:GetService("AudioService")

Overview

AudioService is built on Roblox's modern audio instances (AudioPlayer, AudioFader, AudioEmitter and friends) and gives you everything around them:

• Sound definitions: name a sound once, with variations, volume and pitch ranges, limits and cooldowns, then play it by name.
• A mixer of buses (Master, Music, Sfx, Ambience, UI, Voice, Speaker, Stinger by default) with volumes, muting, effects, ducking, sidechain compression and snapshots of the whole mix.
• Speakers: parts in the world that play sounds or radio-style playlists.
• Playlists with shuffle, crossfades and loop modes.
• Adaptive music: tracks with stacked layers that fade in by intensity, sections, beat and bar events, quantized transitions and stingers.
• States: one call that switches music, mix and intensity together, such as "Combat" or "Menu".
• A watchdog that notices stalled, silent or broken sounds and repairs them, so music does not just stop.

Audio is heard on the client, so playing happens there. The server can define sounds and tell clients what to play with the Broadcast... methods and SetGlobalState.

local AudioService = Engine:GetService("AudioService")

AudioService:Define("Footstep", {
	Assets = { "rbxassetid://111", "rbxassetid://112", "rbxassetid://113" },
	VolumeRange = NumberRange.new(0.4, 0.6),
	PitchRange = NumberRange.new(0.9, 1.1),
	Limit = 6,
})

AudioService:PlayAt("Footstep", character.HumanoidRootPart)

AudioService:DefineTrack("Exploration", {
	Bpm = 96,
	Layers = {
		{ Name = "Pads", Asset = "rbxassetid://201", Lead = true },
		{ Name = "Drums", Asset = "rbxassetid://202", MinIntensity = 0.5 },
	},
})

AudioService:PlayTrack("Exploration")
AudioService:SetIntensity(0.8, 2) -- drums fade in over 2 seconds

Sound definitions

Define

AudioService:Define(id: string, def: SoundDef)

Works on both sides. Define your sounds in a shared module so the server can broadcast them by name.

Playing sounds (client)

Play / PlayAt / Loop

AudioService:Play(id: string | number, config: PlayConfig?): Voice?
AudioService:PlayAt(id: string | number, at: Vector3 | CFrame | Instance, config: PlayConfig?): Voice?
AudioService:Loop(id: string | number, at: Target?, config: PlayConfig?): Voice?

Play plays a 2D sound (UI, music stingers). PlayAt plays a positional sound at a point or on an instance. Loop plays a looping bed, positional when given a target. Passing an asset id instead of a definition id plays it with default settings. Each returns a Voice, or nil when the play was skipped (cooldown, limit, too far away, voice budget full); PlaySkipped fires with the id and the reason.

Stop / StopAll

AudioService:Stop(id: string, fadeTime: number?)
AudioService:StopAll(bus: string?, fadeTime: number?)

Voice

A Voice is one playing sound.

The mixer

Every sound plays on a bus, and buses feed into their parent up to Master. The default layout comes from the Buses setting; by default Voice chat automatically pushes Music down through a sidechain compressor.

Analyze = true on a bus adds an analyzer, so you can read its loudness:

The volume properties (MasterVolume, MusicVolume, SfxVolume, AmbienceVolume, UIVolume, VoiceVolume, SpeakerVolume) and Muted make settings menus a one-liner:

musicSlider.Changed:Connect(function(value)
	AudioService.MusicVolume = value
end)

Speakers (client)

CreateSpeaker

AudioService:CreateSpeaker(part: Instance, def: SpeakerDef?): Speaker

Turns a part into a speaker: a radio, a boombox, a PA system.

Speaker methods: :Play(id?, { FadeIn?, Looped? }?), :PlayPlaylist(def), :Stop(fadeTime?), :Pause(), :Resume(), :Next(), :Previous(), :SetDirection(coneAngle?, outerGain?), :Destroy(); properties IsPlaying, CurrentTrack, Playlist, Level, Volume, Bus, Range; signals Started(track) and Stopped. :GetSpeakers() and :StopSpeakers(fadeTime?) work on all speakers.

Playlists

CreatePlaylist

AudioService:CreatePlaylist(name: string, def: PlaylistDef): Playlist

:PlayPlaylist(name, index?) plays it as the music (stopping other music), :StopPlaylist(name?, fadeTime?) stops one or all, :GetPlaylist(name) and :PlaylistNames() look them up.

A Playlist has :Play(index?), :Stop(fadeTime?), :Pause(), :Resume(), :Next(fadeTime?), :Previous(fadeTime?), :JumpTo(trackOrIndex, fadeTime?), :Add(track, index?), :Remove(trackOrIndex), :Clear(), :Destroy(); the signals TrackStarted(track, index), TrackEnded(track, index), TrackFailed(track, reason), Finished and Exhausted (every track failed); and properties such as CurrentTrack, CurrentIndex, IsPlaying, TimePosition, Shuffle, LoopMode and Volume.

Tracks that fail repeatedly drop out of rotation for a while (TrackRetrySeconds) instead of breaking the playlist.

Adaptive music

DefineTrack

AudioService:DefineTrack(id: string, def: TrackDef)

Playing and changing music (client)

Quantize values: "Immediate", "Beat", "Bar", "Section".

States

AudioService:DefineState(name: string, def: { Track?, Playlist?, Snapshot?, Intensity?, FadeTime?, Quantize? })
AudioService:SetState(name: string) -- client
AudioService:GetStateNames(): { string }

A state bundles a mix snapshot, an intensity and a track or playlist. SetState applies it all and fires StateChanged. If music is already playing, the track change is a quantized transition.

AudioService:DefineState("Combat", { Track = "Battle", Snapshot = "Default", Intensity = 1, Quantize = "Bar" })
AudioService:DefineState("Menu", { Playlist = "MenuMusic", Snapshot = "Menu" })

Broadcasting (server)

All broadcast methods send to every player, or only to players when given. Messages are batched.

Health and recovery

Several times a second the watchdog checks every voice, bus, speaker and playlist against what should be happening. It retries assets that time out, replays stalled sounds from where they were, rebuilds broken players, restarts music that went silent and skips playlist tracks that never start.

Properties

Configuration

Types

export type SoundDef
export type PlayConfig
export type Target = Vector3 | CFrame | Instance
export type Voice
export type Bus
export type BusDef
export type DuckConfig
export type DuckHandle
export type Snapshot = { [string]: number }
export type Speaker
export type SpeakerDef
export type Playlist
export type PlaylistDef
export type LoopMode = "Off" | "Track" | "Playlist"
export type TrackDef
export type LayerDef
export type SectionDef
export type Quantize = "Immediate" | "Beat" | "Bar" | "Section"
export type TransitionConfig
export type StingerConfig
export type MusicPlayConfig
export type PreloadReport
export type HealthReport
export type StateDef