Split sounds into local and UI

README.md

@@ -1,4 +1,4 @@
-![SayWhat logo](logo.svg)
+![SayWhat logo](docs/logo.svg)
 
 # Godot Sound Manager
 
@@ -9,32 +9,22 @@ Features:
 - Pooled audio players
 - Handles music crossfades
 - Autodetect probable audio buses for both sounds and music
+- Splits sounds up into UI sounds and local sounds
 
-## Usage
+## Installation
 
-Copy the `sound_manager` directory into your `res://addons/` directory.
+Copy the `addons/sound_manager` directory into a `res://addons/sound_manager` directory.
 
 Enable `SoundManager` in project plugins.
 
-- **`SoundManager.play_sound(resource: AudioStream, override_bus: String = "")`**
+## Documentation
 
-    Play an audio stream. Optionally specify which audio bus you want to use for this sound.
+- [Sound effects](docs/Sounds.md)
+- [Music](docs/music.md)
 
-- **`SoundManager.set_default_sound_bus(bus: String)`**
+## Discord
 
-    Sets the default audio bus used for playing sounds.
-
-- **`SoundManager.play_music(resource: AudioStream, crossfade_duration: int = 0, override_bus: String = "")`**
-
-    Play some music with an optional fade in (or crossfade if something is already playing) and optionally specify which audio bus to use.
-
-- **`SoundManager.stop_music(fade_out_duration: int = 0)`**
-
-    Stop any music that's playing with an optional fade out.
-
-- **`SoundManager.set_default_music_bus(bus: String)`**
-
-    Sets the default audio bus used for playing music.
+[![Join the Discord](docs/discord.png)](https://discord.gg/zwBVQdJchX)
 
 ## Contributors
 

sound_manager/audio_player_pool.gd → addons/sound_manager/audio_player_pool.gd

@@ -18,13 +18,15 @@ func prepare(resource: AudioStream, override_bus: String = "") -> AudioStreamPla
 	var player = get_available_player()
 	player.stream = resource
 	player.volume_db = linear2db(1)
+	player.pitch_scale = 1
 	player.bus = override_bus if override_bus != "" else bus
 	return player
 
 
-func play(resource: AudioStream, override_bus: String = "") -> void:
+func play(resource: AudioStream, override_bus: String = "") -> AudioStreamPlayer:
 	var player = prepare(resource, override_bus)
 	player.play()
+	return player
 
 
 func get_available_player() -> AudioStreamPlayer:

sound_manager/music.gd → addons/sound_manager/music.gd

@@ -14,18 +14,20 @@ func _ready() -> void:
 	add_child(audio_player_pool)
 
 
-func play(resource: AudioStream, crossfade_duration = 0, override_bus: String = "") -> void:
-	if is_already_playing(resource): return
+func play(resource: AudioStream, crossfade_duration = 0, override_bus: String = "") -> AudioStreamPlayer:
+	var player = get_player_with_music(resource)
 
-	# Fading out sounds quicker than fading in in
+	if player != null: return player
+
+	# Fading out sounds is quicker than fading in
 	stop(crossfade_duration * 2)
 
-	var player = audio_player_pool.prepare(resource, override_bus)
+	player = audio_player_pool.prepare(resource, override_bus)
 	if crossfade_duration > 0:
 		audio_player_pool.fade_volume(player, -80, 0, crossfade_duration)
 
-	yield(get_tree(), "idle_frame")
-	player.play()
+	player.call_deferred("play")
+	return player
 
 
 func stop(fade_out_duration: int = 0) -> void:
@@ -34,17 +36,16 @@ func stop(fade_out_duration: int = 0) -> void:
 			player.stop()
 		else:
 			audio_player_pool.fade_volume(player, player.volume_db, -80, fade_out_duration)
-	yield(get_tree(), "idle_frame")
 
 
-func is_already_playing(resource: AudioStream) -> bool:
+func get_player_with_music(resource: AudioStream) -> AudioStreamPlayer:
 	for player in audio_player_pool.busy_players:
 		if player.stream.resource_path == resource.resource_path:
-			return true
-	return false
+			return player
+	return null
 
 
-### SETGET
+### Setget
 
 
 func set_bus(value: String) -> void:

addons/sound_manager/sound_effects.gd

@@ -0,0 +1,38 @@
+extends Node
+
+
+const AudioPlayerPool = preload("res://addons/sound_manager/audio_player_pool.gd")
+
+
+onready var audio_player_pool := AudioPlayerPool.new(["Sounds", "sounds", "SFX"])
+onready var ui_audio_player_pool := AudioPlayerPool.new(["UI", "Interface", "interface", "Sounds", "sounds", "SFX"])
+
+
+var bus: String = "Master" setget set_bus
+var ui_bus: String = "Master" setget set_ui_bus
+
+
+func _ready() -> void:
+	add_child(audio_player_pool)
+
+	bus = audio_player_pool.bus
+	ui_bus = ui_audio_player_pool.bus
+
+
+func play(resource: AudioStream, override_bus: String = "") -> AudioStreamPlayer:
+	return audio_player_pool.play(resource, override_bus)
+
+
+func play_ui(resource: AudioStream, override_bus: String = "") -> AudioStreamPlayer:
+	return ui_audio_player_pool.play(resource, override_bus)
+
+
+### Setget
+
+
+func set_bus(value: String) -> void:
+	audio_player_pool.bus = value
+
+
+func set_ui_bus(value: String) -> void:
+	ui_audio_player_pool.bus = value

sound_manager/sound_manager.gd → addons/sound_manager/sound_manager.gd

@@ -14,21 +14,29 @@ func _ready() -> void:
 	add_child(music)
 
 
-func play_sound(resource: AudioStream, override_bus: String = "") -> void:
-	sound_effects.play(resource, override_bus)
+func play_sound(resource: AudioStream, override_bus: String = "") -> AudioStreamPlayer:
+	return sound_effects.play(resource, override_bus)
+
+
+func play_ui_sound(resource: AudioStream, override_bus: String = "") -> AudioStreamPlayer:
+	return sound_effects.play_ui(resource, override_bus)
 
 
 func set_default_sound_bus(bus: String) -> void:
 	sound_effects.bus = bus
 
 
-func play_music(resource: AudioStream, crossfade_duration: int = 0, override_bus: String = "") -> void:
-	music.play(resource, crossfade_duration, override_bus)
+func set_default_ui_sound_bus(bus: String) -> void:
+	sound_effects.ui_bus = bus
+
+
+func play_music(resource: AudioStream, crossfade_duration: int = 0, override_bus: String = "") -> AudioStreamPlayer:
+	return music.play(resource, crossfade_duration, override_bus)
 
 
 func stop_music(fade_out_duration: int = 0) -> void:
 	music.stop(fade_out_duration)
 
 
 func set_default_music_bus(bus: String) -> void:
-	music.bus = bus
+	music.bus = bus

docs/Music.md

@@ -0,0 +1,15 @@
+# Music
+
+- **`SoundManager.play_music(resource: AudioStream, crossfade_duration: int = 0, override_bus: String = "")`**
+
+    Play some music with an optional fade in (or crossfade if something is already playing) and optionally specify which audio bus to use.
+
+    This returns the `AudioStreamPlayer` that is playing the sound so you can make any other adjustments you need.
+
+- **`SoundManager.stop_music(fade_out_duration: int = 0)`**
+
+    Stop any music that's playing with an optional fade out.
+
+- **`SoundManager.set_default_music_bus(bus: String)`**
+
+    Sets the default audio bus used for playing music.

docs/Sounds.md

@@ -0,0 +1,23 @@
+# Sound effects
+
+Playing sound effects is broken up into playing general sounds (ie. in the game world) and playing user interface sounds. The reasoning behind this is that you might have your audio buses set up to include local modifiers (eg. being underwater) for local sounds where you wouldn't want your UI sounds being affected.
+
+- **`SoundManager.play_sound(resource: AudioStream, override_bus: String = "")`**
+
+    Play an audio stream intended for an action within the game world. Optionally specify which audio bus you want to use for this sound.
+
+    This returns the `AudioStreamPlayer` that is playing the sound so you can adjust the pitch or volume.
+
+- **`SoundManager.play_ui_sound(resource: AudioStream, override_bus: String = "")`**
+
+    Play an audio stream intended for the user interface. Optionally specify which audio bus you want to use for this sound.
+
+    This returns the `AudioStreamPlayer` that is playing the sound so you can adjust the pitch or volume.
+
+- **`SoundManager.set_default_sound_bus(bus: String)`**
+
+    Sets the default audio bus used for playing sounds.
+
+- **`SoundManager.set_default_ui_sound_bus(bus: String)`**
+
+    Sets the default audio bus used for playing UI sounds.