rojo/.cursor/rules/roblox/reference/engine/classes/AudioPlayer.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: AudioPlayer
type: class
memory_category: Internal
summary: |
  Used to play audio assets.
description: |
  `Class.AudioPlayer` is used to play audio assets. It provides a single
  **Output** pin which can be connected to other pins via `Class.Wire|Wires`.
code_samples:
  - audio-wiring---device-output
inherits:
  - Instance
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: AudioPlayer.Asset
    summary: |
      The asset to be loaded into the `Class.AudioPlayer`.
    description: |
      The asset to be loaded into the `Class.AudioPlayer`. If
      `Class.AudioPlayer.AutoLoad|AutoLoad` is `true`, the asset loads
      immediately once this property is assigned. When loading is complete,
      `Class.AudioPlayer.IsReady|IsReady` becomes `true`.
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.AssetId
    summary: |
      The asset to be loaded into the `Class.AudioPlayer`.
    description: |
      The asset to be loaded into the `Class.AudioPlayer`. If
      `Class.AudioPlayer.AutoLoad|AutoLoad` is `true`, the asset loads
      immediately once this property is assigned. When loading is complete,
      `Class.AudioPlayer.IsReady|IsReady` becomes `true`.
    code_samples: []
    type: string
    tags:
      - Hidden
      - NotReplicated
      - Deprecated
    deprecation_message: |
      This property is deprecated; use `Class.AudioPlayer.Asset|Asset` instead.
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - Audio
  - name: AudioPlayer.AudioContent
    summary: ''
    description: ''
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.AutoLoad
    summary: |
      Controls whether `Class.AudioPlayer.Asset|Asset` loads automatically once
      assigned.
    description: |
      Controls whether `Class.AudioPlayer.Asset|Asset` loads automatically once
      assigned. If `false`, the asset will load upon the first attempt to play.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.AutoPlay
    summary: |
      Denotes whether this `Class.AudioPlayer` starts playing as soon as it
      spawns in for the first time.
    description: |
      Denotes whether this `Class.AudioPlayer` starts playing as soon as it
      enters the `Class.DataModel` for the first time. This only applies to
      `Class.AudioPlayer|AudioPlayers` that are created or deserialized locally,
      and does not apply to `Class.AudioPlayer|AudioPlayers` generated via
      replication. This property is primarily used at edit time in Studio to
      have an `Class.AudioPlayer` begin when entering a play session.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Playback
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.IsMutedForCapture
    summary: ''
    description: ''
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: RobloxScriptSecurity
      write: RobloxScriptSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.IsPlaying
    summary: |
      Denotes whether this `Class.AudioPlayer` is currently playing.
    description: |
      Denotes whether this `Class.AudioPlayer` is currently playing. This
      property is read-only, but replicates. To play and stop an
      `Class.AudioPlayer` at runtime, use the `Class.AudioPlayer:Play()|Play()`
      and `Class.AudioPlayer:Stop()|Stop()` methods.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: RobloxEngineSecurity
    thread_safety: ReadSafe
    category: Playback
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Audio
  - name: AudioPlayer.IsReady
    summary: |
      Denotes whether this `Class.AudioPlayer` is loaded, buffered, and ready to
      play.
    description: |
      Denotes whether this `Class.AudioPlayer` is loaded, buffered, and ready to
      play. Although uncommon, `Class.AudioPlayer|AudioPlayers` may have their
      assets unloaded at runtime if there is extreme memory pressure, in which
      case `Class.AudioPlayer.IsReady|IsReady` will become false.
    code_samples: []
    type: boolean
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.Looping
    summary: |
      Controls whether this `Class.AudioPlayer` loops.
    description: |
      Controls whether this `Class.AudioPlayer` loops when exceeding the end of
      its `Class.AudioPlayer.TimeLength|TimeLength`,
      `Class.AudioPlayer.LoopRegion|LoopRegion`, or
      `Class.AudioPlayer.PlaybackRegion|PlaybackRegion`.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Playback
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.LoopRegion
    summary: |
      A range, in seconds, denoting a desired loop start and loop end within the
      `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` of this
      `Class.AudioPlayer`.
    description: |
      A range, in seconds, denoting a desired loop start and loop end within the
      `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` of this
      `Class.AudioPlayer`.

      If the `Class.AudioPlayer.LoopRegion|LoopRegion` minimum is **greater**
      than the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum, the
      loop starts from the `Class.AudioPlayer.LoopRegion|LoopRegion` minimum.

      If the `Class.AudioPlayer.LoopRegion|LoopRegion` minimum is **less** than
      the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum, the loop
      starts from the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum.

      If the `Class.AudioPlayer.LoopRegion|LoopRegion` maximum is **greater**
      than the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` maximum, the
      loop ends at the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion`
      maximum.

      If the `Class.AudioPlayer.LoopRegion|LoopRegion` maximum is **less** than
      the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` maximum, the loop
      ends at exactly the `Class.AudioPlayer.LoopRegion|LoopRegion` maximum.

      If the `Class.AudioPlayer.LoopRegion|LoopRegion` minimum **equals** the
      `Class.AudioPlayer.LoopRegion|LoopRegion` maximum, the `Class.AudioPlayer`
      uses the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` property
      instead.
    code_samples: []
    type: NumberRange
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Regions
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.PlaybackRegion
    summary: |
      Range in seconds denoting a desired start time (minimum) and stop time
      (maximum) within the `Class.AudioPlayer.TimeLength|TimeLength`.
    description: |
      Range in seconds denoting a desired start time (minimum) and stop time
      (maximum) within the `Class.AudioPlayer.TimeLength|TimeLength`.

      If the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum is
      **greater** than 0, the sound begins playing from the
      `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum time.

      If the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum is
      **less** than 0, the sound begins playing from 0.

      If the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` maximum is
      **greater** than the `Class.AudioPlayer.TimeLength|TimeLength`, the sound
      stops at `Class.AudioPlayer.TimeLength|TimeLength`.

      If the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` maximum is
      **less** than the `Class.AudioPlayer.TimeLength|TimeLength`, the sound
      stops at exactly the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion`
      maximum.

      If the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` minimum
      **equals** the `Class.AudioPlayer.PlaybackRegion|PlaybackRegion` maximum,
      the sound plays in its entirety.
    code_samples: []
    type: NumberRange
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Regions
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.PlaybackSpeed
    summary: |
      Controls how quickly the asset will be played, which controls its pitch.
    description: |
      Multiplier controlling how quickly the asset will be played, directly
      controlling its perceived pitch. Ranges from 0 to 20.
    code_samples: []
    type: double
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Playback
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.TimeLength
    summary: |
      Denotes the length of the loaded asset.
    description: |
      Denotes the length of the loaded `Class.AudioPlayer.Asset|Asset` in
      seconds.
    code_samples: []
    type: double
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Asset
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.TimePosition
    summary: |
      Tracks the current position of the playhead within the asset.
    description: |
      Tracks and controls the current position of the playhead within the
      `Class.AudioPlayer.Asset|Asset`, in seconds.
    code_samples: []
    type: double
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Playback
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: AudioPlayer.Volume
    summary: |
      Controls how loudly the asset will be played.
    description: |
      Volume level which is multiplied onto the output audio stream, controlling
      how loudly the asset will be played. Ranges from 0 to 3.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: State
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
methods:
  - name: AudioPlayer:GetConnectedWires
    summary: |
      Returns an array of `Class.Wire|Wires` that are connected to the specified
      pin.
    description: |
      Returns an array of `Class.Wire|Wires` that are connected to the specified
      pin. `Class.AudioPlayer` has one "Output" pin.
    code_samples: []
    parameters:
      - name: pin
        type: string
        default:
        summary: ''
    returns:
      - type: Instances
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: AudioPlayer:GetInputPins
    summary: ''
    description: ''
    code_samples: []
    parameters: []
    returns:
      - type: Array
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: AudioPlayer:GetOutputPins
    summary: ''
    description: ''
    code_samples: []
    parameters: []
    returns:
      - type: Array
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: AudioPlayer:GetWaveformAsync
    summary: ''
    description: ''
    code_samples: []
    parameters:
      - name: timeRange
        type: NumberRange
        default:
        summary: ''
      - name: samples
        type: int
        default:
        summary: ''
    returns:
      - type: Array
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: AudioPlayer:Play
    summary: |
      Plays the `Class.AudioPlayer` from wherever its
      `Class.AudioPlayer.TimePosition|TimePosition` is.
    description: |
      Plays the `Class.AudioPlayer` from wherever its
      `Class.AudioPlayer.TimePosition|TimePosition` is. Replicates from server
      to client.
    code_samples: []
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: AudioPlayer:Stop
    summary: |
      Stops the `Class.AudioPlayer` wherever its
      `Class.AudioPlayer.TimePosition|TimePosition` is.
    description: |
      Stops the `Class.AudioPlayer` wherever its
      `Class.AudioPlayer.TimePosition|TimePosition` is. Replicates from server
      to client.
    code_samples: []
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
events:
  - name: AudioPlayer.Ended
    summary: |
      Fires when the `Class.AudioPlayer` has completed playback and stopped.
    description: |
      Fires after the `Class.AudioPlayer` has completed playback and stopped.
      Note this event will **not** fire for audio with
      `Class.AudioPlayer.Looped|Looped` 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
      `Class.AudioPlayer:GetPropertyChangedSignal()` on the
      `Class.AudioPlayer.IsPlaying|IsPlaying` property.

      This event is often used to destroy an `Class.AudioPlayer` when it has
      completed playback.
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Audio
  - name: AudioPlayer.Looped
    summary: |
      Fires when the `Class.AudioPlayer` loops.
    description: |
      Event that fires after the `Class.AudioPlayer` loops. This happens when
      the audio reaches the end of its content (or the end of the
      `Class.AudioPlayer.LoopRegion|LoopRegion` if it is active) and
      `Class.AudioPlayer.Looping|Looping` is `true`.

      This event does **not** fire if the audio is looped manually by changing
      its `Class.AudioPlayer.TimePosition|TimePosition`.
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Audio
  - name: AudioPlayer.WiringChanged
    summary: |
      Fires when another instance is connected to or disconnected from the
      `Class.AudioPlayer` via a `Class.Wire`.
    description: |
      Event that fires after a `Class.Wire` becomes connected or disconnected,
      and that `Class.Wire` is now or was previously connected to a pin on the
      `Class.AudioPlayer` and to some other wirable instance.
    code_samples: []
    parameters:
      - name: connected
        type: boolean
        default:
        summary: |
          Whether the instance got connected or disconnected.
      - name: pin
        type: string
        default:
        summary: |
          The pin on the `Class.AudioPlayer` that the `Class.Wire` targets.
      - name: wire
        type: Wire
        default:
        summary: |
          The `Class.Wire` between the `Class.AudioPlayer` and the other
          instance.
      - name: instance
        type: Instance
        default:
        summary: |
          The other instance that is or was connected through the `Class.Wire`.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Audio
callbacks: []