Strip AudioStream WAV/Ogg/MP3 data using placeholders for dedicated server exports

doc/classes/AudioStreamWAV.xml

@@ -11,6 +11,12 @@
 		<link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link>
 	</tutorials>
 	<methods>
+		<method name="create_placeholder" qualifiers="const">
+			<return type="Resource" />
+			<description>
+				Creates a placeholder version of this resource ([PlaceholderAudioStream]).
+			</description>
+		</method>
 		<method name="load_from_buffer" qualifiers="static">
 			<return type="AudioStreamWAV" />
 			<param index="0" name="stream_data" type="PackedByteArray" />

doc/classes/PlaceholderAudioStream.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="PlaceholderAudioStream" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Placeholder class for WAV, Ogg Vorbis or MP3 audio.
+	</brief_description>
+	<description>
+		This class is used when loading a project that uses [AudioStreamWAV], [AudioStreamOggVorbis] or [AudioStreamMP3], if the project was exported in dedicated server mode. In this mode, only the resource reference is kept, with no actual audio data. This allows reducing the exported PCK's size significantly.
+		[b]Note:[/b] This is not intended to be used as an actual resource for audio playback.
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="length" type="float" setter="set_length" getter="get_length" default="0.0">
+			The audio stream's length in seconds.
+		</member>
+		<member name="loop_begin" type="int" setter="set_loop_begin" getter="get_loop_begin" default="0">
+			The loop start point (in number of samples, relative to the beginning of the stream).
+		</member>
+		<member name="loop_end" type="int" setter="set_loop_end" getter="get_loop_end" default="0">
+			The loop end point (in number of samples, relative to the beginning of the stream).
+		</member>
+		<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="PlaceholderAudioStream.LoopMode" default="0">
+			The loop mode.
+		</member>
+		<member name="tags" type="Dictionary" setter="set_tags" getter="get_tags" default="{}">
+			Contains user-defined tags if found in the WAV or Ogg Vorbis data.
+			Commonly used tags include [code]title[/code], [code]artist[/code], [code]album[/code], [code]tracknumber[/code], and [code]date[/code] ([code]date[/code] does not have a standard date format).
+			[b]Note:[/b] No tag is [i]guaranteed[/i] to be present in every file, so make sure to account for the keys not always existing.
+			[b]Note:[/b] Only WAV files using a [code]LIST[/code] chunk with an identifier of [code]INFO[/code] to encode the tags are currently supported.
+		</member>
+	</members>
+	<constants>
+		<constant name="LOOP_DISABLED" value="0" enum="LoopMode">
+			Audio does not loop.
+		</constant>
+		<constant name="LOOP_FORWARD" value="1" enum="LoopMode">
+			Audio loops the data between [member loop_begin] and [member loop_end], playing forward only.
+		</constant>
+		<constant name="LOOP_PINGPONG" value="2" enum="LoopMode">
+			Audio loops the data between [member loop_begin] and [member loop_end], playing back and forth.
+		</constant>
+		<constant name="LOOP_BACKWARD" value="3" enum="LoopMode">
+			Audio loops the data between [member loop_begin] and [member loop_end], playing backward only.
+		</constant>
+	</constants>
+</class>

modules/minimp3/audio_stream_mp3.cpp

@@ -34,6 +34,7 @@
 
 #include "audio_stream_mp3.h"
 #include "core/io/file_access.h"
+#include "scene/resources/placeholder_audio_stream.h"
 
 int AudioStreamPlaybackMP3::_mix_internal(AudioFrame *p_buffer, int p_frames) {
 	if (!active) {
@@ -327,6 +328,14 @@ Ref<AudioStreamMP3> AudioStreamMP3::load_from_file(const String &p_path) {
 	return load_from_buffer(stream_data);
 }
 
+Ref<Resource> AudioStreamMP3::create_placeholder() const {
+	Ref<PlaceholderAudioStream> placeholder;
+	placeholder.instantiate();
+	placeholder->set_length(get_length());
+	placeholder->set_tags(get_tags());
+	return placeholder;
+}
+
 void AudioStreamMP3::_bind_methods() {
 	ClassDB::bind_static_method("AudioStreamMP3", D_METHOD("load_from_buffer", "stream_data"), &AudioStreamMP3::load_from_buffer);
 	ClassDB::bind_static_method("AudioStreamMP3", D_METHOD("load_from_file", "path"), &AudioStreamMP3::load_from_file);
@@ -349,6 +358,8 @@ void AudioStreamMP3::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_bar_beats", "count"), &AudioStreamMP3::set_bar_beats);
 	ClassDB::bind_method(D_METHOD("get_bar_beats"), &AudioStreamMP3::get_bar_beats);
 
+	ClassDB::bind_method(D_METHOD("create_placeholder"), &AudioStreamMP3::create_placeholder);
+
 	ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "data", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NO_EDITOR), "set_data", "get_data");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "bpm", PROPERTY_HINT_RANGE, "0,400,0.01,or_greater"), "set_bpm", "get_bpm");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "beat_count", PROPERTY_HINT_RANGE, "0,512,1,or_greater"), "set_beat_count", "get_beat_count");

modules/minimp3/audio_stream_mp3.h

@@ -147,6 +147,8 @@ class AudioStreamMP3 : public AudioStream {
 
 	virtual void get_parameter_list(List<Parameter> *r_parameters) override;
 
+	virtual Ref<Resource> create_placeholder() const;
+
 	AudioStreamMP3();
 	virtual ~AudioStreamMP3();
 };

modules/minimp3/doc_classes/AudioStreamMP3.xml

@@ -10,6 +10,12 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="create_placeholder" qualifiers="const">
+			<return type="Resource" />
+			<description>
+				Creates a placeholder version of this resource ([PlaceholderAudioStream]).
+			</description>
+		</method>
 		<method name="load_from_buffer" qualifiers="static">
 			<return type="AudioStreamMP3" />
 			<param index="0" name="stream_data" type="PackedByteArray" />

modules/vorbis/audio_stream_ogg_vorbis.cpp

@@ -30,6 +30,7 @@
 
 #include "audio_stream_ogg_vorbis.h"
 #include "core/io/file_access.h"
+#include "scene/resources/placeholder_audio_stream.h"
 
 #include "core/templates/rb_map.h"
 
@@ -703,6 +704,14 @@ Ref<AudioStreamOggVorbis> AudioStreamOggVorbis::load_from_file(const String &p_p
 	return load_from_buffer(stream_data);
 }
 
+Ref<Resource> AudioStreamOggVorbis::create_placeholder() const {
+	Ref<PlaceholderAudioStream> placeholder;
+	placeholder.instantiate();
+	placeholder->set_length(get_length());
+	placeholder->set_tags(get_tags());
+	return placeholder;
+}
+
 void AudioStreamOggVorbis::_bind_methods() {
 	ClassDB::bind_static_method("AudioStreamOggVorbis", D_METHOD("load_from_buffer", "stream_data"), &AudioStreamOggVorbis::load_from_buffer);
 	ClassDB::bind_static_method("AudioStreamOggVorbis", D_METHOD("load_from_file", "path"), &AudioStreamOggVorbis::load_from_file);
@@ -728,6 +737,8 @@ void AudioStreamOggVorbis::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_tags", "tags"), &AudioStreamOggVorbis::set_tags);
 	ClassDB::bind_method(D_METHOD("get_tags"), &AudioStreamOggVorbis::get_tags);
 
+	ClassDB::bind_method(D_METHOD("create_placeholder"), &AudioStreamOggVorbis::create_placeholder);
+
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "packet_sequence", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NO_EDITOR), "set_packet_sequence", "get_packet_sequence");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "bpm", PROPERTY_HINT_RANGE, "0,400,0.01,or_greater"), "set_bpm", "get_bpm");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "beat_count", PROPERTY_HINT_RANGE, "0,512,1,or_greater"), "set_beat_count", "get_beat_count");

modules/vorbis/audio_stream_ogg_vorbis.h

@@ -38,6 +38,7 @@
 #include <vorbis/codec.h>
 
 class AudioStreamOggVorbis;
+class PlaceholderAudioStream;
 
 class AudioStreamPlaybackOggVorbis : public AudioStreamPlaybackResampled {
 	GDCLASS(AudioStreamPlaybackOggVorbis, AudioStreamPlaybackResampled);
@@ -177,6 +178,8 @@ class AudioStreamOggVorbis : public AudioStream {
 	}
 	virtual Ref<AudioSample> generate_sample() const override;
 
+	virtual Ref<Resource> create_placeholder() const;
+
 	AudioStreamOggVorbis();
 	virtual ~AudioStreamOggVorbis();
 };

modules/vorbis/doc_classes/AudioStreamOggVorbis.xml

@@ -10,6 +10,12 @@
 		<link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link>
 	</tutorials>
 	<methods>
+		<method name="create_placeholder" qualifiers="const">
+			<return type="Resource" />
+			<description>
+				Creates a placeholder version of this resource ([PlaceholderAudioStream]).
+			</description>
+		</method>
 		<method name="load_from_buffer" qualifiers="static">
 			<return type="AudioStreamOggVorbis" />
 			<param index="0" name="stream_data" type="PackedByteArray" />

scene/register_scene_types.cpp

@@ -138,6 +138,7 @@
 #include "scene/resources/dpi_texture.h"
 #include "scene/resources/packed_scene.h"
 #include "scene/resources/particle_process_material.h"
+#include "scene/resources/placeholder_audio_stream.h"
 #include "scene/resources/placeholder_textures.h"
 #include "scene/resources/portable_compressed_texture.h"
 #include "scene/resources/resource_format_text.h"
@@ -1116,6 +1117,7 @@ void register_scene_types() {
 	GDREGISTER_CLASS(AudioStreamPlayer);
 	GDREGISTER_CLASS(AudioStreamWAV);
 	GDREGISTER_CLASS(AudioStreamPolyphonic);
+	GDREGISTER_CLASS(PlaceholderAudioStream);
 	GDREGISTER_ABSTRACT_CLASS(AudioStreamPlaybackPolyphonic);
 
 	OS::get_singleton()->yield(); // may take time to init

scene/resources/audio_stream_wav.cpp

@@ -32,6 +32,7 @@
 
 #include "core/io/file_access_memory.h"
 #include "core/io/marshalls.h"
+#include "scene/resources/placeholder_audio_stream.h"
 
 const float TRIM_DB_LIMIT = -50;
 const int TRIM_FADE_OUT_FRAMES = 500;
@@ -1204,6 +1205,14 @@ Ref<AudioStreamWAV> AudioStreamWAV::load_from_file(const String &p_path, const D
 	return load_from_buffer(stream_data, p_options);
 }
 
+Ref<Resource> AudioStreamWAV::create_placeholder() const {
+	Ref<PlaceholderAudioStream> placeholder;
+	placeholder.instantiate();
+	placeholder->set_length(get_length());
+	placeholder->set_tags(get_tags());
+	return placeholder;
+}
+
 void AudioStreamWAV::_bind_methods() {
 	ClassDB::bind_static_method("AudioStreamWAV", D_METHOD("load_from_buffer", "stream_data", "options"), &AudioStreamWAV::load_from_buffer, DEFVAL(Dictionary()));
 	ClassDB::bind_static_method("AudioStreamWAV", D_METHOD("load_from_file", "path", "options"), &AudioStreamWAV::load_from_file, DEFVAL(Dictionary()));
@@ -1234,6 +1243,8 @@ void AudioStreamWAV::_bind_methods() {
 
 	ClassDB::bind_method(D_METHOD("save_to_wav", "path"), &AudioStreamWAV::save_to_wav);
 
+	ClassDB::bind_method(D_METHOD("create_placeholder"), &AudioStreamWAV::create_placeholder);
+
 	ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "data", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NO_EDITOR), "set_data", "get_data");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "format", PROPERTY_HINT_ENUM, "8-Bit,16-Bit,IMA ADPCM,Quite OK Audio"), "set_format", "get_format");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_mode", PROPERTY_HINT_ENUM, "Disabled,Forward,Ping-Pong,Backward"), "set_loop_mode", "get_loop_mode");

scene/resources/audio_stream_wav.h

@@ -171,6 +171,8 @@ class AudioStreamWAV : public AudioStream {
 	}
 	virtual Ref<AudioSample> generate_sample() const override;
 
+	virtual Ref<Resource> create_placeholder() const;
+
 	static void _compress_ima_adpcm(const Vector<float> &p_data, Vector<uint8_t> &r_dst_data) {
 		static const int16_t _ima_adpcm_step_table[89] = {
 			7, 8, 9, 10, 11, 12, 13, 14, 16, 17,