# 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: SoundService
type: class
memory_category: Instances
summary: |
  A service that determines various aspects of how the audio engine works. Most
  of its properties affect how `Class.Sound|Sounds` play in the experience.
description: |
  A service that determines various aspects of how the audio engine works. Most
  of its properties affect how `Class.Sound|Sounds` play in the experience,
  while others affect the behavior of instances in the advanced audio system
  such as `Class.AudioPlayer|AudioPlayers` and
  `Class.AudioEmitter|AudioEmitters`.

  `Class.SoundService` is also often used to store
  `Class.SoundGroup|SoundGroups`, although this is not mandatory for groups to
  work.
code_samples:
  - SoundService-Reverb-System
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties:
  - name: SoundService.AcousticSimulationEnabled
    summary: |
      Determines whether acoustic simulation is enabled globally in the advanced
      audio system.
    description: |
      Determines at a global level whether sound from
      `Class.AudioEmitter|AudioEmitters` and
      `Class.AudioListener|AudioListeners` should automatically implement
      features of acoustic simulation, such as occlusion (being muffled through
      walls), diffraction (bending around corners), and reverberation (echoing
      off of walls).

      If set to `false`, these instances will not simulate these features,
      regardless of their individual
      `Class.AudioEmitter.AcousticSimulationEnabled|AcousticSimulationEnabled`
      settings.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.AmbientReverb
    summary: |
      The ambient sound environment preset applied to all `Class.Sound|Sounds`.
    description: |
      A reverb preset that should be applied to all `Class.Sound|Sounds` in the
      experience.

      Each `Enum.ReverbType` option for this property corresponds to a preset
      available in the FMOD sound engine. For example, when
      `Class.SoundService.AmbientReverb|AmbientReverb` is set to
      `Enum.ReverbType.Hangar`, `Class.Sound|Sounds` will have reverb applied to
      simulate being in a large enclosed space.

      Note that this only affects `Class.Sound|Sounds` and **not** instances in
      the advanced audio system such as `Class.AudioPlayer|AudioPlayers` and
      `Class.AudioEmitter|AudioEmitters`. See `Class.AudioReverb` for a way to
      apply reverb in that system.
    code_samples: []
    type: ReverbType
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.CharacterSoundsUseNewApi
    summary: |
      Determines whether the default character sounds will use instances in the
      advanced audio system vs. `Class.Sound|Sounds`.
    description: |
      Determines which set of instances core scripts will use to create default
      character sounds. If set to `Enum.RolloutState.Enabled`, it will use
      instances in the advanced audio system such as
      `Class.AudioPlayer|AudioPlayers` and `Class.AudioEmitter|AudioEmitters`.
      If set to `Enum.RolloutState.Disabled`, it will use instances in the
      legacy sound system such as `Class.Sound|Sounds`.
    code_samples: []
    type: RolloutState
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.DefaultListenerLocation
    summary: |
      Determines where (if anywhere) to place an `Class.AudioListener` by
      default.
    description: |
      Determines where to place an `Class.AudioListener` by default. The
      `Class.AudioListener` will automatically be wired to a
      `Class.AudioDeviceOutput` and will have an empty
      `Class.AudioListener.InteractionGroup` set.

      See `Enum.ListenerLocation` for detailed descriptions of each option.
    code_samples: []
    type: ListenerLocation
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.DistanceFactor
    summary: |
      The number of studs to be considered a meter by `Class.SoundService` when
      simulating the Doppler effect for `Class.Sound|Sounds`.
    description: |
      The number of studs to be considered a meter by `Class.SoundService` when
      simulating the Doppler effect for `Class.Sound|Sounds`. This impacts any
      `Class.Sound` parented to a `Class.BasePart` or `Class.Attachment`.

      By default, this property is `3.33`, meaning that a meter is considered
      3.33 studs for the purposes of simulating the Doppler effect. The greater
      the `Class.SoundService.DistanceFactor|DistanceFactor`, the faster the
      listener has to travel relative to `Class.Sound|Sounds` in order to
      experience the same Doppler shift.

      It's recommended that you only change this property if the objects in your
      experience are scaled differently from what they represent. For example,
      if your character is meant to be very small (but is normal-sized in the
      engine), you may want to increase `Class.SoundService.DistanceFactor`.

      Note that this does not impact the behavior of instances in the advanced
      audio system, such as `Class.AudioPlayer` or `Class.AudioEmitter`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.DopplerScale
    summary: |
      Degree to which the pitch of a `Class.Sound` varies due to the Doppler
      effect.
    description: |
      This property determines the degree to which the pitch of a `Class.Sound`
      varies due to the Doppler effect. This impacts any `Class.Sound` parented
      to a `Class.BasePart` or `Class.Attachment`.

      The Doppler effect is a phenomenon whereby the pitch of a sound changes as
      the source and observer of the sound move further away or closer together,
      which is stronger the more quickly they are moving. Increasing
      `Class.SoundService.DopplerScale` exaggerates the impact of this effect,
      whereas decreasing it minimizes it. By default, the value of this property
      is `1`.

      Note that this does not impact the behavior of instances in the advanced
      audio system, such as `Class.AudioPlayer` or `Class.AudioEmitter`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.RespectFilteringEnabled
    summary: |
      Sets whether `Class.Sound` playback from a client will replicate to the
      server.
    description: |
      This property determines whether `Class.Sound` playback is replicated from
      the client to the server, and therefore from the server. In other words,
      when a `Class.LocalScript` calls `Class.Sound:Play()|Play()` and this
      property is `true`, the sound will only play on the respective client. If
      this property is `false`, other clients will also hear the sound.

      Default is `true`, meaning filtering is enabled.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.RolloffScale
    summary: |
      Determines how fast the volume of a `Class.Sound` attenuates beyond its
      `Class.Sound.RollOffMinDistance`.
    description: |
      Determines how fast the volume of a spatialized `Class.Sound` attenuates.
      This impacts any `Class.Sound` parented to a `Class.BasePart` or
      `Class.Attachment`.

      A higher `Class.SoundService.RolloffScale|RolloffScale` means the volume
      of a `Class.Sound` will attenuate more rapidly as the distance between the
      listener and the `Class.Sound|Sound` grows. More precisely, the volume of
      the `Class.Sound` will still start attenuating at a distance equal to
      `Class.Sound.RollOffMinDistance`, but the attenuation curve will be
      steeper or more gradual based on the value of
      `Class.SoundService.RolloffScale|RolloffScale`. Note that the
      `Class.Sound` will still be inaudible past its the
      `Class.Sound.RollOffMaxDistance` regardless of the value of
      `Class.SoundService.RolloffScale`.

      Note that this property does not affect the behavior of instances in the
      advanced audio system, such as `Class.AudioEmitter`. See
      `Class.AudioEmitter:SetDistanceAttenuation` for a way to apply custom
      attenuation in that system.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
  - name: SoundService.VolumetricAudio
    summary: |
      Determines whether certain spatialized `Class.Sound|Sounds` emit
      volumetrically, throughout the space of their parent object.
    description: |
      Determines whether any `Class.Sound|Sounds` parented to a `Class.Part`
      emit volumetrically. If set to `Enum.VolumetricAudio.Enabled`, the
      `Class.Sound` will simulate being emitted from every point in the interior
      of the `Class.Part`. If set to `Enum.VolumetricAudio.Disabled`, the
      `Class.Sound` will only emit from a single point in the center of the
      `Class.Part`.

      Note that this does not impact `Class.Sound|Sounds` parented to other
      objects, such as `Class.Attachment|Attachments` or
      `Class.MeshPart|MeshParts`. This also does not impact the behavior of
      instances in the advanced audio system such as `Class.AudioEmitter`.
    code_samples: []
    type: VolumetricAudio
    tags:
      - NotScriptable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Audio
methods:
  - name: SoundService:GetListener
    summary: |
      Returns the current listener type used by `Class.Sound|Sounds`, as well as
      what that listener is currently set to.
    description: |
      Returns the current listener type used by `Class.Sound|Sounds` and what
      object or position that listener is currently set to. This is the point
      from which `Class.Sound` audio in the experience is heard by the player.
      By default, the listener is set to `Class.Workspace.CurrentCamera`. The
      listener can be changed using
      `Class.SoundService:SetListener()|SetListener()`.

      Note that this does not affect the listener location when using the
      advanced audio system. See `Class.AudioListener` for a way to set the
      listener location in that system.
    code_samples: []
    parameters: []
    returns:
      - type: Tuple
        summary: |
          A table containing two results. The first result is the listener's
          `Enum.ListenerType` and the second result is dependent on that type:

          <table>
                <thead>
          	  <tr>
          	      <th>Listener Type</th>
          	      <th>Description</th>
          	  </tr>
                </thead>
                <tbody>
          	  <tr>
          	      <td><code>Enum.ListenerType.Camera</code></td>
          	      <td>Does not return a listener object as <code>Class.Workspace.CurrentCamera|CurrentCamera</code> is always used.</td>
          	  </tr>
          	  <tr>
          	      <td><code>Enum.ListenerType.CFrame</code></td>
          	      <td>Returns the <code>Datatype.CFrame</code> used in <code>Class.SoundService:SetListener()|SetListener()</code>.</td>
          	  </tr>
          	  <tr>
          	      <td><code>Enum.ListenerType.ObjectPosition</code></td>
          	      <td>Returns the <code>Class.BasePart</code> used in <code>Class.SoundService:SetListener()|SetListener()</code>.</td>
          	  </tr>
          	  <tr>
          	      <td><code>Enum.ListenerType.ObjectCFrame</code></td>
          	      <td>Returns the <code>Class.BasePart</code> used in <code>Class.SoundService:SetListener()|SetListener()</code>.</td>
          	  </tr>
                </tbody>
          </table>
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: SoundService:OpenAttenuationCurveEditor
    summary: |
      Opens the attenuation curve editor in Studio for the provided
      `Class.AudioEmitter` or `Class.AudioListener` instances.
    description: |
      Opens the attenuation curve editor in Studio for the provided
      `Class.AudioEmitter` or `Class.AudioListener` instances.
    code_samples: []
    parameters:
      - name: selectedCurveObjects
        type: Instances
        default:
        summary: |
          A list of `Class.AudioEmitter|AudioEmitters` or
          `Class.AudioListener|AudioListeners`.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: PluginSecurity
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: SoundService:OpenDirectionalCurveEditor
    summary: |
      Opens the directional curve editor in Studio for the provided
      `Class.AudioEmitter` or `Class.AudioListener` instances.
    description: |
      Opens the directional curve editor in Studio for the provided
      `Class.AudioEmitter` or `Class.AudioListener` instances.
    code_samples: []
    parameters:
      - name: selectedCurveObjects
        type: Instances
        default:
        summary: |
          A list of `Class.AudioEmitter|AudioEmitters` or
          `Class.AudioListener|AudioListeners`.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: PluginSecurity
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: SoundService:PlayLocalSound
    summary: |
      Plays a copy of a `Class.Sound` locally, such that it will only be heard
      by the client calling this method.
    description: |
      Plays a copy of a `Class.Sound` locally. The `Class.Sound` will only be
      heard by the client calling this method, regardless of where it's parented
      to.

      Some properties of the `Class.Sound` will be carried over into the copy.
      These include its `Class.Sound.Volume`, `Class.Sound.TimePosition`,
      `Class.Sound.PlaybackSpeed`, and any spatialization and effects that are
      applied to it, including through `Class.Sound.SoundGroup|SoundGroups`.
      Properties that do not affect the copy include `Class.Sound.Looped` and
      `Class.SoundService.AmbientReverb`.
    code_samples: []
    parameters:
      - name: sound
        type: Instance
        default:
        summary: |
          The `Class.Sound` to be played.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
  - name: SoundService:SetListener
    summary: |
      Sets the listener used by `Class.Sound|Sounds`.
    description: |
      Sets the listener type for any `Class.Sound|Sounds` in the experience,
      which defines the point from which `Class.Sound` audio in the experience
      is heard by the player. For `Class.Sound|Sounds` parented to a
      `Class.BasePart` or `Class.Attachment`, the listener influences the volume
      and left/right balance of a playing sound. By default, this listener is
      set to `Class.Workspace.CurrentCamera`.

      Note that this does not affect the listener location when using the
      advanced audio system. See `Class.AudioListener` for a way to set the
      listener location in that system.
    code_samples: []
    parameters:
      - name: listenerType
        type: ListenerType
        default:
        summary: |
          The `Enum.ListenerType` of the listener.
      - name: listener
        type: Tuple
        default:
        summary: |
          Dependent on the `Enum.ListenerType`. Use a `Class.BasePart` for
          `Enum.ListenerType.ObjectPosition` or
          `Enum.ListenerType.ObjectCFrame`, a `Datatype.CFrame` for
          `Enum.ListenerType.CFrame`, or `nil` for `Enum.ListenerType.Camera`.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Audio
events: []
callbacks: []