# Module `Sound`

Provides the Sound class, which represents a playing sound effect.

## Class Sound

subtitles.Sound:new (spec, parameters, handle) | Constructor.
subtitles.Sound:get_players () | Checks which players the sound is audible to.
subtitles.Sound:is_in_range_of_player (player) | Checks if this sound is within the player's range.
subtitles.Sound:get_max_distance () | Returns the sound's maximum subtitle distance.
subtitles.Sound:get_duration () | Returns the sound's expected duration
subtitles.Sound:get_description () | Returns the sound's description.
subtitles.Sound:get_name () | Returns the sound's technical name.
subtitles.Sound:get_pos () | Calculates the sound's current position.
subtitles.Sound:get_relative_pos_for_player (player) | Returns the sound's position from the player's perspective.
subtitles.Sound:get_merge_key () | Returns the key to use for merging this sound with other sounds.
subtitles.Sound:is_exempt () | Checks if this sound should be exempt from subtitles.
subtitles.Sound:is_dynamic () | Checks if this sound is dynamically positioned (attached to an object).

## Class Sound

Represents a playing sound effect. Sound objects should be treated as immutable, as they are shared between all players.

subtitles.Sound:new (spec, parameters, handle)
  Constructor.

  ### Parameters:

  - spec The sound's SimpleSoundSpec, as a table or string.
  - parameters The sound's parameters, or nil.
  - handle The sound's numeric handle, or nil if the sound is ephemeral.
subtitles.Sound:get_players ()
  Checks which players the sound is audible to.

  ### Returns:

  A sequence of player ObjectRefs.
subtitles.Sound:is_in_range_of_player (player)
  Checks if this sound is within the player's range.

  ### Parameters:

  - player The player's ObjectRef.

  ### Returns:

  true if the sound is in range.
subtitles.Sound:get_max_distance ()
  Returns the sound's maximum subtitle distance.

  ### Returns:

  The maximum distance in metres.
subtitles.Sound:get_duration ()
  Returns the sound's expected duration

  ### Returns:

  The duration in seconds.
subtitles.Sound:get_description ()
  Returns the sound's description.

  ### Returns:

  A human-readable description string.
subtitles.Sound:get_name ()
  Returns the sound's technical name.

  ### Returns:

  A sound name string.
subtitles.Sound:get_pos ()
  Calculates the sound's current position. This may change if the sound is attached to an object.

  ### Returns:

  An absolute position vector.
subtitles.Sound:get_relative_pos_for_player (player)
  Returns the sound's position from the player's perspective.

  ### Parameters:

  - player The player's ObjectRef.

  ### Returns:

  A vector relative to the player's position and rotation.
subtitles.Sound:get_merge_key ()
  Returns the key to use for merging this sound with other sounds. Multiple sounds with the same merge key will be merged into a single subtitle.

  ### Returns:

  A table key, or nil to not merge.
subtitles.Sound:is_exempt ()
  Checks if this sound should be exempt from subtitles.

  ### Returns:

  true to disable the subtitle.
subtitles.Sound:is_dynamic ()
  Checks if this sound is dynamically positioned (attached to an object).

  ### Returns:

  true if the sound is dynamic.

generated by LDoc 1.4.6 Last updated 2023-01-14 06:51:17