Updated based on feedback from audio team meeting.

Removed the override flag, changed speaker_mode to allow taking a 'Default' value
(to correspond to using the audio driver speaker_mode). Moved the setting to
audio/general.

Removed the channel remap settings from project settings, and made configuring them
done through exposed methods on AudioServer (get/set_channel_remap).

Author: BuzzLord

doc/classes/AudioServer.xml

@@ -118,6 +118,19 @@
 				[b]Note:[/b] The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on the result of [method get_bus_volume_db].
 			</description>
 		</method>
+		<method name="get_channel_remap" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="output_channel" type="int" />
+			<description>
+				Returns the mapping for the stereo channel index at [param output_channel]. Channel index values correspond to the following stereo channels:
+				- [code]0[/code]: Front left and right
+				- [code]1[/code]: Center and LFE (bass)
+				- [code]2[/code]: Back left and right
+				- [code]3[/code]: Side left and right
+				- [code]-1[/code]: Muted
+				The default is for the [param output_channel] to map to the same corresponding internal stereo channel.
+			</description>
+		</method>
 		<method name="get_driver_name" qualifiers="const">
 			<return type="String" />
 			<description>
@@ -322,6 +335,19 @@
 				[b]Note:[/b] Using this method is equivalent to calling [method set_bus_volume_db] with the result of [method @GlobalScope.linear_to_db] on a value.
 			</description>
 		</method>
+		<method name="set_channel_remap">
+			<return type="void" />
+			<param index="0" name="output_channel" type="int" />
+			<param index="1" name="source_channel" type="int" />
+			<description>
+				Given a stereo channel index [param output_channel], configures the [AudioServer] to map it to the internal channel [param source_channel]. Channel index values correspond to the following stereo channels:
+				- [code]0[/code]: Front left and right
+				- [code]1[/code]: Center and LFE (bass)
+				- [code]2[/code]: Back left and right
+				- [code]3[/code]: Side left and right
+				Setting an output channel to an invalid source channel (e.g. [code]-1[/code]) will mute output from that channel. If the current [method get_speaker_mode] does not use a particular channel, mapping that source channel to an output channel will mute the output channel.
+			</description>
+		</method>
 		<method name="set_enable_tagging_used_audio_streams">
 			<return type="void" />
 			<param index="0" name="enable" type="bool" />

doc/classes/ProjectSettings.xml

@@ -391,29 +391,6 @@
 		<member name="audio/buses/channel_disable_time" type="float" setter="" getter="" default="2.0">
 			Audio buses will disable automatically when sound goes below a given dB threshold for a given time. This saves CPU as effects assigned to that bus will no longer do any processing.
 		</member>
-		<member name="audio/buses/channel_override/override_channels" type="bool" setter="" getter="" default="false">
-			If [code]true[/code], the number of audio channels processed by Godot is set via the Channel Override [code]speaker_mode[/code] instead of the speaker mode of the current audio device.
-			[b]Note:[/b] This setting is intended for debugging, testing, and troubleshooting, and should not be enabled on production builds.
-		</member>
-		<member name="audio/buses/channel_override/remap_channel_0" type="int" setter="" getter="" default="0">
-			Audio channel remapping index for the front left/right speakers (stereo channel 0). This causes the front speakers to play audio from the given stereo channel. Useful for testing different audio device configurations without needing specific hardware.
-			[b]Note:[/b] Channel remapping is only enabled when [code]override_channels[/code] is true.
-		</member>
-		<member name="audio/buses/channel_override/remap_channel_1" type="int" setter="" getter="" default="1">
-			Audio channel remapping index for the center speaker and LFE channel (stereo channel 1). This causes the center speaker (and LFE channel) to play audio from the given stereo channel. Useful for testing different audio device configurations without needing specific hardware.
-			[b]Note:[/b] Channel remapping is only enabled when [code]override_channels[/code] is true.
-		</member>
-		<member name="audio/buses/channel_override/remap_channel_2" type="int" setter="" getter="" default="2">
-			Audio channel remapping index for the rear left/right speakers (stereo channel 2). This causes the rear speakers to play audio from the given stereo channel. Useful for testing different audio device configurations without needing specific hardware.
-			[b]Note:[/b] Channel remapping is only enabled when [code]override_channels[/code] is true.
-		</member>
-		<member name="audio/buses/channel_override/remap_channel_3" type="int" setter="" getter="" default="3">
-			Audio channel remapping index for the side left/right speakers (stereo channel 3). This causes the side speakers to play audio from the given stereo channel. Useful for testing different audio device configurations without needing specific hardware.
-			[b]Note:[/b] Channel remapping is only enabled when [code]override_channels[/code] is true.
-		</member>
-		<member name="audio/buses/channel_override/speaker_mode" type="int" setter="" getter="" default="0">
-			The speaker mode used by Godot when [code]override_channels[/code] is true. Additional channels are muted (e.g. rear speaker channels when set to Stereo speaker mode 0).
-		</member>
 		<member name="audio/buses/default_bus_layout" type="String" setter="" getter="" default="&quot;res://default_bus_layout.tres&quot;">
 			Default [AudioBusLayout] resource file to use in the project, unless overridden by the scene.
 		</member>
@@ -468,6 +445,10 @@
 		<member name="audio/general/ios/session_category" type="int" setter="" getter="" default="0">
 			Sets the [url=https://developer.apple.com/documentation/avfaudio/avaudiosessioncategory]AVAudioSessionCategory[/url] on iOS. Use the [code]Playback[/code] category to get sound output, even if the phone is in silent mode.
 		</member>
+		<member name="audio/general/speaker_mode" type="int" setter="" getter="" default="-1">
+			The speaker mode used internally by Godot. [code]Default[/code] will use the audio drivers speaker mode, while other values will override the internal speaker mode, and thus the number of audio channels, used by the [AudioServer].
+			When the internal speaker mode differs from the drivers speaker mode, audio channels will be muted, ignored, or mapped to the audio drivers channels.
+		</member>
 		<member name="audio/general/text_to_speech" type="bool" setter="" getter="" default="false">
 			If [code]true[/code], text-to-speech support is enabled on startup, otherwise it is enabled first time TTS method is used, see [method DisplayServer.tts_get_voices] and [method DisplayServer.tts_speak].
 			[b]Note:[/b] Enabling TTS can cause addition idle CPU usage and interfere with the sleep mode, so consider disabling it if TTS is not used.

servers/audio_server.cpp

@@ -264,7 +264,7 @@ void AudioServer::_driver_process(int p_frames, int32_t *p_buffer) {
 #endif
 
 	if (channel_count != get_channel_count()) {
-		// Amount of channels changed due to a output_device change, or override_channels/speaker_mode change
+		// Amount of channels changed due to a output_device change, or speaker_mode change
 		// reinitialize the buses channels and buffers
 		init_channels_and_buffers();
 	}
@@ -293,7 +293,7 @@ void AudioServer::_driver_process(int p_frames, int32_t *p_buffer) {
 			// The destination start for data will be the same in all cases.
 			int32_t *dest = &p_buffer[from_buf * (cs * 2) + (k * 2)];
 
-			int rk = override_channels ? override_remap_channel[k] : k;
+			int rk = channel_remap[k];
 
 #ifdef DEBUG_ENABLED
 			if (!debug_mute && rk < mcs && master->channels[rk].active) {
@@ -1506,36 +1506,38 @@ int AudioServer::get_driver_channel_count() const {
 	ERR_FAIL_V(1);
 }
 
-void AudioServer::_project_settings_changed() {
-	override_channels = GLOBAL_GET("audio/buses/channel_override/override_channels");
-	override_speaker_mode = (SpeakerMode) int(GLOBAL_GET("audio/buses/channel_override/speaker_mode"));
-
-	_get_configured_channel_remap();
+void AudioServer::init_channel_remap() {
+	for (int i = 0; i < MAX_CHANNELS_PER_BUS; i++) {
+		channel_remap[i] = i;
+	}
 }
 
-void AudioServer::_get_configured_channel_remap() {
-	bool remap_changed = false;
-	for (int i = 0; i < MAX_CHANNELS_PER_BUS; i++) {
-		const String channel_key = vformat("audio/buses/channel_override/remap_channel_%d", i);
-		int channel = int(GLOBAL_GET(channel_key));
-		if (channel < 0 || channel > MAX_CHANNELS_PER_BUS) {
-			if (override_channels) {
-				WARN_PRINT(vformat("Invalid %s set to source channel %d. Muting channel.",
-						channel_key, channel));
-			}
-			// Source channels outside valid range will get muted.
-			remap_changed = remap_changed || override_remap_channel[i] != MAX_CHANNELS_PER_BUS;
-			override_remap_channel[i] = MAX_CHANNELS_PER_BUS;
-		} else {
-			remap_changed = remap_changed || override_remap_channel[i] != channel;
-			override_remap_channel[i] = channel;
-		}
+void AudioServer::set_channel_remap(int p_output_channel, int p_source_channel) {
+	ERR_FAIL_INDEX_MSG(p_output_channel, MAX_CHANNELS_PER_BUS, "Invalid output channel, out of range");
+	bool remap_changed;
+
+	lock();
+	if (p_source_channel < 0 || p_source_channel > MAX_CHANNELS_PER_BUS) {
+		remap_changed = channel_remap[p_output_channel] != MAX_CHANNELS_PER_BUS;
+
+		// Source channels outside valid range will get muted.
+		channel_remap[p_output_channel] = MAX_CHANNELS_PER_BUS;
+	} else {
+		remap_changed = channel_remap[p_output_channel] != p_source_channel;
+		channel_remap[p_output_channel] = p_source_channel;
 	}
-	if (remap_changed && override_channels) {
-		print_verbose(vformat("AudioServer: override channel remap: [%d, %d, %d, %d]", override_remap_channel[0], override_remap_channel[1], override_remap_channel[2], override_remap_channel[3]))
+	unlock();
+
+	if (remap_changed) {
+		print_verbose(vformat("AudioServer: channel remap changed: output channel [%d] -> source channel [%d]", p_output_channel, channel_remap[p_output_channel]))
 	}
 }
 
+int AudioServer::get_channel_remap(int p_output_channel) const {
+	ERR_FAIL_INDEX_V_MSG(p_output_channel, MAX_CHANNELS_PER_BUS, -1, "Invalid output channel, out of range");
+	return channel_remap[p_output_channel] == MAX_CHANNELS_PER_BUS ? -1 : channel_remap[p_output_channel];
+}
+
 void AudioServer::notify_listener_changed() {
 	for (CallbackItem *ci : listener_changed_callback_list) {
 		ci->callback(ci->userdata);
@@ -1545,11 +1547,7 @@ void AudioServer::notify_listener_changed() {
 void AudioServer::init_channels_and_buffers() {
 	channel_count = get_channel_count();
 
-	if (override_channels) {
-		print_verbose(vformat("AudioServer: initializing %d override stereo channel(s), detected %d device stereo channel(s)", channel_count, get_driver_channel_count()));
-	} else {
-		print_verbose(vformat("AudioServer: initializing %d stereo channel(s)", channel_count));
-	}
+	print_verbose(vformat("AudioServer: Speaker mode set to %s, initializing %d stereo channel(s)", _get_speaker_mode_name(), channel_count));
 
 	temp_buffer.resize(channel_count);
 	mix_buffer.resize(buffer_size + LOOKAHEAD_BUFFER_SIZE);
@@ -1568,17 +1566,11 @@ void AudioServer::init_channels_and_buffers() {
 }
 
 void AudioServer::init() {
-	channel_disable_threshold_db = GLOBAL_DEF_RST(PropertyInfo(Variant::FLOAT, "audio/buses/channel_disable_threshold_db", PROPERTY_HINT_RANGE, "-80,0,0.1,suffix:dB"), -60.0);
+	channel_disable_threshold_db = GLOBAL_DEF(PropertyInfo(Variant::FLOAT, "audio/buses/channel_disable_threshold_db", PROPERTY_HINT_RANGE, "-80,0,0.1,suffix:dB"), -60.0);
 	channel_disable_frames = float(GLOBAL_DEF_RST(PropertyInfo(Variant::FLOAT, "audio/buses/channel_disable_time", PROPERTY_HINT_RANGE, "0,5,0.01,or_greater"), 2.0)) * get_mix_rate();
 
-	override_channels = GLOBAL_DEF("audio/buses/channel_override/override_channels", false);
-	override_speaker_mode = (SpeakerMode) int(GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/buses/channel_override/speaker_mode", PROPERTY_HINT_ENUM, "Stereo,Surround 3.1,Surround 5.1,Surround 7.1"), SpeakerMode::SPEAKER_MODE_STEREO));
-
-	GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/buses/channel_override/remap_channel_0", PROPERTY_HINT_ENUM, "Front Left/Right,Center/LFE,Rear Left/Right,Side Left/Right,Muted"), 0);
-	GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/buses/channel_override/remap_channel_1", PROPERTY_HINT_ENUM, "Front Left/Right,Center/LFE,Rear Left/Right,Side Left/Right,Muted"), 1);
-	GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/buses/channel_override/remap_channel_2", PROPERTY_HINT_ENUM, "Front Left/Right,Center/LFE,Rear Left/Right,Side Left/Right,Muted"), 2);
-	GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/buses/channel_override/remap_channel_3", PROPERTY_HINT_ENUM, "Front Left/Right,Center/LFE,Rear Left/Right,Side Left/Right,Muted"), 3);
-	_get_configured_channel_remap();
+	speaker_mode_config = GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/general/speaker_mode", PROPERTY_HINT_ENUM, "Default:-1,Stereo:0,Surround 3.1:1,Surround 5.1:2,Surround 7.1:3"), -1);
+	init_channel_remap();
 
 	// TODO: Buffer size is hardcoded for now. This would be really nice to have as a project setting because currently it limits audio latency to an absolute minimum of 11ms with default mix rate, but there's some additional work required to make that happen. See TODOs in `_mix_step_for_channel`.
 	// When this becomes a project setting, it should be specified in milliseconds rather than raw sample count, because 512 samples at 192khz is shorter than it is at 48khz, for example.
@@ -1601,7 +1593,14 @@ void AudioServer::init() {
 
 	GLOBAL_DEF_RST(PropertyInfo(Variant::INT, "audio/video/video_delay_compensation_ms", PROPERTY_HINT_RANGE, "-1000,1000,1,suffix:ms"), 0);
 
-	ProjectSettings::get_singleton()->connect("settings_changed", callable_mp(this, &AudioServer::_project_settings_changed));
+	ProjectSettings::get_singleton()->connect("settings_changed", callable_mp(this, &AudioServer::project_settings_changed));
+}
+
+void AudioServer::project_settings_changed() {
+	lock();
+	channel_disable_threshold_db = GLOBAL_GET("audio/buses/channel_disable_threshold_db");
+	speaker_mode_config = GLOBAL_GET("audio/general/speaker_mode");
+	unlock();
 }
 
 void AudioServer::update() {
@@ -1724,10 +1723,33 @@ void AudioServer::unlock() {
 }
 
 AudioServer::SpeakerMode AudioServer::get_speaker_mode() const {
-	if (override_channels) {
-		return override_speaker_mode;
+	switch (speaker_mode_config) {
+		case 0:
+			return SPEAKER_MODE_STEREO;
+		case 1:
+			return SPEAKER_SURROUND_31;
+		case 2:
+			return SPEAKER_SURROUND_51;
+		case 3:
+			return SPEAKER_SURROUND_71;
+		default:
+			return get_driver_speaker_mode();
+	}
+}
+
+String AudioServer::_get_speaker_mode_name() const {
+	switch (speaker_mode_config) {
+		case 0:
+			return "Stereo";
+		case 1:
+			return "Surround 3.1";
+		case 2:
+			return "Surround 5.1";
+		case 3:
+			return "Surround 7.1";
+		default:
+			return "Default";
 	}
-	return get_driver_speaker_mode();
 }
 
 float AudioServer::get_mix_rate() const {
@@ -2062,6 +2084,9 @@ void AudioServer::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_bus_effect_enabled", "bus_idx", "effect_idx", "enabled"), &AudioServer::set_bus_effect_enabled);
 	ClassDB::bind_method(D_METHOD("is_bus_effect_enabled", "bus_idx", "effect_idx"), &AudioServer::is_bus_effect_enabled);
 
+	ClassDB::bind_method(D_METHOD("set_channel_remap", "output_channel", "source_channel"), &AudioServer::set_channel_remap);
+	ClassDB::bind_method(D_METHOD("get_channel_remap", "output_channel"), &AudioServer::get_channel_remap);
+
 	ClassDB::bind_method(D_METHOD("get_bus_peak_volume_left_db", "bus_idx", "channel"), &AudioServer::get_bus_peak_volume_left_db);
 	ClassDB::bind_method(D_METHOD("get_bus_peak_volume_right_db", "bus_idx", "channel"), &AudioServer::get_bus_peak_volume_right_db);
 

servers/audio_server.h

@@ -224,9 +224,8 @@ class AudioServer : public Object {
 	int channel_count = 0;
 	int to_mix = 0;
 
-	bool override_channels = false;
-	SpeakerMode override_speaker_mode = SPEAKER_MODE_STEREO;
-	int override_remap_channel[MAX_CHANNELS_PER_BUS];
+	int speaker_mode_config = -1;
+	int channel_remap[MAX_CHANNELS_PER_BUS];
 
 	float playback_speed_scale = 1.0f;
 
@@ -326,10 +325,12 @@ class AudioServer : public Object {
 
 	void _update_bus_effects(int p_bus);
 
-	void _get_configured_channel_remap();
+	String _get_speaker_mode_name() const;
 
 	static AudioServer *singleton;
 
+	void init_channel_remap();
+
 	void init_channels_and_buffers();
 
 	void _mix_step();
@@ -381,7 +382,7 @@ class AudioServer : public Object {
 	bool get_debug_mute() const;
 #endif // DEBUG_ENABLED
 
-	void _project_settings_changed();
+	void project_settings_changed();
 
 	void set_bus_count(int p_count);
 	int get_bus_count() const;
@@ -432,6 +433,9 @@ class AudioServer : public Object {
 
 	bool is_bus_channel_active(int p_bus, int p_channel) const;
 
+	void set_channel_remap(int p_output_channel, int p_source_channel);
+	int get_channel_remap(int p_output_channel) const;
+
 	void set_playback_speed_scale(float p_scale);
 	float get_playback_speed_scale() const;