Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.
AudioPlayer
Inherits from: Instance → Object
AudioPlayer is used to play audio assets. It provides a single Output pin which can be connected to other pins via Wires.
Inherits from: Instance
Memory category: Internal
Code samples: View on Creator Hub (audio-wiring---device-output).
Properties
| Name | Type / Returns | Description |
|---|---|---|
| AudioPlayer.Asset | ContentId | The asset to be loaded into the AudioPlayer. |
| AudioPlayer.AssetId | string | The asset to be loaded into the AudioPlayer. |
| AudioPlayer.AudioContent | Content | The audio content to be loaded into the AudioPlayer. |
| AudioPlayer.AutoLoad | boolean | Controls whether Asset loads automatically once assigned. |
| AudioPlayer.AutoPlay | boolean | Denotes whether this AudioPlayer starts playing as soon as it spawns in for the first time. |
| AudioPlayer.IsPlaying | boolean | Denotes whether this AudioPlayer is currently playing or planning to play. |
| AudioPlayer.IsReady | boolean | Denotes whether this AudioPlayer is loaded, buffered, and ready to play. |
| AudioPlayer.Looping | boolean | Controls whether this AudioPlayer loops. |
| AudioPlayer.LoopRegion | NumberRange | A range, in seconds, denoting a desired loop start and loop end within the PlaybackRegion of this AudioPlayer. |
| AudioPlayer.PlaybackRegion | NumberRange | Range in seconds denoting a desired start time (minimum) and stop time (maximum) within the TimeLength. |
| AudioPlayer.PlaybackSpeed | double | Controls how quickly the asset will be played, which controls its pitch. |
| AudioPlayer.TimeLength | double | Denotes the length of the loaded asset. |
| AudioPlayer.TimePosition | double | Tracks the current position of the playhead within the asset. |
| AudioPlayer.Volume | float | Controls how loudly the asset will be played. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.Archivable | boolean | Determines if an Instance and its descendants can be cloned using Instance:Clone(), and can be saved/published. |
| Instance.archivable | boolean | |
| Instance.Capabilities | SecurityCapabilities | The set of capabilities allowed to be used for scripts inside this container. |
| Instance.IsInSandbox | boolean | Indicates whether the instance is inside a sandboxed container. |
| Instance.Name | string | A non-unique identifier of the Instance. |
| Instance.Parent | Instance | Determines the hierarchical parent of the Instance. |
| Instance.PredictionMode | PredictionMode | Reflects the client-side prediction mode applied to the instance under server-authoritative physics. |
| Instance.RobloxLocked | boolean | A deprecated property that used to protect CoreGui objects. |
| Instance.Sandboxed | boolean | When enabled, the instance can only access abilities in its Capabilities list. |
| Instance.UniqueId | UniqueId | A unique identifier for the instance. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.ClassName | string | A read-only string representing the class this Object belongs to. |
| Object.className | string |
AudioPlayer.Asset
The asset to be loaded into the AudioPlayer. If AutoLoad is true, the asset loads immediately once this property is assigned. When loading is complete, IsReady becomes true.
| Field | Value |
|---|---|
| type | ContentId |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.AssetId
Deprecated. This property is deprecated; use Asset instead.
The asset to be loaded into the AudioPlayer. If AutoLoad is true, the asset loads immediately once this property is assigned. When loading is complete, IsReady becomes true.
| Field | Value |
|---|---|
| type | string |
| tags | ["Hidden","NotReplicated","Deprecated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":true,"can_save":false} |
| capabilities | ["Audio"] |
AudioPlayer.AudioContent
The audio content to be loaded into the AudioPlayer. If AutoLoad is true, the asset loads immediately once this property is assigned. When loading is complete, IsReady becomes true.
| Field | Value |
|---|---|
| type | Content |
| tags | ["Hidden"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.AutoLoad
Controls whether Asset loads automatically once assigned. If false, the asset will load upon the first attempt to play.
| Field | Value |
|---|---|
| type | boolean |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.AutoPlay
Denotes whether this AudioPlayer starts playing as soon as it enters the DataModel for the first time. This only applies to AudioPlayers that are created or deserialized locally, and does not apply to AudioPlayers generated via replication. This property is primarily used at edit time in Studio to have an AudioPlayer begin when entering a play session.
| Field | Value |
|---|---|
| type | boolean |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Playback |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.IsPlaying
Denotes whether this AudioPlayer is currently playing or planning to play. This property is read-only, but replicates. To play and stop an AudioPlayer at runtime, use the Play() and Stop() methods.
| Field | Value |
|---|---|
| type | boolean |
| security | {"read":"None","write":"RobloxEngineSecurity"} |
| thread safety | ReadSafe |
| category | Playback |
| serialization | {"can_load":false,"can_save":false} |
| capabilities | ["Audio"] |
AudioPlayer.IsReady
Denotes whether this AudioPlayer is loaded, buffered, and ready to play. Although uncommon, AudioPlayers may have their assets unloaded at runtime if there is extreme memory pressure, in which case IsReady will become false.
| Field | Value |
|---|---|
| type | boolean |
| tags | ["ReadOnly","NotReplicated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":false,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.Looping
Controls whether this AudioPlayer loops when exceeding the end of its TimeLength, LoopRegion, or PlaybackRegion.
| Field | Value |
|---|---|
| type | boolean |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Playback |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.LoopRegion
A range, in seconds, denoting a desired loop start and loop end within the PlaybackRegion of this AudioPlayer.
If the LoopRegion minimum is greater than the PlaybackRegion minimum, the loop starts from the LoopRegion minimum.
If the LoopRegion minimum is less than the PlaybackRegion minimum, the loop starts from the PlaybackRegion minimum.
If the LoopRegion maximum is greater than the PlaybackRegion maximum, the loop ends at the PlaybackRegion maximum.
If the LoopRegion maximum is less than the PlaybackRegion maximum, the loop ends at exactly the LoopRegion maximum.
If the LoopRegion minimum equals the LoopRegion maximum, the AudioPlayer uses the PlaybackRegion property instead.
| Field | Value |
|---|---|
| type | NumberRange |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Regions |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.PlaybackRegion
Range in seconds denoting a desired start time (minimum) and stop time (maximum) within the TimeLength.
If the PlaybackRegion minimum is greater than 0, the sound begins playing from the PlaybackRegion minimum time.
If the PlaybackRegion minimum is less than 0, the sound begins playing from 0.
If the PlaybackRegion maximum is greater than the TimeLength, the sound stops at TimeLength.
If the PlaybackRegion maximum is less than the TimeLength, the sound stops at exactly the PlaybackRegion maximum.
If the PlaybackRegion minimum equals the PlaybackRegion maximum, the sound plays in its entirety.
| Field | Value |
|---|---|
| type | NumberRange |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Regions |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.PlaybackSpeed
Multiplier controlling how quickly the asset will be played, directly controlling its perceived pitch. Ranges from 0 to 20.
| Field | Value |
|---|---|
| type | double |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Playback |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.TimeLength
Denotes the length of the loaded Asset in seconds.
| Field | Value |
|---|---|
| type | double |
| tags | ["ReadOnly","NotReplicated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Asset |
| serialization | {"can_load":false,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.TimePosition
Tracks and controls the current position of the playhead within the Asset, in seconds.
| Field | Value |
|---|---|
| type | double |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Playback |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
AudioPlayer.Volume
Volume level which is multiplied onto the output audio stream, controlling how loudly the asset will be played. Ranges from 0 to 10.
| Field | Value |
|---|---|
| type | float |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | State |
| serialization | {"can_load":true,"can_save":true} |
| capabilities | ["Audio"] |
Methods
| Name | Type / Returns | Description |
|---|---|---|
| AudioPlayer:Cancel | boolean | Attempts to cancel a pre-planned future Play or Stop command. |
| AudioPlayer:GetConnectedWires | List | Returns an array of Wires that are connected to the specified pin. |
| AudioPlayer:GetInputPins | Array | Gets the list of pins that Wire can use in Wire.TargetName to connect to this instance via its Wire.TargetInstance property. |
| AudioPlayer:GetOutputPins | Array | Gets the list of pins that Wire can use in Wire.SourceName to connect to this instance via its Wire.SourceInstance property. |
| AudioPlayer:GetWaveformAsync | Array | Returns a sampling of the waveform data for the loaded Asset. |
| AudioPlayer:Play | int64? | Plays the AudioPlayer from wherever its TimePosition is. |
| AudioPlayer:Stop | int64? | Stops the AudioPlayer wherever its TimePosition is. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance:AddTag | () | Applies a tag to the instance. |
| Instance:children | Instances | Returns an array of the object's children. |
| Instance:ClearAllChildren | () | This method destroys all of an instance's children. |
| Instance:Clone | Instance | Create a copy of an instance and all its descendants, ignoring instances that are not Archivable. |
| Instance:clone | Instance | |
| Instance:Destroy | () | Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children. |
| Instance:destroy | () | |
| Instance:FindFirstAncestor | Instance? | Returns the first ancestor of the Instance whose Instance.Name is equal to the given name. |
| Instance:FindFirstAncestorOfClass | Instance? | Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className. |
| Instance:FindFirstAncestorWhichIsA | Instance? | Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstChild | Instance? | Returns the first child of the Instance found with the given name. |
| Instance:findFirstChild | Instance | |
| Instance:FindFirstChildOfClass | Instance? | Returns the first child of the Instance whose ClassName is equal to the given class name. |
| Instance:FindFirstChildWhichIsA | Instance? | Returns the first child of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstDescendant | Instance? | Returns the first descendant found with the given Instance.Name. |
| Instance:GetActor | Actor? | Returns the Actor associated with the Instance, if any. |
| Instance:GetAttribute | Variant | Returns the value which has been assigned to the given attribute name. |
| Instance:GetAttributeChangedSignal | RBXScriptSignal | Returns an event that fires when the given attribute changes. |
| Instance:GetAttributes | Dictionary | Returns a dictionary of the instance's attributes. |
| Instance:GetChildren | Instances | Returns an array containing all of the instance's children. |
| Instance:getChildren | Instances | |
| Instance:GetDebugId | string | Returns a coded string of the debug ID used internally by Roblox. |
| Instance:GetDescendants | Instances | Returns an array containing all of the descendants of the instance. |
| Instance:GetFullName | string | Returns a string describing the instance's ancestry. |
| Instance:GetStyled | Variant | Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified. |
| Instance:GetStyledPropertyChangedSignal | RBXScriptSignal | Returns an event that fires when the given style property changes on the instance. |
| Instance:GetTags | Array | Gets an array of all tags applied to the instance. |
| Instance:HasTag | boolean | Check whether the instance has a given tag. |
| Instance:IsAncestorOf | boolean | Returns true if an Instance is an ancestor of the given descendant. |
| Instance:IsDescendantOf | boolean | Returns true if an Instance is a descendant of the given ancestor. |
| Instance:isDescendantOf | boolean | |
| Instance:IsPropertyModified | boolean | Returns true if the value stored in the specified property is not equal to the code-instantiated default. |
| Instance:QueryDescendants | Instances | Returns an array containing all descendants of the instance that match the selector string. |
| Instance:Remove | () | Sets the object's Parent to nil, and does the same for all its descendants. |
| Instance:remove | () | |
| Instance:RemoveTag | () | Removes a tag from the instance. |
| Instance:ResetPropertyToDefault | () | Resets a property to its default value. |
| Instance:SetAttribute | () | Sets the attribute with the given name to the given value. |
| Instance:WaitForChild | Instance | Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object:GetPropertyChangedSignal | RBXScriptSignal | Get an event that fires when a given property of the object changes. |
| Object:IsA | boolean | Returns true if an object's class matches or inherits from a given class. |
| Object:isA | boolean |
AudioPlayer:Cancel
Attempts to cancel a Play() or Stop() command that was scheduled to occur at a future time. When Play() or Stop() is called with an atTime argument, the action is scheduled against GetMixerTime() and the call returns a unique actionId. Passing that actionId to this method prevents the scheduled action from taking effect.
Returns true if the pending action was found and successfully cancelled. Returns false if the action has already occurred, was never scheduled, or the supplied actionId does not correspond to a pending action.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| actionId | int64? | The unique-ID of a pre-planned Play or Stop command. |
Returns
| Type | Description |
|---|---|
| boolean | Whether the cancellation was successful. Returns false if the action has already occurred, or otherwise does not exist. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:GetConnectedWires
Returns an array of Wires that are connected to the specified pin. AudioPlayer has one "Output" pin.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| pin | string | An input or output pin on this instance |
Returns
| Type | Description |
|---|---|
| List | An array of Wires |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:GetInputPins
Gets the list of pins that Wire can use in Wire.TargetName to connect to this instance via its Wire.TargetInstance property.
For AudioPlayer, there are none.
Returns
| Type | Description |
|---|---|
| Array | An array of strings representing valid pin names. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:GetOutputPins
Gets the list of pins that Wire can use in Wire.SourceName to connect to this instance via its Wire.SourceInstance property.
For AudioPlayer, this is Output only.
Returns
| Type | Description |
|---|---|
| Array | An array of strings representing valid pin names. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:GetWaveformAsync
Returns a sampling of the waveform data for the loaded Asset, allowing you to check the volume of an asset over its full duration without playing it. Unlike AudioAnalyzer, which measures volume levels of a live audio stream in real time, this method analyzes the asset ahead of time, making it suitable for waverform visualization or logic that needs audio content before playback begins.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| timeRange | NumberRange | The start and end time (in seconds) of the segment to read. | |
| samples | int | The number of samples to return for the specified range. |
Returns
| Type | Description |
|---|---|
| Array | A table of samples numbers ranging between -1 and 1 representing the sampled waveform, or an empty table if a waveform could not be read. |
| Field | Value |
|---|---|
| tags | ["Yields"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:Play
Plays the AudioPlayer from wherever its TimePosition is. Replicates from server to client. When atTime is provided, the action is scheduled against GetMixerTime() for sample-accurate, framerate-independent timing — useful for rhythm games or any scenario where audio changes must align precisely with a beat.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| atTime | double? | A specific time, based on GetMixerTime, that this AudioPlayer should begin playing at. |
Returns
| Type | Description |
|---|---|
| int64? | If atTime was provided, a unique ID, which can be passed to Cancel(). |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
AudioPlayer:Stop
Stops the AudioPlayer wherever its TimePosition is. Replicates from server to client. When atTime is provided, the action is scheduled against GetMixerTime() for sample-accurate, framerate-independent timing, enabling precise beat-synchronized stops or track transitions.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| atTime | double? | A specific time, based on GetMixerTime, that this AudioPlayer should stop playing at. |
Returns
| Type | Description |
|---|---|
| int64? | If atTime was provided, a unique ID, which can be passed to Cancel(). |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Audio"] |
Events
| Name | Type / Returns | Description |
|---|---|---|
| AudioPlayer.Ended | Fires when the AudioPlayer has completed playback and stopped. | |
| AudioPlayer.Looped | Fires when the AudioPlayer loops. | |
| AudioPlayer.WiringChanged | Fires when another instance is connected to or disconnected from the AudioPlayer via a Wire. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.AncestryChanged | Fires when the Instance.Parent property of this object or one of its ancestors is changed. | |
| Instance.AttributeChanged | Fires whenever an attribute is changed on the Instance. | |
| Instance.ChildAdded | Fires after an object is parented to this Instance. | |
| Instance.childAdded | ||
| Instance.ChildRemoved | Fires after a child is removed from this Instance. | |
| Instance.DescendantAdded | Fires after a descendant is added to the Instance. | |
| Instance.DescendantRemoving | Fires immediately before a descendant of the Instance is removed. | |
| Instance.Destroying | Fires immediately before (or is deferred until after) the instance is destroyed via Instance:Destroy(). | |
| Instance.StyledPropertiesChanged | Fires whenever any style property is changed on the instance, including when a property is set to nil. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.Changed | Fires immediately after a property of the object changes, with some limitations. |
AudioPlayer.Ended
Fires after the AudioPlayer has completed playback and stopped. Note this event will not fire for audio with Looping set to true since it continues playing upon reaching its end. This event will also not fire when the audio is stopped before playback has completed; for this, use AudioPlayer:GetPropertyChangedSignal() on the IsPlaying property.
This event is often used to destroy an AudioPlayer when it has completed playback.
| Field | Value |
|---|---|
| security | None |
| capabilities | ["Audio"] |
AudioPlayer.Looped
Event that fires after the AudioPlayer loops. This happens when the audio reaches the end of its content (or the end of the LoopRegion if it is active) and Looping is true.
This event does not fire if the audio is looped manually by changing its TimePosition.
| Field | Value |
|---|---|
| security | None |
| capabilities | ["Audio"] |
AudioPlayer.WiringChanged
Event that fires after a Wire becomes connected or disconnected, and that Wire is now or was previously connected to a pin on the AudioPlayer and to some other wirable instance.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| connected | boolean | Whether the instance got connected or disconnected. | |
| pin | string | The pin on the AudioPlayer that the Wire targets. | |
| wire | Wire | The Wire between the AudioPlayer and the other instance. | |
| instance | Instance | The other instance that is or was connected through the Wire. |
| Field | Value |
|---|---|
| security | None |
| capabilities | ["Audio"] |