Description

Use it to play music and sounds. Is the shortcut for IAudio.gd, and can be used (from any script) with A (E.g. A.play_music('mx_garage') or E.mx_garage.play()).

It is based on an audio cue system. Each audio file you add to the project should be assigned to a category: music, sfx, voice or ui, for Popochiu to create the corresponding audio cue (AudioCue).

At the moment of writing, audio cues support only one file (clip). In the following versions of the plugin each cue will be able to have more than one clip so developers can add variations to their sounds without needing to code that behavior.

Some things you can do with it:

• Play and stop sounds and music.
• Change the pitch and volume for an AudioCue.

Examples

# Plays "the forest" music, with a fade of 1.5 secs, starting from 1.2 seconds
A.play_music_no_block('mx_forest', 1.5, 1.2)

# Plays the sound effect for opening a door, pausing the array of instructions until the audio finishes playing.
E.run([
  A.play('sfx_door_open'),
  'Player: What is this place?'
])

Or (since version 1.9.0 (no worries, the previous implementation will still work 😉)):

# Plays "the forest" music, with a fade of 1.5 secs, starting from 1.2 seconds
A.mx_forest.play_now(1.5, 1.2)

# Plays the sound effect for opening a door, pausing the array of instructions until the audio finishes playing.
E.run([
  A.sfx_door_open.play(),
  'Player: What is this place?'
])

Properties

Public

• twelfth_root_of_two float. Default pow(2.0, (1.0 / 12.0)). Used to convert a pitch value in semitones to a right value to use when changing the pitch_scale of an AudioStreamPlayer or an AudioStreamPlayer2D. Related to pitch adjustments.

Methods

• change_cue_pitch( String cue_name, float pitch = 0.0 ) void

  Sets to pitch the pitch_scale in the audio stream of the AudioCue identified with cue_name.

• change_cue_volume( String cue_name, float volume = 0.0 ) void

  Sets to volume the volume_db in the audio stream of the AudioCue identified with cue_name.

• get_cue_playback_position( String cue_name ) float

  Returns the playback position of the AudioCue identified by cue_name. If not found, returns -1.0.

• play( String cue_name = '', bool wait_to_end = false, Vector2 position_2d = Vector2.ZERO ) AudioStreamPlayer / AudioStreamPlayer2D

  🍑 Use this to play an AudioCue inside an E.run() (a.k.a. queue of instructions) 🍑

  Plays the AudioCue identified with cue_name when running inside an E.run(). If wait_to_end is true the excecution will pause until the audio clip finishes. You can play the clip from a specific position_2d in the scene if the AudioCue has its is_2d property as true. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio cue.

  # The player character (PC) will say "What is this?" once the audio clip finishes playing.
  yield(E.run([
    C.walk_to_clicked(),
    'Player: Lets see what we can find here.',
    A.play('sfx_locker_open', true),
    'Player: What is this?'
  ]), 'completed')
  

• play_no_block( String cue_name = '', bool wait_to_end = false, Vector2 position_2d = Vector2.ZERO ) AudioStreamPlayer / AudioStreamPlayer2D

  Plays the AudioCue identified with cue_name when running outside an E.run(). If wait_to_end is true the excecution will pause until the audio clip finishes. You can play the clip from a specific position_2d in the scene if the AudioCue has its is_2d property as true. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio cue.

  A.play_no_block('sfx_key')
  

  This is what you'll have to do in order to get the AudioStreamPlayer used to play an AudioCue.

  # Get the AudioStreamPlayer that plays sfx_locker_open
  var asp: AudioStreamPlayer = A.play_no_block('sfx_locker_open')
  
  # Do something with it
  asp.pitch_scale = A.semitone_to_pitch(-5.0)
  

• play_fade( String cue_name = '', float duration = 1.0, bool wait_to_end = false, float from = -80.0, float to = INF, Vector2 position_2d = Vector2.ZERO ) AudioStreamPlayer / AudioStreamPlayer2D

  🍑 Use this to play an AudioCue inside an E.run() (a.k.a. queue of instructions) 🍑

  Same as play() but with a fade that will last duration seconds. You can specify the starting volume with from and the target volume with to. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio cue.

  # Plays sfx_locker_open with a fade of 2 seconds.
  # Won't pause the queue of instructions waiting for the clip to end.
  yield(E.run([
    C.walk_to_clicked(),
    A.play_fade('sfx_turn_on_pc', 2.0),
    'Player: I should not being doing this.'
  ]), 'completed')
  

• play_fade_no_block( String cue_name = '', float duration = 1.0, bool wait_to_end = false, float from = -80.0, float to = INF, Vector2 position_2d = Vector2.ZERO ) AudioStreamPlayer / AudioStreamPlayer2D

  Same as play_no_block() but with a fade that will last duration seconds. You can specify the starting volume with from and the target volume with to. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio cue.

  # Plays sfx_locker_open with a fade of 2 seconds.
  # Will pause the method waiting for the clip to end.
  yield(A.play_fade_no_block('sfx_turn_on_pc', 2.0, true), 'completed')
  
  # Once the sound effect stops playing, characters will say something
  E.run([
    "Player: I'm ready to use this computer now",
    "Popsy: Let's check the email"
  ])
  

• play_music( String cue_name, float fade_duration = 0.0, float music_position = 0.0 ) AudioStreamPlayer / AudioStreamPlayer2D

  🍑 Use this to play an AudioCue inside an E.run() (a.k.a. queue of instructions) 🍑

  Plays the music track named cue_name. It can fade for fade_duration seconds. You can change the track starting position in seconds with music_position. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio track.

  func on_room_transition_finished() -> void:
    E.run([
      A.play_music('mx_classic', 1.5),
      A.play('sfx_intro),
      "Player: I like this music..."
    ])
  

• play_music_no_block( String cue_name, float fade_duration = 0.0, float music_position = 0.0 ) AudioStreamPlayer / AudioStreamPlayer2D

  Plays the music track named cue_name when running outside an E.run(). It can fade for fade_duration seconds. You can change the track starting position in seconds with music_position. Can be yield.

  It returns the AudioStreamPlayer (or AudioStreamPlayer2D if the AudioCue's is_2d property is true) that plays the audio track.

  func on_interact() -> void:
    A.play_music_no_block('mx_radio_emotion')
  
    E.run([
      "Player: Wait... that radio station",
      '...',
      "Player: Is it Fernando Martínez?"
    ])
  

• semitone_to_pitch( pitch: float ) float

  Transforms pitch to a value that can be used to modify the pitch_scale of an AudioStreamPlayer or an AudioStreamPlayer2D.

• stop( String cue_name, float fade_duration = 0.0 ) void

  🍑 Use this to play an AudioCue inside an E.run() (a.k.a. queue of instructions) 🍑

  Stops the AudioCue with cue_name. Can use a fade that will last fade_duration seconds. Can be yield.

  Use it to stop music too.

  func on_interact() -> void:
    E.run([
      "Player: I'm tired of this shit!!!",
      A.stop('mx_classic'),
      '....',
      "Player: That's better"
    ])
  

• stop_no_block( String cue_name, float fade_duration = 0.0 ) void

  Stops the AudioCue with cue_name. Can use a fade that will last fade_duration seconds. Can be yield.

  Use it to stop music too.

  func on_room_exited() -> void:
    A.stop_no_block('mx_bar', 2.0)
    A.stop_no_block('sfx_bar_ambience', 2.0)